Build on Venom Comms
Send messages and place phone calls from your app or an agent. Text people on SMS, WhatsApp, RCS, Telegram or email, run fallback profiles, read conversations and follow replies over the Comms API or MCP.
Venom Comms sends messages and places calls through the providers your org configured (Settings, Comms). Apps use the
Comms API under /v1/comms with an org API key. Agents use the comms_* MCP tools, where a person approves each send
unless a profile allows agents. The tools also have a REST twin under /api/v1/comms (one route per tool, the same
arguments), for scripts that act as an agent rather than as an application.
What you can build
- Notifications from your app. Send an SMS, WhatsApp, RCS, Telegram or email message (
POST /v1/comms/messages) with anIdempotency-Key, so a retry never sends twice. - Phone confirmations. Place a call that reads a script and listens for a key press (
POST /v1/comms/calls), then read the digits from the call'sgatheredor acomms.call.gatherwebhook. - Escalation with fallback. Start a profile such as
page(SMS, then a call if nobody acknowledges) withprofileinstead ofchannel, follow it withGET /v1/comms/dispatches/{id}and stop it withPOST /v1/comms/dispatches/{id}/ack. - A reply handler. Read inbound messages from the event feed (
GET /v1/comms/events?after=<cursor>) or subscribe a webhook tocomms.message.received. - An agent that drafts outreach. Connect
venom-commsand let an agent read a conversation (comms_conversation_get) and ask to send a reply (comms_message_send); a person approves it before it goes out. - Opt-out sync. Push your own unsubscribe list into Comms (
POST /v1/comms/optouts), so no product contacts those people. - Approvals from your phone or chat. Show an owner the sends waiting (
GET /v1/comms/messages?status=pending_approval) and let them approve or reject each one (POST /v1/comms/messages/{id}/approve,…/reject, orcomms_message_approveover MCP).
At a glance
Generated from the code on every docs build.
| MCP endpoint | https://cloud.usevenom.dev/workspace/mcp/comms, server name venom-comms |
| Connect | claude mcp add --transport http venom-comms https://cloud.usevenom.dev/workspace/mcp/comms |
| MCP tools | 27 (13 read, 14 write) |
| OAuth scopes | comms:read comms:write |
| REST twin | 27 routes under https://cloud.usevenom.dev/api/v1 |
| Comms API | 28 operations |
| Webhook events | comms.message.received, comms.message.status, comms.call.answered, comms.call.gather, comms.call.ended, comms.call.status, comms.dispatch.acknowledged |
Authentication and scopes
Comms treats an app and an agent differently:
- An API key on
/v1/comms(vck_…, personal or team) is an application your org made. Its sends go out at once, subject to opt-outs, quiet hours and the org's per-minute limit. It cannot change Comms settings, and it can lift only the opt-outs that the API added. - An API key on MCP is an agent. It may read and ask to send. A service agent that an admin made read-only, or scoped to other apps, is refused in words.
- An OAuth app is an agent too. It needs
comms:readto use the tools at all andcomms:writeto send or add an opt-out./v1/commstakes its token as well, when the token was issued for the workspace (/workspace/mcp) with comms scopes: it is still an agent there, so its sends wait for approval, andcomms:readalone only reads.
What happens to an agent's send:
| The call | Result |
|---|---|
comms_message_send or comms_call_place with a channel or a script |
stored with status pending_approval; it goes out when a person approves it in Settings, Comms, or is canceled if they reject it |
With a profile an admin opened to agents ("Agents may send without approval") |
goes out at once |
With any other profile |
refused: 403 approval_required, with a message that names the profile |
Approving from another app
A person can approve or reject a waiting send without opening the console: POST /v1/comms/messages/{id}/approve or
…/reject (and /v1/comms/calls/{id}/…), or the tools comms_message_approve, comms_message_reject,
comms_call_approve and comms_call_reject (/api/v1/comms/messages/{message}/approve on the twin). The rule is the
console's, plus one:
- The credential is a person's: an OAuth app with
comms:write, or the member's own personal API key. A team or service key is refused, because no person stands behind it. - The member's role manages Comms (owner or admin). Developers, billing members and viewers are refused.
- An agent never approves its own send. The credential that asked is refused, and so is every other credential of the same member (their other OAuth apps and personal keys), so an approval always takes a second party.
Approving sends the message (or places the call) at once and answers it; rejecting sets it canceled. A send that is
no longer waiting answers 404. Each decision is in the audit log (comms.approved, comms.rejected) with the
approver as actor.
An opted-out contact gets status blocked and is never contacted. A non-urgent send in the recipient's quiet hours is
scheduled until they end. Profiles and who may use them are on Profiles.
Worked example
Text a customer that their order shipped, safe to retry, then read its status:
curl -X POST "$VENOM_CLOUD/v1/comms/messages" \
-H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \
-H 'Idempotency-Key: order-4411-shipped' \
-d '{"to": "+15551234567", "channel": "sms", "body": "Your order 4411 shipped.", "subject": "order:4411"}'
curl "$VENOM_CLOUD/v1/comms/messages/<message-id>" \
-H "Authorization: Bearer $VENOM_API_KEY"The first call answers 201 with the message; status moves from queued through sent to delivered. Over MCP,
from a client connected to /workspace/mcp/comms, the same send waits for a person:
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call",
"params": { "name": "comms_message_send",
"arguments": { "to": "+15551234567", "channel": "sms", "body": "Your order 4411 shipped.", "idempotency_key": "order-4411-shipped" } } }The answer says "Asked to send" and the message's status is pending_approval. Read it later with
comms_message_get and its message id.
Without a provider, sends answer 409 comms_not_configured. To try the flow first, add the fake provider in Settings,
Comms and drive replies with POST /v1/comms/simulate (The Comms API).
Errors worth handling
| Status, code | What to do |
|---|---|
409 comms_not_configured |
the org has no enabled provider for that channel: add one in Settings, Comms |
409 no_sender |
the provider has no sender for that channel |
400 whatsapp_template_required |
WhatsApp outside the 24-hour window: send an approved template (GET /v1/comms/templates) |
403 approval_required |
an agent named a profile that is not open to agents |
429 rate_limit_exceeded |
over the org's per-minute limit for messages and calls together; wait for retry-after |
Events
7 org webhook events, generated from lib/webhooks/events.ts. Subscribe an endpoint to them in Settings, Webhooks (see Webhooks and events).
| Event | When |
|---|---|
comms.message.received |
Someone wrote to one of the org's numbers (Venom Comms): the channel, the sender, the conversation and the text, plus what it asked for (ack, escalate, STOP). |
comms.message.status |
A message sent through Venom Comms changed status (sent, delivered, read, failed), with the provider's reason on a failure. |
comms.call.answered |
A call placed through Venom Comms was answered. |
comms.call.gather |
The person on a Venom Comms call pressed keys at a gather step: the step's name and the digits. |
comms.call.ended |
A Venom Comms call ended: its result, duration and cost. |
comms.call.status |
A Venom Comms call changed status (ringing, failed, busy, no answer). |
comms.dispatch.acknowledged |
Someone acknowledged a Venom Comms profile run (a reply of 1 or ack, or key 1 on the call): no further steps go out. |
The same events are a feed: GET /v1/comms/events?after=<cursor> returns them oldest first, in the envelope the
webhooks carry, except that the feed has an inbound message's body and the webhook has only its length. Pass
next_cursor back as after. See The Comms API.
REST routes
The REST twin: 27 routes under https://cloud.usevenom.dev/api/v1, each calling the MCP tool named in its row with the same arguments (see the REST twin).
/comms/messages
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/comms/messages |
Recent messages, newest first | comms_message_list |
| POST | /api/v1/comms/messages |
Send a message on a channel, or run a profile (an agent's send waits for a person's approval unless the profile allows agents) | comms_message_send |
| GET | /api/v1/comms/messages/{message} |
One message and its delivery status | comms_message_get |
| POST | /api/v1/comms/messages/{message}/approve |
A person sends an agent's pending message (owner or admin; never the credential that asked) | comms_message_approve |
| POST | /api/v1/comms/messages/{message}/reject |
A person cancels an agent's pending message (owner or admin; never the credential that asked) | comms_message_reject |
/comms/calls
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/comms/calls |
Recent calls, newest first | comms_call_list |
| POST | /api/v1/comms/calls |
Call a person with a short script, or run a profile (an agent's call waits for approval unless the profile allows agents) | comms_call_place |
| GET | /api/v1/comms/calls/{call} |
One call: status, duration, cost and the digits pressed | comms_call_get |
| POST | /api/v1/comms/calls/{call}/approve |
A person places an agent's pending call (owner or admin; never the credential that asked) | comms_call_approve |
| POST | /api/v1/comms/calls/{call}/reject |
A person cancels an agent's pending call (owner or admin; never the credential that asked) | comms_call_reject |
/comms/conversations
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/comms/conversations |
Threads with contacts, newest first | comms_conversation_list |
| GET | /api/v1/comms/conversations/{conversation} |
One thread with its messages and calls | comms_conversation_get |
| POST | /api/v1/comms/conversations/{conversation}/read |
Mark the contact's messages read (WhatsApp's blue ticks) | comms_receipt_send |
/comms/senders
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/comms/senders |
The org's numbers and sender ids | comms_sender_list |
| POST | /api/v1/comms/senders |
Add a number or sender id (a person whose role manages Comms) | comms_sender_add |
| DELETE | /api/v1/comms/senders/{sender} |
Remove a sender (a person whose role manages Comms) | comms_sender_delete |
/comms/templates
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/comms/templates |
Message templates and their approval state | comms_template_list |
/comms/profiles
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/comms/profiles |
Routing profiles and whether agents may use them | comms_profile_list |
/comms/optouts
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/comms/optouts |
Contacts who must not be messaged or called | comms_optout_list |
| POST | /api/v1/comms/optouts |
Stop all messages and calls to a contact (or one channel) | comms_optout_add |
/comms/dispatches
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/comms/dispatches/{dispatch} |
One profile run: its steps and who acknowledged it | comms_dispatch_get |
/comms/settings
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/comms/settings |
Quiet hours, time zone, send limit and call voice | comms_setting_get |
| PATCH | /api/v1/comms/settings |
Change quiet hours, time zone, send limit or call voice (a person whose role manages Comms) | comms_setting_update |
/comms/providers
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/comms/providers |
Providers and mailboxes, without secrets or webhook URLs (a person whose role manages Comms) | comms_provider_list |
| PATCH | /api/v1/comms/providers/{provider} |
Enable, disable, rename or reorder a provider (a person whose role manages Comms) | comms_provider_update |
| DELETE | /api/v1/comms/providers/{provider} |
Remove a provider or mailbox (a person whose role manages Comms) | comms_provider_delete |
| POST | /api/v1/comms/providers/{provider}/test |
Sign in to a mailbox and check its domain's DNS (a person whose role manages Comms) | comms_mailbox_test |
Also the Comms API: 28 operations, generated from services/nodejs-cloud/contracts/comms-openapi.yaml. "Key or token" is a Venom API key or an OAuth access token; SDK keys and client ids belong to an environment and are for your app's runtime.
/v1/comms
| Method | Path | Summary | Auth |
|---|---|---|---|
| GET | /v1/comms/messages |
Recent messages, newest first | key or token |
| POST | /v1/comms/messages |
Send a message on a channel, or start a routing profile | key or token |
| GET | /v1/comms/messages/{id} |
key or token | |
| POST | /v1/comms/messages/{id}/approve |
Send an agent's pending message | key or token |
| POST | /v1/comms/messages/{id}/reject |
Cancel an agent's pending message | key or token |
| GET | /v1/comms/calls |
key or token | |
| POST | /v1/comms/calls |
Place a call that plays a script, or start a routing profile | key or token |
| GET | /v1/comms/calls/{id} |
key or token | |
| POST | /v1/comms/calls/{id}/approve |
Place an agent's pending call | key or token |
| POST | /v1/comms/calls/{id}/reject |
Cancel an agent's pending call | key or token |
| GET | /v1/comms/conversations |
Threads (one per channel and contact), newest first | key or token |
| GET | /v1/comms/conversations/{id} |
key or token | |
| GET | /v1/comms/senders |
The org's numbers and sender ids | key or token |
| GET | /v1/comms/templates |
Message templates and their approval state (WhatsApp outside the 24-hour window sends an approved one) | key or token |
| POST | /v1/comms/templates/sync |
Read the providers' templates and their approval state again | key or token |
| GET | /v1/comms/profiles |
Routing profiles, the org's and the built-in page, support and notify | key or token |
| GET | /v1/comms/optouts |
key or token | |
| POST | /v1/comms/optouts |
Record that a contact must not be contacted on a channel (or any, "*") | key or token |
| DELETE | /v1/comms/optouts |
Lift an opt-out an API key added (a person lifts any in the console) | key or token |
| GET | /v1/comms/dispatches/{id} |
A profile run and where it is | key or token |
| POST | /v1/comms/dispatches/{id}/ack |
Acknowledge a profile run so no further steps go out | key or token |
| GET | /v1/comms/events |
The event feed after a cursor, oldest first | key or token |
| POST | /v1/comms/simulate |
Apply a fake provider's callback (fake providers only) | key or token |
/api
| Method | Path | Summary | Auth |
|---|---|---|---|
| POST | /api/integrations/comms/line/session |
Venom Line, the media bridge exchanges a call's ticket for a session (not for API clients) | none |
| POST | /api/integrations/comms/line/tools |
Venom Line, one of the line's tools for a live call's agent (not for API clients) | none |
| POST | /api/integrations/comms/line/report |
Venom Line, a call's transcript and measured latencies once it ends (not for API clients) | none |
| POST | /api/integrations/comms/{provider}/{token}/{route} |
A provider's callback (not for API clients) | none |
| GET | /api/integrations/comms/{provider}/{token}/tts/{call}/{step} |
A call step spoken in the org's own TTS voice (fetched by the provider) | none |
The /api/integrations/comms/… routes are provider callbacks and Venom Line's own; your app does not call them.
Field-by-field reference, call script steps and statuses: The Comms API.
MCP tools
27 tools: 13 read, 14 write. Generated from the code; "write (destructive)" is the tool's destructiveHint. A tool with a REST route is the same call over HTTP.
| Tool | Title | Access | Scope | REST route |
|---|---|---|---|---|
comms_call_approve |
Approve a pending call | write | comms:write |
POST /api/v1/comms/calls/{call}/approve |
comms_call_get |
Read a call | read | comms:read |
GET /api/v1/comms/calls/{call} |
comms_call_list |
List calls | read | comms:read |
GET /api/v1/comms/calls |
comms_call_place |
Place a phone call | write | comms:write |
POST /api/v1/comms/calls |
comms_call_reject |
Reject a pending call | write (destructive) | comms:write |
POST /api/v1/comms/calls/{call}/reject |
comms_conversation_get |
Read a conversation | read | comms:read |
GET /api/v1/comms/conversations/{conversation} |
comms_conversation_list |
List conversations | read | comms:read |
GET /api/v1/comms/conversations |
comms_dispatch_get |
Read a dispatch | read | comms:read |
GET /api/v1/comms/dispatches/{dispatch} |
comms_mailbox_test |
Test a mailbox | write | comms:write |
POST /api/v1/comms/providers/{provider}/test |
comms_message_approve |
Approve a pending message | write | comms:write |
POST /api/v1/comms/messages/{message}/approve |
comms_message_get |
Read a message | read | comms:read |
GET /api/v1/comms/messages/{message} |
comms_message_list |
List messages | read | comms:read |
GET /api/v1/comms/messages |
comms_message_reject |
Reject a pending message | write (destructive) | comms:write |
POST /api/v1/comms/messages/{message}/reject |
comms_message_send |
Send a message | write | comms:write |
POST /api/v1/comms/messages |
comms_optout_add |
Opt a contact out | write | comms:write |
POST /api/v1/comms/optouts |
comms_optout_list |
List opt-outs | read | comms:read |
GET /api/v1/comms/optouts |
comms_profile_list |
List profiles | read | comms:read |
GET /api/v1/comms/profiles |
comms_provider_delete |
Remove a provider | write (destructive) | comms:write |
DELETE /api/v1/comms/providers/{provider} |
comms_provider_list |
List providers | read | comms:read |
GET /api/v1/comms/providers |
comms_provider_update |
Enable, disable or rename a provider | write | comms:write |
PATCH /api/v1/comms/providers/{provider} |
comms_receipt_send |
Mark a conversation read | write | comms:write |
POST /api/v1/comms/conversations/{conversation}/read |
comms_sender_add |
Add a sender | write | comms:write |
POST /api/v1/comms/senders |
comms_sender_delete |
Remove a sender | write (destructive) | comms:write |
DELETE /api/v1/comms/senders/{sender} |
comms_sender_list |
List senders | read | comms:read |
GET /api/v1/comms/senders |
comms_setting_get |
Read Comms settings | read | comms:read |
GET /api/v1/comms/settings |
comms_setting_update |
Change Comms settings | write | comms:write |
PATCH /api/v1/comms/settings |
comms_template_list |
List message templates | read | comms:read |
GET /api/v1/comms/templates |