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/inbox takes view (mine, unassigned or all), status (open, pending, closed), channel, q (name, number or latest message) and before (for the next page).
  • GET /comms/inbox/{convId} returns the conversation and a page of its messages (before for older ones), each with direction in or out.
  • PATCH /comms/inbox/{convId} takes any of assignee (a member id, "" to unassign), status, read, record_type + record_id (you must be able to read the record) and rematch: true (look the number up among your records again).
  • POST …/reply takes text, or template_id with vars. 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.