Want to provide feedback?

Write to docs@telesign.com.

NOTE:

If you are interested in trying TeleSign’s Voice API, sign up by navigating to our Voice API signup page.

Perform a Cold Transfer with TeleSign’s Voice API

A cold transfer on TeleSign’s Voice API is a transfer of a phone call without notice or explanation. This kind of transfer is useful in situations where a customer wants to do something simple that does not require explanation after a transfer occurs. For example, a customer might call in to a credit card company to ask an agent about their bill. After learning their bill is past due, the customer might want to pay the bill. The agent tells the customer they can transfer them to the billing department. Without any introduction or context, the customer is then connected to the appropriate agent in the billing department. Because the transaction is simple, this kind of transfer would be okay to use. If the customer needed to explain something complex, a cold transfer is not recommended.

NOTE:

TeleSign calls have a maximum call duration of four hours.

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 - you must purchase a TeleSign phone number to use as a callerID. You can do this using the Phone Numbers API. Refer to the Get Started with the Phone Numbers API page.
  • For details about supported standards and codecs, see Supported Standards and Codecs*
  • If you plan to use events posted by TeleSign as a trigger for what action to take next with a call, you need a customer event URL on your server 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.
  • If you want to make choice about how to handle a call without needing an event posted by TeleSign as a trigger, you will need to review:

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 take the action of dialing 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 can transfer caller A to make a payment. Caller A accepts, and agent B does 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 described 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 the 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 - example only",
        "from": "15558675309 - example only",
      }
}
  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 - example only",
    "caller_id_number": "15554441313 - example only"
  }
}
  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 - example only",
                "to": "15555551212 - example only",
                "caller_id": "15550000001 - example only",
                "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 introduction or context provided as to why the customer is being transferred. When you are designing, think about whether this works for your use case. Cold transfers are best for simple use cases where a customer does not need to explain their situation. 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 - example only",
    "caller_id_number": "15554441313 - example only"
  }
}
  1. Caller A and agent C talk, and the caller pays their bill and hangs up. TeleSign posts a call_completed event to the 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.