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. You can collect input for IVR 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") or by detecting speech using speech recognition.

• 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 voice-capable phone number you have purchased from Telesign to use as a caller ID. Contact our Customer Support Team for 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.

Use case - 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. For example, you can collect digits or detect speech in the same IVR as discussed below.

📘

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": "11234567890",
      }
}

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 and detect speech feature

{
  "method": "play",
  "params": {
    "url": "https://tsqa-test.s3.amazonaws.com/20_second_count.wav",
    "collect_digits": {
      "max": 3,
      "terminators": "#"
    },
    "detect_speech": {
      "language": "en-US",
      "max_speech_duration": 3000,
      "timeout": 6000,
      "inter_speech_timeout": 2000
    }
  }
}

Receive a response to your Action

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

Example: Play Completed Event when digits are collected

{
  "reference_id": "123ABC",
  "event": "play_completed",
  "data": {
    "to": "15555551212",
    "from": "11234567890",
    "status": "play_successful",
    "collected_digits": "5"
  }
}

Example: Play Completed Event when speech is detected

{  
  "reference_id": "123ABC",  
  "event": "play_completed",  
  "data": {  
    "to": "15555551212",  
    "from": "11234567890",  
    "status": "play_successful",  
    "collected_digits": "",  
    "detected_speech": "speak with representative"  
  }  
}