Phone & Messages API
Send email, SMS and WhatsApp through your own provider accounts, read the delivery log and manage templates and suppressions.
Phone & Messages sends email, SMS and WhatsApp messages — and carries phone calls — through the provider accounts your workspace has connected (for example SendGrid, Twilio or WhatsApp Cloud). AxisIQ does not send for you: the sending, billing and reputation are your provider's. This API sends messages, reads the delivery log, and manages templates and the do-not-contact list.
Connecting a provider account involves secrets, so it is done in the app (Phone & Messages › Channels). The secrets are never returned by the API.
If the Phone & Messages app is switched off in Settings › Apps, these routes answer 404 NOT_FOUND.
Endpoints
Connections and messages are checked against the connection (its key is the resource), so a role can be limited to one mailbox or number. Templates and the do-not-contact list are workspace-wide: they need comms:read or comms:manage on all connections (*).
| Method | Path | Permission | What it does |
|---|---|---|---|
GET |
/orgs/{orgId}/comms/connections |
comms:read |
List connections |
GET |
/orgs/{orgId}/comms/connections/{connId} |
comms:read |
Get a connection |
GET |
/orgs/{orgId}/comms/providers |
comms:read |
Supported providers and the fields each needs |
GET |
/orgs/{orgId}/comms/connections/{connId}/templates |
comms:manage |
Read the provider's own approved templates |
POST |
/orgs/{orgId}/comms/messages |
comms:send |
Send a message |
GET |
/orgs/{orgId}/comms/messages |
comms:read |
The delivery log |
GET · POST |
/orgs/{orgId}/comms/scheduled |
comms:read · comms:send |
Scheduled messages · schedule one |
PUT |
/orgs/{orgId}/comms/scheduled/{id} |
comms:send |
Change a scheduled message's time |
POST |
/orgs/{orgId}/comms/scheduled/{id}/cancel |
comms:send |
Cancel a scheduled message |
GET |
/orgs/{orgId}/comms/messages/{msgId} |
comms:read |
One message |
GET |
/orgs/{orgId}/comms/templates |
comms:read |
List templates (?channel=) |
GET |
/orgs/{orgId}/comms/templates/{tmplId} |
comms:read |
Get a template |
POST · PUT · DELETE |
/orgs/{orgId}/comms/templates[/{tmplId}] |
comms:manage |
Manage templates |
GET |
/orgs/{orgId}/comms/suppressions |
comms:read |
The do-not-contact list |
POST |
/orgs/{orgId}/comms/suppressions |
comms:manage |
Add an address |
DELETE |
/orgs/{orgId}/comms/suppressions/{supId} |
comms:manage |
Remove an address |
GET |
/orgs/{orgId}/comms/inbox |
comms:inbox |
List SMS/WhatsApp conversations |
GET · PATCH |
/orgs/{orgId}/comms/inbox/{convId} |
comms:inbox |
One conversation with its messages · assign, change status, mark read, link a record |
POST |
/orgs/{orgId}/comms/inbox/{convId}/reply |
comms:inbox |
Reply in a conversation |
GET · POST |
/orgs/{orgId}/comms/broadcasts |
comms:read · comms:broadcast |
List broadcasts · create a draft |
POST |
/orgs/{orgId}/comms/broadcasts/preview |
comms:broadcast |
Count who a broadcast would reach |
GET · DELETE |
/orgs/{orgId}/comms/broadcasts/{id} |
comms:read · comms:broadcast |
One broadcast · delete it |
POST |
/orgs/{orgId}/comms/broadcasts/{id}/send · /cancel · /test |
comms:broadcast |
Send or schedule · cancel · send one test copy |
PUT |
/orgs/{orgId}/comms/broadcasts/{id}/schedule |
comms:broadcast |
Move a scheduled broadcast |
Connections can also be created (POST, comms:connect), edited (PUT), tested (POST …/{connId}/test) and deleted (DELETE, answers 204) with comms:manage. List endpoints return a plain array in data.
Connections
{
"id": "0190fa00-…",
"channel": "email",
"provider": "sendgrid",
"provider_label": "SendGrid",
"name": "Billing mail",
"key": "billing-mail",
"from_address": "billing@example.com",
"from_name": "Example Billing",
"enabled": true,
"status": "ok"
}
channel is email, sms or whatsapp. A connection also carries its non-secret config, capabilities, last_checked_at and last_error. Use id when sending through the REST API; the Functions SDK addresses connections by key.
POST /orgs/{orgId}/comms/messages
Queue one message. Permission: comms:send on the connection.
| Field | Type | Required | Notes |
|---|---|---|---|
connection_id |
string | Yes | The connection to send through |
to |
string | One of to or record_id |
An email address or phone number |
record_type, record_id, to_field |
string | Take the recipient from a field of a record, and fill the template from it. You need to be able to read the record | |
template_id |
string | One of a template or a body | A saved template. Its channel must match the connection's |
subject, body_text, body_html |
string | A message written inline instead of using a template | |
data |
object | No | Extra values for the template |
vars |
array of strings | No | Ordered values for providers whose templates take positional variables (WhatsApp) |
curl -s -X POST https://axisiq.co/api/v1/orgs/$ORG/comms/messages \
-H "Authorization: Bearer $AXIS_KEY" -H "Content-Type: application/json" \
-d '{"connection_id": "0190fa00-…", "to": "asha@example.com", "subject": "Your invoice", "body_text": "Hi Asha, invoice INV-1001 is ready."}'
Response 202 Accepted. The message is queued and sent in the background, so the call never waits on the provider.
{
"data": {
"id": "0190fa10-…",
"connection_id": "0190fa00-…",
"channel": "email",
"provider": "sendgrid",
"direction": "outbound",
"to": "asha@example.com",
"from": "billing@example.com",
"subject": "Your invoice",
"status": "queued",
"created_at": "2026-10-04T09:30:00Z"
}
}
Message statuses
| Status | Meaning |
|---|---|
queued |
Accepted, waiting to be sent |
sending |
Being handed to the provider |
sent |
The provider accepted it |
delivered |
The provider confirmed delivery |
read |
The recipient opened or read it (where the provider reports it) |
bounced |
The address could not be reached |
complained |
The recipient reported it as spam |
failed |
The provider refused it. error says why |
suppressed |
Not sent because the address is on the do-not-contact list |
Later statuses arrive from the provider's callbacks, and a status only moves forward: a late delivered never overwrites a bounced. Some providers (SMTP) report nothing back, so their messages stop at sent. To receive callbacks, open the connection in the app and paste the webhook address it shows into your provider's dashboard.
Errors
| Status | Code | When |
|---|---|---|
| 400 | VALIDATION_ERROR |
No recipient, no body or template, template and connection channels differ, connection disabled, bad ids |
| 403 | FORBIDDEN |
The role lacks comms:send on this connection |
| 404 | NOT_FOUND |
No such connection, template or record |
A message to a do-not-contact address is still accepted (202): the returned message has status suppressed.
GET /orgs/{orgId}/comms/messages
Newest first. Returns an array of message objects.
| Parameter | Notes |
|---|---|
channel |
email, sms or whatsapp |
status |
One of the statuses above |
connection_id, record_id |
Filters |
limit |
Default 50, maximum 200 (a value above 200 falls back to 50) |
cursor |
The id of the last message of the previous page |
Message objects also carry body_text, body_html, template_id, record_type, record_id, provider_message_id, error, sent_at and delivered_at where they apply.
Scheduled messages
POST /comms/scheduled takes the same body as POST /comms/messages plus send_at (RFC 3339, 5 minutes to 90 days ahead) and answers 201 with the scheduled row: id, connection_id, channel, to, summary, send_at, status (scheduled, sending, sent, cancelled or failed), message_id once sent, error when not sent. Everything a send checks is checked at once, so a bad message is a 400 now rather than a failure later. Attachments are not accepted.
At send_at the message goes through the normal send as the person who scheduled it, with their permissions read at that moment; if they have left or lost comms:send, the row becomes failed with a reason and nothing is sent. A message is sent at most once.
GET /comms/scheduled lists rows on connections you can read: pending ones soonest first, then the newest 100 finished. PUT /comms/scheduled/{id} with { "send_at": "…" } and POST …/{id}/cancel only act on rows still scheduled.
Templates
A template is a reusable message. Email templates have a subject, body_html and body_text; SMS has body_text; WhatsApp templates are the ones your provider has approved, linked by provider_ref. The text uses the same template language as PDF documents, with record values filled in from record_id, and data for anything extra. HTML values are escaped, so a value from a form cannot inject markup.
POST and PUT take key, name, channel, subject, body_html, body_text, object_type (the record type it is written for), provider_ref, provider_status and language. DELETE answers 204.
The do-not-contact list
Bounces, spam complaints and unsubscribes are added to this list automatically. A message to a listed address is never sent: it is logged with status suppressed, whichever route, flow or function asked for it. POST /comms/suppressions takes channel, address and an optional reason, and answers 204. GET takes channel, limit (default 200, maximum 500) and cursor, and answers an array. DELETE …/suppressions/{supId} answers 204.
A recipient who follows an unsubscribe link from one of your messages sees a confirmation page, and is added to the list when they confirm.
Inbox
A conversation is every SMS or WhatsApp message with one customer number on one connection. You only see conversations on connections you hold comms:inbox on.
GET /comms/inboxtakesview(mine,unassignedorall),status(open,pending,closed),channel,q(name, number or latest message) andbefore(for the next page).GET /comms/inbox/{convId}returns the conversation and a page of its messages (beforefor older ones), each withdirectioninorout.PATCH /comms/inbox/{convId}takes any ofassignee(a member id,""to unassign),status,read,record_type+record_id(you must be able to read the record) andrematch: true(look the number up among your records again).POST …/replytakestext, ortemplate_idwithvars. On WhatsApp, free text is refused more than 24 hours after the customer's last message; send an approved template instead.
Broadcasts
POST /comms/broadcasts creates a draft: name, connection_id, template_id (or config.subject / config.body_text / config.body_html), type_key (the record type), and config with filters (as in the records search), address_field and vars. POST /preview takes the same body and answers {records, reachable, no_address, sample, too_large}; more than 50,000 matching records is refused.
POST …/{id}/send sends now, or at send_at (RFC 3339, up to 90 days ahead) if given. PUT …/{id}/schedule with { "send_at": "…" } moves a broadcast that is still scheduled. POST …/cancel stops messages not yet handed to the provider. POST …/test with to sends one copy, filled from the first matching record. The audience is the records the sender can read, worked out again at send time. WhatsApp broadcasts need a template the provider reports as approved.
Phone calls
A phone line is a connection with channel voice on your own Twilio or Plivo account. Calls are placed and answered in the browser; these routes read the call log and manage what the app needs.
| Method | Path | Permission | What it does |
|---|---|---|---|
GET |
/orgs/{orgId}/comms/calls |
comms:read on the line |
The call log, newest first. Filters: connection, direction (in, out), status (a status, or missed_any for missed + voicemail), contact (E.164), conversation, record_type + record_id, before (a started_at), limit (≤ 100). |
GET |
/orgs/{orgId}/comms/calls/{callId} |
comms:read on the line |
One call and its transcript: { call, transcript: [{ seq, speaker, text, at }] }. speaker is agent, customer, voicemail or call. |
GET |
/orgs/{orgId}/comms/calls/{callId}/recording |
comms:read on the line |
The recording as audio/mpeg. |
PATCH |
/orgs/{orgId}/comms/calls/{callId} |
comms:call on the line |
Set note, or link the call to a record with record_type + record_id (record_id: "" removes the link). |
POST |
/orgs/{orgId}/comms/calls/{callId}/summary |
comms:read on the line |
Write an AI summary from the transcript. Uses AI credit: 402 LIMIT_EXCEEDED when it has run out. |
GET |
/orgs/{orgId}/comms/connections/{connId}/routing |
comms:read on the line |
The line's call routing and who is available now (online user ids). |
PUT |
/orgs/{orgId}/comms/connections/{connId}/routing |
comms:manage on the line |
Replace the call routing. |
A call looks like:
{
"id": "01a1…",
"connection_id": "01a0…",
"direction": "in",
"from": "+919845012345",
"to": "+918047182290",
"contact": "+919845012345",
"status": "completed",
"agent": "0190…",
"route": "Sales",
"started_at": "2026-10-23T05:30:00Z",
"answered_at": "2026-10-23T05:30:08Z",
"ended_at": "2026-10-23T05:35:20Z",
"duration": 312,
"recording": "stored",
"recording_seconds": 312,
"summary": "Asked for a quote on 40 office chairs…"
}
status is one of queued, ringing, in_progress, completed, missed, voicemail, no_answer, busy, failed, canceled. duration is the talk time in seconds.
Call routing:
{
"language": "en-IN",
"greeting": "Thanks for calling Example Retail Co.",
"menu_prompt": "Press 1 for sales. Press 2 for support.",
"menu": [
{ "digit": "1", "label": "Sales", "ring": { "strategy": "round_robin", "members": ["0190…"], "timeout": 20 } },
{ "digit": "2", "label": "Address", "ring": { "strategy": "all", "members": [], "timeout": 25 }, "message": "We are at 12 MG Road." }
],
"ring": { "strategy": "all", "members": [], "timeout": 25 },
"hours": { "zone": "Asia/Kolkata", "days": [[], [{ "from": "10:00", "to": "20:00" }], [], [], [], [], []] },
"closed_message": "We are closed right now.",
"voicemail": true,
"voicemail_prompt": "",
"record": true,
"record_notice": "This call may be recorded.",
"transcribe": true
}
hours.days[0] is Sunday; leave hours out for always open. An empty members list rings everyone with comms:call on the line. Making and answering calls happens in the app's softphone, not through this API.
Related
- Functions SDK:
axis.comms.send - Flows: the send-message block
- In the product: Phone & Messages