NOTE:

If you are interested in trying TeleSign’s Voice API, sign up by contacting our experts.

Perform a Cold Transfer with the TeleSign Voice API

This page explains how to use the TeleSign Voice API to perform a cold transfer. A cold transfer is one where the transferring agent does not talk to the new agent before performing the transfer.

For example, a customer might call in to a credit card company to ask an agent about their bill. After learning that their bill is past due, the customer might want to pay the bill immediately. The agent tells the customer that they will transfer them to the billing department. The customer is then connected to a new agent in the billing department immediately after the initial agent drops off the call.

NOTE:

TeleSign calls have a maximum call duration of four hours. You can also set a shorter maximum for an individual call.

Requirements

To implement a cold transfer with TeleSign’s Voice API, you must have the following:

  • TeleSign credentials: Your Customer ID and API key
  • TeleSign phone number: A phone number you have purchased from TeleSign to use as a caller ID. Purchase a number using the TeleSign Phone Numbers API (see Get Started with the Phone Numbers API) or ask our Customer Support Team to purchase a number for you. Make sure that the number is voice-capable (include the parameter and value voice_capable=true in your request to the Phone Numbers API). Refer to Get Started with the Phone Numbers API for more details.
  • Customer event URL: A notification service you have set up for TeleSign to post event information to. For more details, refer to the Set up the Customer Event URL section on the Voice API Reference page.

Be sure also to only use supported standards and codecs (see Supported Standards and Codecs).

How to Implement a Cold Transfer

In this example, caller A calls into their credit card company. TeleSign receives the call and notifies the credit card company that there is an incoming call by posting an event to the company’s customer event URL on their server. Their server responds with a request to TeleSign to dial agent B. TeleSign calls agent B, and when agent B picks up, caller A and agent B are bridged together. Caller A and agent B talk about the caller’s bill, and agent B says they will transfer caller A to make a payment. Caller A accepts, and agent B initiates a cold transfer by hanging up. The hang up triggers a call to agent C. TeleSign calls agent C, and this bridges caller A and agent C.

Sections of a call are referred to as “legs”. A call leg is a logical connection between two voice gateways or between a gateway and an IP telephony device. Caller A connecting to TeleSign in the example is call leg A, TeleSign connecting to agent B and bridging the call is call leg B, and TeleSign connecting to agent C and bridging the call is call leg C.

To set up the call, do the following:

  1. Imagine caller A makes an incoming call. TeleSign posts to a customer event URL on your server that you have an incoming call with an incoming call event. Caller A calling and reaching TeleSign can be thought of as call leg A. Here is a sample of how the JSON TeleSign sends to you in an event might look:
POST Request from TeleSign - Incoming Call
{
  "event": "incoming_call",
  "reference_id": "534e1848-235f-482d-983d-e3e11a04f58a",
  "data": {
        "to": "15555551212",
        "from": "15558675309",
      }
}
  1. To set up call leg B and connect the call, you respond to the TeleSign Voice API with a request for the dial action. Your dial action contains the phone number of agent B, and the TeleSign purchased caller ID you want to use to mask the number you are connecting to the customer.
Dial Command Used to Bridge Call
{
  "method": "dial",
  "params": {
    "to": "15555551212",
    "caller_id_number": "15554441313"
  }
}
  1. This bridges the call. Caller A and agent B can now communicate about the customer’s bill. The agent says “If you want to make a payment, I can transfer you to the billing department.” The caller says that would be great. The agent hangs up. TeleSign posts a call_leg_completed event to a customer event URL on your server. This triggers a system response to set up the C leg of the call.
    {
            "event": "call_leg_completed",
            "reference_id": "01695AB90A3F570CE200338200000000",
            "data": {
                "from": "15558675309",
                "to": "15555551212",
                "caller_id": "15550000001",
                "status": "call_answered",
            }
        }
  1. Again using a dial command, you dial to the new agent (agent C). This will bridge the caller who is still on the line to the agent. This is a cold transfer. The bridging occurs, but there is no overlap between agent B and agent C being on the call. You can think of this as bridging the A leg of the call to the C leg. An example of the JSON is:
{
  "method": "dial",
  "params": {
    "to": "15552311234",
    "caller_id_number": "15554441313"
  }
}
  1. Caller A and agent C talk, and the caller pays their bill and hangs up. TeleSign posts a call_completed event to a customer event URL on your server. The call counts as completed because the A leg has now hung up. If the A leg does not hang up, you can add other options and transfers.

Next Steps

This section offers some suggestions for next steps to take.

  • Receive an Inbound Call - Learn more about receiving an inbound call.
  • Set up Click-to-Call - If you set up a system where an agent calls a customer you might want to combine starting the call with click-to-call with cold transfers to other agents for different services.
  • Get Started with the Phone Numbers API - Learn more about using TeleSign’s Phone Numbers API to lease phone numbers for use with the Voice API. You can also cancel leases, or check what leased numbers you already have.