Want to provide feedback?

Write to docs@telesign.com.


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

Set up IVR with TeleSign’s Voice API

You can use TeleSign’s new Voice API to create a complete inbound or outbound Interactive Voice Response (IVR) experience.

IVR is an automated system that uses voice to engage customers with information like alerts or reminders, or by collecting dual-tone multi-frequency (DTMF) digits in response to questions (for example 'Press 1 to speak to an agent, 2 to hear your balance).

  • Inbound IVR - This is where someone calls into your system. This is often used to help users complete simple transactions, or to connect them to the right person to help them with a problem. An example of Inbound IVR would be when you call in to hear your banking balance or speak with an agent about a bill.
  • Outbound IVR - This is typically used to do a mass alert, reminder, or send people a survey. An example of outbound IVR might be a school wanting to send a mass alert that school will be cancelled. Or a system that sends out Doctor’s appointment reminders.

TeleSign’s Voice API is flexible. You use events and actions to communicate. When TeleSign has information for you about a call, it posts the information as an event at your customer event URL. You then decide from the information in the event what you want to do next, and use an action to communicate to TeleSign’s Voice API. The endpoint you use to send requests is https://rest-ww.telesign.com/v2/voice.


TeleSign calls have a maximum call duration of four hours.


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.
  • 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:

Set up Inbound IVR

A popular use case for interactive voice response is setting up a phone tree. With TeleSign’s Voice API, you can set up the flow a variety of ways. In this walkthrough, you go through the steps for setup, and details about the payload you send back and forth.


For further technical details, including definitions for each parameter, see Voice API Reference.

Give TeleSign Your Event URL

If you plan to have actions you take on a phone call triggered by events from TeleSign, you must set up a customer event URL. To get started, contact our Customer Support Team, and provide them with your customer event URL. TeleSign will post event notifications to this URL.

Turn Off Event Posting From TeleSign

Should you decide you do not wish to receive event information from TeleSign, you can contact our Customer Support Team and request that they turn off this feature for you. To handle calls you will then need to use the Customer Action API and the Call Query API.

Buy a Phone Number

  1. Make sure you have your customer ID and API key.

  2. Make sure that you purchase a phone number for use with the TeleSign Voice API. You will need one that includes voice capability. You can search for one using the API Explorer on the Search for a Phone Number page. To use it, send a GET request to https://rest-ww.telesign.com/v1/phone_numbers/numbers?country_iso2=US&voice_capable=true. With this request, you are asking for a voice capable phone number from the US.

  3. Choose one of the numbers returned to you, and then you can buy one. Send a POST request to https://rest-ww.telesign.com/v1/phone_numbers/leases. The body of your request should contain country_iso2 and phone_number.

  "country_iso2": "US",
  "phone_number": "Enter the phone number you want to buy, no special characters or spaces",


Receive an Inbound Call

This example starts with an inbound call. When a call comes in, you receive information about it when TeleSign posts an event notification to your server at the customer event URL you specified.

  "event": "incoming_call",
  "reference_id": "534e1848-235f-482d-983d-e3e11a04f58a",
  "data": {
        "to": "15555551212",
        "from": "15558675309",

When you receive it, you decide what to do next by telling TeleSign with an action. The action can be from any of the action choices described on the Voice API Reference page. This includes play and speak. Send your request to https://rest-ww.telesign.com/v2/voice. Here is an example of an action you might respond with:

Play Action with Collect Digits Feature
  "method": "play",
  "params": {
    "url": "https://url-pointing-to-audio-file.com",
    "collect_digits": {
      "max": 5,
      "timeout": 10000,
      "inter_digit_timeout": 3000

Receive a Response to Your Actions

After you send TeleSign a message that you want to play a message and collect digits, TeleSign will respond back to you with information about the message. You will receive a play_completed event that tells you the status of your request. Here is an example of a successful response:

Play Completed Event
  "event": "play_completed",
  "reference_id": "Q772E290BG4C01648984EAD7EA1D0021",
  "data": {
    "from": "15555551212",
    "to": "15558675309",
    "status": "playback_successful",
    "collected_digits": "923"

Continue Building Your IVR

You can continue building your IVR by using the different available pieces for it. Choices include:

  • Outbound calls
  • Handle inbound calls
  • Play a file for someone
  • Play a TTS message
  • Collect digits

You can read about available options on the Voice API Reference page.