Voice - Set up IVR

📘

NOTE:

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.

📘

NOTE

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

Requirements

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.

📘

NOTE

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"
  }
}