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.
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_minafter 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.