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
| Twilio | MonoPbx |
|---|---|
https://api.twilio.com | https://<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 token | The API key itself (mpbx_k1_...) |
Create an API key in Admin > Settings > Security > Security > API keys with the permissions the calls need:
| Resource | Permission |
|---|---|
| Calls (create, list, update) | calls:control |
| Messages create / list | messaging:write / messaging:read, for the whole company |
| Recordings list | recordings:read |
| TwiML compile | call_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}.
| Call | Notes |
|---|---|
POST /Calls.json | Click-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.json | The live calls you may control. Filters: To, From, Status, PageSize (1 to 100). |
POST /Calls/{CallSid}.json | Status=completed or canceled hangs up. Url, Twiml and Method (redirecting a live call) are refused. |
POST /Messages.json | From must be one of your SMS numbers. Repeat MediaUrl to send an MMS. MessagingServiceSid, StatusCallback and scheduling are refused. Answer: 201 queued. |
GET /Messages.json | The newest messages of the 20 most recent conversations, one page. Filters: To, From, PageSize. |
GET /Recordings.json | Filter CallSid, PageSize at most 100, newest first. media_url points to the native signed-link route. |
POST /TwiML/compile | MonoPbx 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.
| Verb | Supported | Runs as |
|---|---|---|
Say | voice, language, loop | Play of the company prompt tts/<lang>/<hash>.wav |
Play | loop; prompt:<path>, system:<path> or a bare library path | Play |
Gather | numDigits, timeout, finishOnKey, action, nested Say and Play | Collect into the variable Digits |
Dial | a number, <Number>, <Client> (extension), <Queue> (queue extension), timeout, action | Transfer; external numbers go through the dial plan |
Record | maxLength (at most 600 s), playBeep, action | Voicemail into record_mailbox |
Hangup, Reject | reason="busy" | Hang up |
Redirect | flow:<uuid> or an address ending in /flows/<uuid> | Transfer to that flow |
Pause | length (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.
Urlon Calls create is ignored, andTwiml,ApplicationSid,Urlon call update and theactionwebhooks 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.
Sayneeds prompts. The compiler returns the texts. Rendering them into the prompt library is not automatic. Remote media inPlayis not fetched: upload files to the prompt library.- Verbs.
Enqueue,Leave,Conference,Sip,SmsandMessage,ConnectandStream,Pay,Refer, speechGather, simultaneousDialandPlay 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.