---
title: The Comms API
description: "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."
section: comms
order: 10
audience: [builder, agent]
sources: [services/nodejs-cloud/app/v1/comms, services/nodejs-cloud/lib/comms/http.ts, services/nodejs-cloud/lib/comms/mcp.ts, services/nodejs-cloud/lib/mcp/rest.ts, services/nodejs-cloud/contracts/comms.ts, services/nodejs-cloud/contracts/comms-v1.schema.json]
features: [cloud.v1-comms]
---

`/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](#mcp) 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:

```bash
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](/docs/comms/email.md)) or `telegram_user` ([Telegram from your own account](/docs/comms/telegram-personal.md)). Give this or `profile` |
| `profile` | a [profile](/docs/comms/profiles.md) 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:

```json
{
  "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](/docs/comms/support-and-people.md#support)).
- `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](/docs/comms/compliance.md).

## Events

Every inbound message, status change, answered or ended call, key press and acknowledgement is an event:

```json
{
  "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) {#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](/docs/developers/comms.md).

| 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](/docs/developers/comms.md#approve)).
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`.
