Skip to main content

Twilio-compatible API

For new code, use the native routes described in Programmable voice and SMS. This page is for moving existing code. MonoPbx answers the most common Twilio REST calls with Twilio's request and response shapes, and compiles a subset of TwiML into a call flow. Code written for Twilio can move by changing the base URL and the credentials. What is outside the subset is refused with an error, never silently ignored, except the Url parameter of Calls create (see below).

The reference is in the OpenAPI document under the tag twilio-compat.

Credentials and base URL​

TwilioMonoPbx
https://api.twilio.comhttps://<your PBX>/api/v1/twilio
Account SID (AC...)AC followed by the id of an API key: 32 hex digits without dashes. It is the third part of the key mpbx_k1_<company>_<id>_<secret>.
Auth tokenThe API key itself (mpbx_k1_...)

Create an API key in Admin > Settings > Security > Security > API keys with the permissions the calls need:

ResourcePermission
Calls (create, list, update)calls:control
Messages create / listmessaging:write / messaging:read, for the whole company
Recordings listrecordings:read
TwiML compilecall_flows:read

Send the credentials as HTTP Basic, as the Twilio SDKs do. The key as an Authorization: Bearer token also works. The Account SID must match the key, and the Account SID in the path must be your own, otherwise the answer is 404 (20404). A key never does more than its owner may. Department reach, rate limits, the toll-fraud gate and the audit trail apply as on the native API. MonoPbx never sends a WWW-Authenticate challenge.

curl -u "AC$KEY_ID:$MPBX_API_KEY" \
https://pbx.example.com/api/v1/twilio/2010-04-01/Accounts/AC$KEY_ID/Messages.json \
--data-urlencode "To=+15550100100" --data-urlencode "From=+15550100001" \
--data-urlencode "Body=Hello"

With an SDK, point its HTTP client at the new base URL. Bodies are application/x-www-form-urlencoded.

Resources​

All paths are under /api/v1/twilio/2010-04-01/Accounts/{AccountSid}.

CallNotes
POST /Calls.jsonClick-to-call. From is the extension number of a user. That user's devices ring first, then To is dialled as that user through the dial plan. Url is accepted and ignored. Twiml, ApplicationSid and machine detection are refused. Answer: 201 with status=queued.
GET /Calls.jsonThe live calls you may control. Filters: To, From, Status, PageSize (1 to 100).
POST /Calls/{CallSid}.jsonStatus=completed or canceled hangs up. Url, Twiml and Method (redirecting a live call) are refused.
POST /Messages.jsonFrom must be one of your SMS numbers. Repeat MediaUrl to send an MMS. MessagingServiceSid, StatusCallback and scheduling are refused. Answer: 201 queued.
GET /Messages.jsonThe newest messages of the 20 most recent conversations, one page. Filters: To, From, PageSize.
GET /Recordings.jsonFilter CallSid, PageSize at most 100, newest first. media_url points to the native signed-link route.
POST /TwiML/compileMonoPbx only. Compiles TwiML into a call-flow graph.

SIDs are CA + the call id, SM + the message id and RE + the recording id, each a UUID without dashes. Times are RFC 2822, as on Twilio.

Errors use Twilio's body {code, message, more_info, status} plus mpbx_code, the native MonoPbx code. Codes: 20003 (credentials), 20403 (forbidden), 20404 (not found), 20429 (rate limited), 21200 (invalid or unsupported parameter), 20503 (service not configured), 12100 (TwiML parse error) and 12200 (TwiML outside the subset).

TwiML subset​

POST /TwiML/compile takes JSON {"twiml": "<Response>...</Response>", "record_mailbox": "101"} and returns {graph, tts}: a call-flow graph and the Say texts. Nothing is stored. Save the graph with the call-flow API and publish it. A number or an IVR can then route to it like any other flow.

VerbSupportedRuns as
Sayvoice, language, loopPlay of the company prompt tts/<lang>/<hash>.wav
Playloop; prompt:<path>, system:<path> or a bare library pathPlay
GathernumDigits, timeout, finishOnKey, action, nested Say and PlayCollect into the variable Digits
Diala number, <Number>, <Client> (extension), <Queue> (queue extension), timeout, actionTransfer; external numbers go through the dial plan
RecordmaxLength (at most 600 s), playBeep, actionVoicemail into record_mailbox
Hangup, Rejectreason="busy"Hang up
Redirectflow:<uuid> or an address ending in /flows/<uuid>Transfer to that flow
Pauselength (1 to 60 s)Waits

After the last verb the call hangs up. An action and a Redirect must name a call flow of your company. MonoPbx never fetches TwiML from your web server during a call.

Gaps​

  • TwiML at run time. Url on Calls create is ignored, and Twiml, ApplicationSid, Url on call update and the action webhooks Twilio calls are not supported. Compile your TwiML and publish it as a flow.
  • Outbound calls that run TwiML when answered. Calls create is click-to-call: a user's phone rings first.
  • Say needs prompts. The compiler returns the texts. Rendering them into the prompt library is not automatic. Remote media in Play is not fetched: upload files to the prompt library.
  • Verbs. Enqueue, Leave, Conference, Sip, Sms and Message, Connect and Stream, Pay, Refer, speech Gather, simultaneous Dial and Play digits.
  • REST. StatusCallback (use webhooks or the events WebSocket), MessagingServiceSid, scheduled messages, machine detection, SendDigits, paging beyond the first page, ended calls in the Calls list (use the call history API), and fetching or deleting a single resource.

Twilio and TwiML are trademarks of their respective owner. MonoPbx is not affiliated with, endorsed or sponsored by it. The names are used only to say which existing code this layer accepts.