logo

Voice Services

Overview of Voice Services at Telgorithm

To enable voice services, customers need to reach out to Telgorithm Support to activate the service on their accounts.

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

v1/phones/{number}/voice
API, 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>
  • 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.

For more details on configuring webhooks and handling Outbound Call events, please refer to the Webhooks Documentation.