Voice Services

Inbound calls

You have two options for handling inbound calls:

Static call forwarding
Dynamic call forwarding

Static call forwarding

Set a fixed forwarding destination for a phone number with the GET /v1/Phones/{phone}/voice endpoint. The callsForwardedTo parameter accepts an E.164 phone number or a SIP URI.

Dynamic call forwarding

If you don't set static forwarding for a number, we default to dynamic call forwarding. We send you a webhook every time an inbound call reaches that number.

Handling inbound calls with dynamic forwarding

The InboundCallReceivedWebhook fires to the URL set on the corresponding Webhook Subscription whenever an inbound call arrives. See the Webhooks article for more on Webhook Subscriptions.

Respond to this webhook with a Call Script telling us how to handle the call. Supported scripts:

Forward the call: <Response><Dial>+1234567890</Dial></Response>
Forward to SIP: <Response><Dial>sip:username@server.com</Dial></Response>
Forward and override recording behavior: <Response><Dial Record="true">+1234567890</Dial></Response>
Play a Text-to-Speech message, then hang up: <Response><Hangup>The number you have dialed is currently out of service.</Hangup></Response>
Hang up directly: <Response><Hangup/></Response>

If we don't get a response, or the response is invalid, we hang up the call automatically.

How inbound call forwarding works

The inbound call reaches Telgorithm as the first call leg. We check the number's forwarding settings to decide between static and dynamic forwarding.
We start the second call leg to the forwarding destination, using the same caller ID as the first leg. This destination is the internal party, such as your call desk agent.
Once the internal party answers, we join both legs. The call ends when either party hangs up, or when you call the Hang Up API endpoint.

Outbound calls

Initiate calls programmatically with the POST /v1/Calls endpoint. The from and to parameters both accept E.164 phone numbers or SIP URIs.

How outbound calls work

We start the first call leg by calling from your caller ID to the destination in from. That destination is the internal party, such as your call desk agent.
Once the internal party answers, and optionally presses a key to acknowledge, we start the second call leg from your caller ID to the destination in to: the external party you're trying to reach.
Once the external party answers, we join both legs. The call ends when either party hangs up, or when you call the Hang Up API endpoint, the same as an inbound call.

SIP configuration reference

These settings apply to both static and dynamic SIP forwarding.

IP whitelisting

Allow inbound SIP traffic from these IP addresses on your receiving system:

137.192.78.201
137.192.80.201

Supported SIP URI formats

Type	Format example
Standard	`sip:user@server.com`
With port	`sip:user@server.com:5060`
With transport	`sip:user@server.com;transport=TLS`
With headers	`sip:user@server.com?header1=value1&header2=value2`
Complex	`sip:user@server.com:5060;transport=TCP?header=value`

Call status webhooks

For both inbound and outbound calls, we send three webhooks per call leg as its status changes: Ringing, Answered, and Completed. These go to the URL on your Webhook Subscription as a CallStatusChangedWebhook.

Each call can produce up to six webhooks in total:

First call leg ringing (replaced by InboundCallReceivedWebhook for dynamic forwarding)
First call leg answered
Second call leg ringing
Second call leg answered
First call leg completed
Second call leg completed

You may see fewer if a party doesn't answer, rejects the call, or hangs up before the other party connects.

Call recordings

We can record your calls. With recordings, you can:

Automatically record all inbound calls to a specific number
Control recording per call for inbound calls using dynamic forwarding
Choose whether to record outbound calls you initiate
Get a webhook when a recording is ready

Recordings are stored as .MP3 files and kept for as long as the associated call record stays in your account.

Legal and privacy notice: Recording calls may require consent from one or more parties and may be restricted by local laws, for example GDPR or CCPA. We provide recording as a feature, but obtaining consent and staying compliant is your responsibility. Consult a qualified attorney for guidance specific to your jurisdiction.

How to enable recording

For inbound calls, the default is controlled by recordInboundCalls on PUT /v1/Phones/{phone}/voice. If a number uses dynamic forwarding (no callsForwardedTo set), you can override that default in the Call Script that handles the call.

For outbound calls, set "record": true on the POST /v1/Calls request. Otherwise, outbound calls aren't recorded.

Recording lifecycle

Status	Description
Recording	The call is actively being recorded.
Paused	Recording was paused.
Processing	The call ended and the recording is being prepared.
Completed	The call ended and the recording is available for download.

Controlling recording mid-call

Pause and resume recording during an active call with POST /v1/Calls/{sid}/recording-control. Each resume starts a new segment, so the number of segments matches the number of pause and resume actions.

Retrieving recordings

Use GET /v1/Calls/{sid} to check whether a call was recorded and to get its recording metadata. The recordings field only appears if a recording was requested for that call.

Call recording webhook

We send a CallRecordingCompleted webhook when a call's recording finishes processing and is ready to download, delivered to the URL you configured in your Webhook Subscription. We don't send this webhook for calls that weren't recorded.