Telephony
These routes manage phone calls over SIP. Viewers on a project can read its trunks and numbers. Developers and admins can change them and place calls. A phone call is a voice session: read it, hang it up or transfer it with the voice session routes.
| Method and path | Who | What it does |
|---|---|---|
GET /sip/install | any signed-in user | Whether the SIP gateway is deployed, where carriers point (host and port), the digest realm and the codecs. |
GET /projects/{project_id}/sip/trunks | viewer | The project's trunks. Passwords are never returned, only whether one is set. |
POST /projects/{project_id}/sip/trunks | developer or admin | Add a trunk. See below. |
PATCH /projects/{project_id}/sip/trunks/{trunk_id} | developer or admin | Change a trunk. |
PUT /projects/{project_id}/sip/trunks/{trunk_id}/credentials | developer or admin | {"inbound_password", "outbound_password"}. null removes one. Stored in Vault. |
DELETE /projects/{project_id}/sip/trunks/{trunk_id} | developer or admin | Remove a trunk. |
GET /projects/{project_id}/sip/numbers | viewer | The project's numbers and the agents that answer them. |
POST /projects/{project_id}/sip/numbers | developer or admin | Add a number. See below. |
PATCH /projects/{project_id}/sip/numbers/{number_id} | developer or admin | Change a number. |
DELETE /projects/{project_id}/sip/numbers/{number_id} | developer or admin | Remove a number. |
POST /projects/{project_id}/sip/calls | developer or admin | Place an outbound call. |
GET /tenants/{tenant_id}/call-recording | organization member | The organization's recording consent and retention. |
PUT /tenants/{tenant_id}/call-recording | organization admin | {"consent": true, "retention_days": 30}. Retention is 1 to 365 days. |
Trunk fields
| Field | What it is |
|---|---|
name | A label. |
inbound_auth | ip, digest or none (outbound only). |
allowed_cidrs | For ip: the carrier's signalling addresses. |
inbound_username, inbound_password | For digest: the username (unique on the install) and password your PBX uses. |
outbound_host, outbound_port, outbound_transport | Where outbound calls go: host, port and udp or tcp. |
outbound_username, outbound_password | Optional credentials the carrier asks for. |
caller_ids | The caller IDs the trunk may present. |
codecs | The trunk's codecs. |
max_concurrent_calls | The trunk's channel limit. |
enabled | Whether the trunk is in use. |
Number fields
| Field | What it is |
|---|---|
number | The phone number. |
trunk_id | The trunk it arrives on. |
agent_name | The agent that answers. |
language | The call language, otherwise the agent's voice settings. |
greeting | The first sentence, up to 500 characters. Default: an AI disclosure. |
record | Record calls, when the organization consents. |
transfer_targets | [{"name": "billing", "number": "+971..."}]: the only places the agent may send a caller. |
max_call_seconds | The longest a call may last. |
enabled | Whether the number answers. |
Place a call
POST
/projects/{project_id}/sip/callsBody
tostringrequiredThe number to dial.
number_idstringoptionalCall from this number: its trunk, agent, language, greeting and recording apply.
trunk_idstringoptionalOr call from this trunk, with
agent_name.agent_namestringoptionalThe agent, when calling from a trunk.
caller_idstringoptionalOne of the trunk's caller IDs.
languagestringoptionalOverride the call language.
greetingstringoptionalOverride the greeting.
recordbooleanoptionalOverride recording. Still needs the organization's consent.
max_ring_secondsintegeroptional5 to 120. Default 45.
Responses
201
The call was started. The body is the voice session. Its
call_status follows the call: ringing, answered, busy, no answer, rejected or failed.403
The licence doesn't include voice.
409
The install has no SIP gateway, or the trunk has no outbound host or is disabled.
422
The body is incomplete: send
number_id, or trunk_id and agent_name. Or the caller ID isn't one of the trunk's.429
The trunk is at its channel limit, or a budget refused the call.
502
The SIP gateway didn't take the call.
503
No voice capacity is free.
Was this page helpful?