docs
/
AppEngine API

Messaging, phone and SMS

Phone numbers, inbound call routing, SMS keywords and auto-replies, email broadcast and live chat.

Four channels, one set of records. Voice and SMS are provisioned and routed here; email broadcast and live chat sit alongside them. What a caller or texter experiences is defined by a routing record — ivr_routing for calls, sms_routing for texts — and both are edited in the same IVR surface.

Phone and voice

Numbers

GET/phone/numbersJWT
GET/phone/numbers/:phoneIdJWT
GET/phone/availableJWT
POST/phone/numbersJWT
POST/phone/numbers/addJWT
PUT/phone/numbers/:phoneIdJWT
DELETE/phone/numbers/:phoneIdJWT

available searches the provider's inventory; numbers purchases from it. numbers/add registers a number you already own instead of buying one.

POST/phone/setupJWT
GET/phone/verifyJWT
GET/phone/migration/statusJWT

A number can also be nominated for org-wide duty:

GET/phone/systemJWT
POST/phone/systemJWT
DELETE/phone/systemJWT
GET/phone/sms-numberJWT
POST/phone/sms-numberJWT
DELETE/phone/sms-numberJWT

Pointing a number at a flow

POST/phone/numbers/:phoneId/routingJWT

The body is { mode: 'voice' | 'ivr' }, and the mode decides which webhook the provider calls:

ModeProvider posts toBehavior
voice/connect/webhook/twilio/voiceDirect dial to a user, group or client
ivr/connect/webhook/twilio/ivr-menuRuns the IVR flow on the matching ivr_routing

Both webhook endpoints are public — the provider is not authenticated as a user — and return TwiML. Inbound calls match an ivr_routing whose phoneNumbers contains the called number and whose enabled is true; priority (0–100, higher first) breaks ties.

Four ways to answer

routingType on the record picks one:

TypeWhat the caller gets
forwardRings a forwarding group, with an optional greeting first
ai-assistantAn AI receptionist converses, then transfers
simple_menuA DTMF menu — press 1 for sales — with retries and a catch-all
automation_flowA full automation with IVR actions, for conditional logic and payments

The AI assistant reads the same menus and forwardingGroups as simple_menu: option labels become intents, and each menu's aiInstructions adds routing guidance. Configure routing once and switch routingType without rebuilding it.

Forwarding groups

Where calls ring. Defined once on the record, referenced by id from menu options, transfer rules and fallbacks.

StrategyBehavior
simultaneousRing every target at once, first to answer wins
sequentialRing targets one at a time, in order
round-robinRotate who rings first, with the counter persisted between calls

Targets are typed phone (E.164), agent, queue or sip. When nobody answers, fallback decides: voicemail, ai-assistant, automation or hangup. Optional whisper announces the caller to whoever picks up, and screening makes them press a key to accept.

Hours and misses

businessHours selects a different menu or automation per period through menuAssignments / automationAssignments (normalHours, afterHours, holiday). Precedence is off days > holidays > office hours > normal-hours fallback.

missedCallActions fire together when nobody answers — sms back to the caller (with cooldownMinutes), email to a team, lead creation, automation, or a webhook.

Softphone

POST/phone/tokenJWT
GET/phone/user-phonesJWT
GET/phone/voice/appJWT
POST/phone/voice/appJWT
GET/phone/voice/voicesJWT
POST/phone/voice/register-deviceJWT
POST/phone/voice/heartbeatJWT
POST/phone/voice/unregister-deviceJWT
GET/phone/voice/devicesJWT

token mints the client credential a browser or mobile softphone dials with. Registered devices must heartbeat to stay in the presence list, which is what makes agent targets ring.

Datatypes: ivr_routing, sms_routing, phone, call, call_log, message.

SMS

Registration

US long codes must clear A2P 10DLC before they can send.

GET/phone/numbers/sms-status/:phoneIdJWT
GET/phone/numbers/:phoneId/sms-requirementsJWT
POST/phone/numbers/register-sms/:phoneIdJWT
GET/phone/a2p/brandJWT

sms-requirements tells you what the carrier still wants; sms-status tracks the verification.

Inbound routing

An sms_routing record is the SMS counterpart to ivr_routing. Its core is responseFlows, selected by flowAssignments on the same business-hours logic as voice. Each flow can carry an autoReply (with cooldownMinutes), its own keywords, an AI assistant, and forwarding.

Keywords match before the flow runs:

FieldValues
matchTypeexact, contains, startsWith, regex
actionauto-reply, go-to-flow, fill-form, forward-sms, ai-assistant, trigger-automation, create-lead, add-tag, opt-out, opt-in

Opt-out

On by default. STOP, UNSUBSCRIBE, CANCEL, END and QUIT opt a sender out; START, SUBSCRIBE and YES opt them back in. Both lists and both confirmation messages are overridable per record — but leaving opt-out off is a compliance problem, not a feature.

Email

Bulk and transactional email runs through broadcast, with sender domains verified first.

POST/broadcast/:id/sendJWT
POST/broadcast/:id/cancelJWT
POST/broadcast/:id/duplicateJWT
GET/broadcast/:id/reportJWT
GET/broadcast/:id/statsJWT
POST/broadcast/domains/registerJWT
POST/broadcast/domains/register-emailJWT
POST/broadcast/domains/auto-configureJWT
GET/broadcast/domains/status/:domainJWT
GET/broadcast/domains/email-status/:emailJWT
DELETE/broadcast/domains/register/:domainJWT
GET/broadcast/validate/domain/:domainJWT
GET/broadcast/validate/email/:emailJWT
GET/broadcast/healthJWT
POST/broadcast/health/:accountId/checkJWT
GET/broadcast/activityJWT
GET/broadcast/sentJWT
GET/broadcast/statsJWT

health is the deliverability view — a warm domain that starts bouncing shows up here before your open rates do.

Datatypes: email_broadcast, email_account, email_account_health, broadcast_delivery, messagetemplate, subscriber.

Chat

GET/chat/agents/onlineJWT
GET/chat/agents/:email/presenceJWT
POST/chat/agents/:email/statusJWT
GET/chat/customers/onlineJWT
GET/chat/customers/:email/journeyJWT
GET/chat/presence/statsJWT
GET/chat/queueJWT
POST/chat/queueJWT
GET/chat/queue/statsJWT
GET/chat/queue/position/:chatIdJWT
DELETE/chat/queue/:chatIdJWT
GET/chat/sessionsJWT
GET/chat/config/:chatIdJWT
POST/chat/live/:chatId/:userIdJWT
POST/chat/upload/:chatId/:userIdJWT
GET/chat/ice-serversJWT

ice-servers supplies the STUN/TURN configuration for voice and video escalation out of a chat.

Provider connections

Channels are bound to vendors through Connect, which holds the credentials and receives the callbacks — Twilio for voice and SMS, Mailgun, SendGrid and SES for email, WhatsApp for messaging. See Connect.