Voice - Set up IVR



To add this product to your account, contact a Telesign expert. This product is available for full-service accounts only.

You can use Telesign Voice 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.

See Voice - Get started for basic usage instructions for Telesign 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 authentication 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 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 Phone Numbers API - Get Started for more details.
  • Customer event URL: A notification service you have set up for Telesign to post Event notifications to. See Voice - Receive Events with webhooks for instructions on how to set that up.

Set up Inbound IVR

A popular use case for IVR is setting up a phone tree. With Voice, you can set up the flow a variety of ways. In this walkthrough, you go through the steps for this type of setup.



For full API reference details for this service, including definitions for each parameter, see POST https://rest-ww.telesign.com/v2/voice.

Receive an inbound call

This example starts with an inbound call. When a call comes in, Telesign sends an Event to your customer event URL to notify you of this.

Example: Incoming Call Event

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

After you receive this Event, you then instruct Telesign what to do next by sending an Action (for example play or speak). See Voice - Actions for a full list of available Actions.

Example: 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 Action

After you send this Action, Telesign responds with a play_completed Event that tells you the status of your request.

Example: Play Completed Event

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