The Comms API
Send messages and place calls with /v1/comms and an org API key; read conversations and events; manage opt-outs; and the comms_* MCP tools for agents.
/v1/comms takes an org API key (vck_…) in Authorization: Bearer, like the rest of /v1. Errors come back in
the same shape as the model API ({"error": {"type", "code", "message", "param"}}). Lists are
{"object": "list", "data": [...], "has_more", "next_cursor"}; pass cursor for the next page.
A key is an application your org made, so its sends go out without approval. Agents use the MCP tools instead.
An OAuth access token issued for the workspace (/workspace/mcp) with comms:read (and comms:write to send) works
here too; it acts as an agent, so its sends wait for a person's approval like the tools'.
Messages
POST /v1/comms/messages sends one message:
curl https://cloud.example.com/v1/comms/messages \
-H "Authorization: Bearer $VENOM_KEY" -H "Idempotency-Key: order-4411-shipped" \
-H "content-type: application/json" \
-d '{"to": "+15551234567", "channel": "sms", "body": "Your order shipped."}'| Field | |
|---|---|
to |
the number in international form (+ and digits), a Telegram chat id, an email address on email, or a Telegram @username or number on telegram_user |
channel |
sms, whatsapp, rcs, telegram, email (Email) or telegram_user (Telegram from your own account). Give this or profile |
profile |
a profile name: its first step goes now, the rest follow on their own |
body |
up to 1,600 characters, or 4,000 on email |
email |
the email channel only: {"subject", "in_reply_to"}. subject is required (up to 300 characters); in_reply_to is a Comms message id to answer in its thread. An email takes no media or template |
media |
[{"url", "type"}], on channels that take media |
template |
{"name", "language", "params"}: a template approved at the provider (WhatsApp outside the 24-hour window) |
from |
a sender address; otherwise the default sender for the channel and the number's country |
conversation_id |
reply in an existing conversation |
subject |
your own label (say order:4411); acknowledgements and events carry it |
recipient_tz |
the recipient's IANA zone for quiet hours; otherwise guessed from the number |
script |
the call script a profile's call step plays |
idempotency_key |
or the Idempotency-Key header: the same key returns the first message instead of sending again |
The answer is 201 with the message. status is where it is: queued, sending, sent, delivered, read,
failed, scheduled (held for quiet hours or a retry), blocked (the recipient opted out), pending_approval,
canceled, or received for an inbound one. segments and cost_usd say what it cost.
GET /v1/comms/messages lists the newest first (status, conversation_id, limit, cursor), and
GET /v1/comms/messages/{id} reads one.
Calls
POST /v1/comms/calls places a call that runs a script:
{
"to": "+15551234567",
"script": [
{"op": "say", "text": "Your table at Lumen is ready."},
{"op": "gather", "prompt": "Press 1 to confirm, 2 to cancel.", "digits": 1, "timeout_s": 8, "name": "confirm"},
{"op": "hangup"}
]
}| Step | |
|---|---|
say |
text, optional voice and locale |
play |
an audio url |
gather |
a prompt, how many digits (default 1), timeout_s, a name reported with the digits |
pause |
seconds |
transfer |
to: connect the call to another number |
hangup |
end the call |
At most 30 steps. Give profile instead of script to start a profile whose first step is a call. The call comes back
with status (queued, ringing, answered, completed, busy, no_answer, failed, …), gathered
([{"name", "digits"}]), duration_s and cost_usd. GET /v1/comms/calls and GET /v1/comms/calls/{id} read them.
Conversations, senders and profiles
GET /v1/comms/conversationslists threads, newest first (channel,contact). One conversation is a contact, a sender and a channel, both directions.session_opensays whether WhatsApp's 24-hour window is open.GET /v1/comms/conversations/{id}reads one with its messages and calls.GET /v1/comms/senderslists your numbers and sender ids.GET /v1/comms/templateslists message templates with their approval state (channel,statusfilters);POST /v1/comms/templates/syncreads them from the providers again. WhatsApp outside its 24-hour window sends anapprovedone (Support and People).GET /v1/comms/profileslists your profiles and the built-in ones.
Profile runs
A send or call with a profile starts a dispatch: the message or call carries its dispatch_id.
GET /v1/comms/dispatches/{id}says which step it is on, when the next one goes and whether someone acknowledged.POST /v1/comms/dispatches/{id}/ackacknowledges it, so no further step goes out. A reply of 1 or "ack" and key 1 on a call do the same.
Opt-outs
GET /v1/comms/optoutslists them (contactto filter).POST /v1/comms/optoutswith{"contact", "channel", "note"}adds one (channel*means every channel).DELETE /v1/comms/optouts?contact=…&channel=…lifts one that the API added. A STOP the person sent is lifted only by their START or by a person in the console.
A STOP reply adds one by itself; see Compliance.
Events
Every inbound message, status change, answered or ended call, key press and acknowledgement is an event:
{
"object": "comms.event", "id": "…", "type": "message.received", "created_at": "2026-11-08T09:12:44Z",
"provider": "<provider id>", "message_id": "…", "call_id": null, "conversation_id": "…", "dispatch_id": "…",
"subject": "order:4411",
"data": {"channel": "sms", "from": "+15551234567", "to": "+15557654321", "body": "1", "intent": "ack"}
}Types: message.received, message.status, call.answered, call.ended, call.gather, call.status,
dispatch.acknowledged. Read them with GET /v1/comms/events?after=<cursor> (the cursor is the last page's
next_cursor), or subscribe an org webhook to comms.message.received, comms.call.gather and the rest (Settings,
Webhooks): they are signed and retried like every other webhook event.
Trying it without a provider
POST /v1/comms/simulate makes the fake provider report something, as if a person had done it:
{"type": "message.received", "from": "+15551234567", "body": "STOP"}; message.status with a message_id you sent
through it and a status; or call.answered, call.gather (with digits) and call.ended with a call_id. A message.received may also carry channel, to (the sender it arrived at, which Support and People route on), name, media ([{"url", "type", "name"}]) and a shared contact, and a repeated event_id shows a provider's retry applied once. It
answers 409 no_fake_provider unless the org has an enabled fake provider. This is how the tests and
make cloud-dev drive Comms.
Errors worth handling
| Status, code | |
|---|---|
409 comms_not_configured |
the org has no enabled provider for that channel |
409 no_sender |
the provider has no sender for that channel |
400 invalid_request |
a bad number, an alphanumeric sender to a country that refuses one, a script step out of range |
429 rate_limit_exceeded |
over the org's per-minute limit; wait for retry-after |
For agents (MCP)
Agents use the Comms MCP server, /workspace/mcp/comms (server venom-comms), with an OAuth grant (comms:read to
read, comms:write to send) or an org API key. Connect it like the other products (Settings, Connect an agent). The
full generated tool list, scopes and webhook events are on Build on Venom Comms.
| Tool | |
|---|---|
comms_message_send |
a message on a channel, or a profile |
comms_call_place |
a call with a script, or a profile |
comms_message_get, comms_message_list |
messages and their status |
comms_call_get, comms_call_list |
calls, their duration, cost and digits |
comms_dispatch_get |
one profile run: its steps, the step it is on and who acknowledged it |
comms_conversation_list, comms_conversation_get |
threads with contacts |
comms_sender_list, comms_profile_list, comms_template_list |
what the org can send from and with, and the templates it may use outside WhatsApp's window |
comms_optout_list, comms_optout_add |
opt-outs; an agent can add one but never lift one |
comms_message_approve, comms_message_reject, comms_call_approve, comms_call_reject |
a person approves or rejects a waiting send (owner or admin; never the credential that asked) |
comms_setting_get, comms_setting_update |
quiet hours, time zone, the per-minute send limit and the call voice (changing them: owner or admin) |
comms_provider_list, comms_provider_update, comms_provider_delete |
providers and mailboxes: list, turn on or off, rename, reorder, remove (owner or admin; never their secrets or webhook URLs) |
comms_mailbox_test |
sign in to a mailbox and check its domain's SPF, DKIM and DMARC (owner or admin) |
comms_sender_add, comms_sender_delete |
the numbers and sender ids the org sends from (owner or admin) |
An agent never has the last word on contacting a person. Its message or call on a channel is stored as
pending_approval and goes out only when someone approves it on the Comms settings page, or from another app with
POST /v1/comms/messages/{id}/approve or POST /v1/comms/messages/{id}/reject (for a call, POST /v1/comms/calls/{id}/approve
or POST /v1/comms/calls/{id}/reject), or the approve tools. Only
a person's credential (an OAuth app with comms:write or their own personal key) whose role manages Comms may, and
never the credential that asked nor another of the same member's (Approving from another app).
The Settings, Comms tools (comms_provider_*, comms_mailbox_test, comms_sender_add, comms_sender_delete,
comms_setting_update) take the same person's credential whose role manages Comms (an OAuth app with comms:write,
or a personal key), as the settings page's org:manage; a team or service key is refused. Some changes stay on the
settings page only: entering or reading a provider's, mailbox's or Venom Line's credentials, saving a profile (its
Agents may send without approval switch decides which agent sends skip approval), lifting an opt-out and linking
your own Telegram.
With a profile, only a profile an admin marked Agents may send without approval goes out at once; any other profile is refused with a message that says so.
The tools also have a REST twin under /api/v1/comms (for example POST /api/v1/comms/messages,
POST /api/v1/comms/messages/{message}/approve), with the same credentials as /workspace/mcp.