Skip to content
Docs menu

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.

View .md

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 an Idempotency-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's gathered or a comms.call.gather webhook.
  • Escalation with fallback. Start a profile such as page (SMS, then a call if nobody acknowledges) with profile instead of channel, follow it with GET /v1/comms/dispatches/{id} and stop it with POST /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 to comms.message.received.
  • An agent that drafts outreach. Connect venom-comms and 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, or comms_message_approve over 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:read to use the tools at all and comms:write to send or add an opt-out. /v1/comms takes 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, and comms:read alone 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