Programmable voice and SMS
Your PBX is also a programmable voice and messaging platform. The same REST API the console uses lets your own software send and receive texts, place and control calls, build menus and react to every call event, on your own numbers and your own carrier accounts.
No per-minute or per-message markup. Calls go out over your own SIP trunks and messages through your own SMS provider account, at the prices you agreed with them. MonoPbx adds no fee per minute, per message or per API call.
What you can build
| You want to... | Use |
|---|---|
| Send an SMS or MMS from a company number and follow its delivery | POST /api/v1/sms/messages, then GET /api/v1/sms/messages/{id} or the sms.sent, sms.delivered and sms.failed events |
| React to inbound texts | A webhook on sms.received |
| Place a call for a user: their phone rings, then the PBX dials the number as that user | POST /api/v1/call-control/calls |
| Hold, resume, transfer or hang up live calls | The call-control routes |
| React to calls as they happen (ringing, answered, transferred, ended) | A webhook on call.*, or the events WebSocket |
| Answer calls with your own menu, queue logic or AI agent | Call flows: POST /api/v1/call-flows, then publish and route a number to it |
| Fetch recordings and call history | The recordings and call history routes |
| Reuse code written for another provider's REST API | The compatible API |
Every call keeps the PBX rules: the dial plan, calling permissions, toll-fraud limits, department reach and the audit trail apply exactly as on a phone. Emergency numbers are never dialled through the API.
Credentials
Create an API key in Admin > Settings > Security > Security > API keys and give it only the scopes your code needs (messaging:write to send texts, integrations:write for webhooks, calls:control to place and control calls). Send it as Authorization: Bearer <key>. See API getting started for the conventions (pagination, Idempotency-Key, errors).
Examples
HTTP
curl -sS https://pbx.example.com/api/v1/sms/messages \
-H "Authorization: Bearer $MPBX_API_KEY" \
-H "Idempotency-Key: order-1042-confirmation" \
-H 'Content-Type: application/json' \
-d '{"from": "+15550100001", "to": "+15550100100", "body": "Your order 1042 is on its way"}'
The answer is 202 with the message in state queued. Repeat the same request with the same Idempotency-Key after a timeout and no second message is sent.
Python
The client libraries are generated from the OpenAPI document and have no dependencies besides the language.
from mpbx_sdk import MonoPbx
pbx = MonoPbx("https://pbx.example.com", token=os.environ["MPBX_API_KEY"])
msg = pbx.api.sms.send_sms({"from": "+15550100001", "to": "+15550100100", "body": "Hello"},
idempotency_key="greeting-42")
print(pbx.api.sms.get_sms_message(msg["id"])["status"])
hook = pbx.api.webhooks.create_webhook_endpoint(
{"name": "crm", "url": "https://crm.example.com/hooks/pbx", "event_types": ["sms.received", "call.*"]})
# Store hook["secret"]: it is shown once and verifies every delivery.
call = pbx.api.call_control.originate_call({"user_id": AGENT_ID, "destination": "+15550100100"})
TypeScript
import { MonoPbx } from '@mpbx/sdk';
const pbx = new MonoPbx({ baseUrl: 'https://pbx.example.com', token: process.env.MPBX_API_KEY });
const msg = await pbx.api.sms.sendSms(
{ body: { from: '+15550100001', to: '+15550100100', body: 'Hello' } },
{ idempotencyKey: 'greeting-42' },
);
const call = await pbx.api.callControl.originateCall({ body: { user_id: agentId, destination: '+15550100100' } });
Complete, runnable examples are in sdk/python/examples/voice_sms.py and sdk/typescript/examples/voice-sms.ts of the source tree.
Receive events
Webhook deliveries are signed POST requests with the Standard Webhooks headers (webhook-id, webhook-timestamp, webhook-signature), so any Standard Webhooks library verifies them with the endpoint's secret. Deliveries are retried with backoff and kept as dead letters when your receiver stays down. See Webhooks.
Menus and call logic
A call flow is a graph of steps (play, collect digits, menu, transfer, queue, voicemail, AI agent, conditions). Build one in the flow editor or send the graph to POST /api/v1/call-flows, publish it, and route a number to it. Flows run inside the PBX: no web server of yours has to answer during a call, so a call never waits on your network.
Moving existing code
If you have code written for another provider's REST API, the compatible API answers the most common calls in that provider's request and response shapes and compiles its markup into call flows. Change the base URL and the credentials, then move to the native routes above when you need more.