Messaging
Contacts, conversations, messages, media and templates. The resources behind sending and reading customer messages.
The API reference is generated from the running API's own specification and lists every field of every operation below.
The model
| Resource | What it is |
|---|---|
| Connection | One connected channel account: a WhatsApp number, an inbox. Live. |
| Contact | A person, merged across channels. One contact can have a WhatsApp number, an email address and an Instagram handle. |
| Identity | One way to reach a contact: a channel plus the id on it, such as whatsapp + +447700900123. |
| Conversation | A contact on one connection: a thread with a status, an assignee and tags. |
| Message | One item in a conversation: inbound or outbound, text, media, template or interactive. |
| Media | A file you upload with POST /v2/media to send. A file already on a message (one a customer sent, or one you sent) is downloaded through that message. |
| Template | An approved WhatsApp message template. |
Endpoints
| Endpoint | Scope | |
|---|---|---|
POST /v2/messages | messages:write | Send a message |
GET /v2/messages/{id} | messages:read | One message |
GET /v2/messages/{id}/status-history | messages:read | Its delivery history |
GET /v2/messages/{id}/attachments/{index} | messages:read | A short-lived download link for a file on a message |
GET /v2/conversations | conversations:read | List conversations |
GET /v2/conversations/{id} | conversations:read | One conversation |
PATCH /v2/conversations/{id} | conversations:write | Status, assignee, team, topic, tags, priority |
POST /v2/conversations/{id}/read | conversations:write | Mark read |
GET /v2/conversations/{id}/messages | messages:read | A conversation's messages |
POST /v2/conversations/{id}/notes | conversations:write | Add an internal note |
GET /v2/contacts, POST /v2/contacts | contacts:read, contacts:write | List, create |
GET, PATCH /v2/contacts/{id} | contacts:read, contacts:write | One contact |
DELETE /v2/contacts/{id} | contacts:write + the member's erasure right | Erase a contact (GDPR, irreversible). See Contacts |
PUT /v2/contacts/by-identity/{channel}/{externalId} | contacts:write | Create or update by channel identity |
GET, POST /v2/contacts/{id}/identities, DELETE …/identities/{identityId} | contacts:read, contacts:write | A contact's handles |
POST /v2/contacts/{id}/tags, DELETE …/tags/{tag} | contacts:write | Tag, untag |
POST /v2/contacts/{id}/merge | contacts:write | Merge another contact into this one |
POST /v2/media | media:write | Get an upload URL |
GET /v2/media/{id} | media:read | Get a short-lived download URL |
GET /v2/templates, GET /v2/templates/{id} | templates:read | WhatsApp templates |
Which keys can call them
Every messaging endpoint needs a live key that is not pinned to an App. A test key gets
403 forbidden with reason sandbox_key_not_supported, and a key pinned to an App gets
403 forbidden with reason key_pinned_to_projects: these endpoints read and write real customer
data that belongs to no single App. The one exception is GET /v2/templates, which a test key may
read. See Test keys.
Visibility
A key sees what its member sees in the console. For conversations and messages, that is the member's own, their team's, or all, depending on their role. Contacts are visible workspace-wide to anyone with contact access, as in the console. See Keys belong to a person.
Sent as you, marked as the API
A message sent with a key is sent as the key's member and appears in the console like any other reply, marked as sent through the API. API sends do not count as a person taking over from the AI assistant.