Skip to main content

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 deliveryPOST /api/v1/sms/messages, then GET /api/v1/sms/messages/{id} or the sms.sent, sms.delivered and sms.failed events
React to inbound textsA webhook on sms.received
Place a call for a user: their phone rings, then the PBX dials the number as that userPOST /api/v1/call-control/calls
Hold, resume, transfer or hang up live callsThe 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 agentCall flows: POST /api/v1/call-flows, then publish and route a number to it
Fetch recordings and call historyThe recordings and call history routes
Reuse code written for another provider's REST APIThe 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.

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.