Voice Services

Inbound Calls

For handling inbound calls, Telgorithm offers two call forwarding options:

1. Static Call Forwarding
2. Dynamic Call Forwarding

Static Call Forwarding

With static call forwarding, customers can set a fixed forwarding destination number for each of their phone numbers. This can be configured using the GET /v1/Phones/{phone}/voice API endpoint, where each phone number is associated with a single, designated forwarding number, where all incoming calls will be redirected to.

Dynamic Call Forwarding

If static forwarding is not set for a number, Telgorithm defaults to dynamic call forwarding. This approach involves sending a webhook to the customer whenever an inbound call is received on a phone number.

Handling Inbound Calls with Dynamic Call Forwarding

The InboundCallReceivedWebhook is triggered and sent to the URL specified for the corresponding Webhook Subscription whenever an inbound call arrives. To learn more about Webhook Subscriptions, please refer to the Webhooks Documentation.

Customers need to respond to this webhook with a Call Script, which dictates how Telgorithm should handle the incoming call.

The following Call Scripts are supported:

• Forward the call: <Response><Dial>+1234567890</Dial></Response>
• Forward the call and override recording behavior: <Response><Dial Record="true">+1234567890</Dial></Response>
• Play a message with Text-to-Speech engine and then hang up: <Response><Hangup>The number you have dialed is currently out of service.</Hangup></Response>
• Directly hang up the call: <Response><Hangup/></Response>

If there is no response to the webhook or if the response is invalid, the system will automatically hang up the call.

How Inbound Call Forwarding is Performed

An inbound call is handled in three stages:

1. When the Inbound Call reaches the Telgorithm Platform, it is referred to as the first Call Leg. The Platform examines the forwarding settings configured for the corresponding account’s phone number to determine which forwarding option (Static or Dynamic) to use.
2. Once the forwarding number is identified, the second Call Leg is initiated to the forwarding number with the same Caller ID as the first Call Leg had. This forwarding number represents the "internal" party of the call (e.g., the calldesk agent’s number).
3. When the internal party answers, both Call Legs are joined. The call ends when any party hangs up or a Hang Up API endpoint is used to terminate the call.

Outbound Calls

Telgorithm supports outbound calling capabilities, allowing customers to initiate calls programmatically.

Initiating Outbound Calls

To initiate an outbound call, customers can use the POST /v1/voice/calls API endpoint.

How Outbound Calls are Performed

An Outbound Call is initiated in three stages:

1. The Telgorithm Platform initiates the first Call Leg by calling from the number specified as "Caller ID" to the number specified as "From". This "From" number is considered the "internal" party of the Outbound Call (e.g., the calldesk agent’s number).
2. When the human agent answers the first Call Leg and optionally acknowledges it by pressing a key tone on their phone, the Platform initiates the second Call Leg from "Caller ID" to the number specified as "To." This "To" number represents the "external" party the agent wants to reach.
3. When the external party answers, both Call Legs are joined. The call ends when any party hangs up or a Hang Up API endpoint is used to terminate the call, similar to an Inbound Call.

Call Status Webhooks

For both Inbound Calls and Outbound Calls, three webhooks are provided per Call Leg when their status changes: Ringing, Answered, and Completed. These webhooks are sent to the URL specified in the Webhook Subscription with the CallStatusChangedWebhook type.

Each call (Inbound or Outbound) may produce up to six webhooks in total:

1. First Call Leg Ringing (replaced by InboundCallReceivedWebhook for Dynamic Forwarding)
2. First Call Leg Answered
3. Second Call Leg Ringing
4. Second Call Leg Answered
5. First Call Leg Completed
6. Second Call Leg Completed

The total number of webhooks may vary if any party does not answer, rejects the call, or hangs up before the other party connects.

Call Recordings

Telgorithm can record your phone calls. With Call Recordings you can:

• Automatically record all inbound calls to a specific phone number.
• Control recording behavior per call for inbound calls using dynamic call forwarding.
• Choose whether to record outbound calls that you initiate.
• Receive a webhook notification when recordings are ready.

Recordings are stored as audio files (.MP3). Recordings are retained as long as the associated Call record remains in your account.

How to Enable Recording

For inbound calls, the default recording behavior is controlled by the recordInboundCalls parameter in PUT /v1/Phones/{phone}/voice. If the number uses dynamic call forwarding (callsForwardedTo is not set), the recording behavior can be overridden in the Call Script that handles the call.

For outbound calls, recording can be enabled by including the "record": true flag in the POST /v1/Voice/Calls. Otherwise, outbound calls are not recorded.

Recording Lifecycle

⚠️Current Limitation: Pause is not yet supported. Each call produces a single, continuous recording.

Retrieving Recordings

To determine whether a call was recorded and to retrieve its recording metadata, use the GET /v1/Voice/Calls/{sid} API endpoint. The recordings field appears only if recordings were requested for the call.

Call Recording Webhook

For both Inbound and Outbound Calls, a CallRecordingCompleted webhook is sent when the call recording is completed and available for download. This webhook is delivered to the URL configured in the Webhook Subscription for this event type.

The webhook is not sent for calls that were not recorded.