Voice API - Set up IVR

You can use the TeleSign 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 can also set a shorter maximum for an individual call.


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.

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.

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 the customer event URL you specified.

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

After you receive this event, you then indicate to TeleSign what to do next by sending an action to the Voice API (for example play or speak). See Voice API Reference for a full list of available actions. Send your request to https://rest-ww.telesign.com/v2/voice. Here is an example response action:
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 this action, TeleSign responds with 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 adding any of these components:

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

To learn more about these options, see Voice API - Overview.

Did this page help you?