Skip to content
Docs menu

Comms profiles

Routing with fallback for messages and calls: the built-in page, support and notify profiles, your own chains, acknowledgements, and which profiles agents may use.

View .md

A profile says how to reach someone, in order, with fallback. It is to messages what a gear is to models: callers name the profile, not the channel, and an admin changes the chain in one place.

A profile is 1 to 6 steps. Each step has a channel (sms, whatsapp, rcs, telegram or voice), after_min (minutes after the previous step) and optionally on:

  • no on: the step always runs, after_min after the previous one;
  • on: "unacked": it runs only if nobody acknowledged by then;
  • on: "failed": it runs only if the previous step failed (an undeliverable WhatsApp message, say).

Built-in profiles

Profile Steps Urgent
page SMS now, then a phone call after 5 minutes unless acknowledged yes
support WhatsApp, else SMS when WhatsApp fails no
notify one SMS, held until morning during quiet hours no

Add your own on the Comms settings page (Profiles), or save one with the name of a built-in to change it for your org. Urgent profiles ignore quiet hours; each time they do, the audit log says so. Nothing ignores an opt-out.

Running a profile

Send with "profile": "page" (POST /v1/comms/messages, or POST /v1/comms/calls when the first step is a call). The first step goes at once and the rest are scheduled: the dispatch in the answer's dispatch_id tracks them. The message steps send body; a call step reads script, or the body followed by a hang-up.

A dispatch is acknowledged when the person replies 1 or "ack", presses 1 on a call, or your app calls POST /v1/comms/dispatches/{id}/ack. No further step goes out, and a dispatch.acknowledged event carries your subject. A reply of 2 or "escalate" is reported with intent: "escalate" for your app to act on.

Steps run on the cloud's sweep, about once a minute, so a step can go out up to a minute after its time.

A dispatch whose last step is a message is marked done an hour after that step went out (a reply of 1 or "ack" inside that hour still acknowledges it, a later one does not). A dispatch that ends on a call is done when the call ends.

Agents

An agent (the comms_* MCP tools) may start only a profile marked Agents may send without approval; any other profile is refused, and a single message or call on a channel waits for a person's approval. Keep agent profiles narrow: a notify-like profile to the customer's own number is a good candidate, a page to a whole team is not.