Skip to main content

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 pathWhoWhat it does
GET /sip/installany signed-in userWhether the SIP gateway is deployed, where carriers point (host and port), the digest realm and the codecs.
GET /projects/{project_id}/sip/trunksviewerThe project's trunks. Passwords are never returned, only whether one is set.
POST /projects/{project_id}/sip/trunksdeveloper or adminAdd a trunk. See below.
PATCH /projects/{project_id}/sip/trunks/{trunk_id}developer or adminChange a trunk.
PUT /projects/{project_id}/sip/trunks/{trunk_id}/credentialsdeveloper or admin{"inbound_password", "outbound_password"}. null removes one. Stored in Vault.
DELETE /projects/{project_id}/sip/trunks/{trunk_id}developer or adminRemove a trunk.
GET /projects/{project_id}/sip/numbersviewerThe project's numbers and the agents that answer them.
POST /projects/{project_id}/sip/numbersdeveloper or adminAdd a number. See below.
PATCH /projects/{project_id}/sip/numbers/{number_id}developer or adminChange a number.
DELETE /projects/{project_id}/sip/numbers/{number_id}developer or adminRemove a number.
POST /projects/{project_id}/sip/callsdeveloper or adminPlace an outbound call.
GET /tenants/{tenant_id}/call-recordingorganization memberThe organization's recording consent and retention.
PUT /tenants/{tenant_id}/call-recordingorganization admin{"consent": true, "retention_days": 30}. Retention is 1 to 365 days.

Trunk fields​

FieldWhat it is
nameA label.
inbound_authip, digest or none (outbound only).
allowed_cidrsFor ip: the carrier's signalling addresses.
inbound_username, inbound_passwordFor digest: the username (unique on the install) and password your PBX uses.
outbound_host, outbound_port, outbound_transportWhere outbound calls go: host, port and udp or tcp.
outbound_username, outbound_passwordOptional credentials the carrier asks for.
caller_idsThe caller IDs the trunk may present.
codecsThe trunk's codecs.
max_concurrent_callsThe trunk's channel limit.
enabledWhether the trunk is in use.

Number fields​

FieldWhat it is
numberThe phone number.
trunk_idThe trunk it arrives on.
agent_nameThe agent that answers.
languageThe call language, otherwise the agent's voice settings.
greetingThe first sentence, up to 500 characters. Default: an AI disclosure.
recordRecord calls, when the organization consents.
transfer_targets[{"name": "billing", "number": "+971..."}]: the only places the agent may send a caller.
max_call_secondsThe longest a call may last.
enabledWhether the number answers.

Place a call​

POST/projects/{project_id}/sip/calls

Body​

tostringrequired
The number to dial.
number_idstringoptional
Call from this number: its trunk, agent, language, greeting and recording apply.
trunk_idstringoptional
Or call from this trunk, with agent_name.
agent_namestringoptional
The agent, when calling from a trunk.
caller_idstringoptional
One of the trunk's caller IDs.
languagestringoptional
Override the call language.
greetingstringoptional
Override the greeting.
recordbooleanoptional
Override recording. Still needs the organization's consent.
max_ring_secondsintegeroptional
5 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?
On this page
Talk to our teamQuestions about licensing or sizing VoisX Orchestrate for your site? We can help.Talk to sales →