Skip to content
Docs menu

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.

View .md

/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/conversations lists threads, newest first (channel, contact). One conversation is a contact, a sender and a channel, both directions. session_open says whether WhatsApp's 24-hour window is open.
  • GET /v1/comms/conversations/{id} reads one with its messages and calls.
  • GET /v1/comms/senders lists your numbers and sender ids.
  • GET /v1/comms/templates lists message templates with their approval state (channel, status filters); POST /v1/comms/templates/sync reads them from the providers again. WhatsApp outside its 24-hour window sends an approved one (Support and People).
  • GET /v1/comms/profiles lists 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}/ack acknowledges 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/optouts lists them (contact to filter).
  • POST /v1/comms/optouts with {"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.