Want to provide feedback?

Write to docs@telesign.com.

NOTE:

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

Stream Audio and Collect Digits with TeleSign’s Voice API

You can use the Voice API to play a message and collect digits from your end user. You can do this in an outbound call, or in response to an inbound call. This can be used to create simple phone trees, or collect information from your customer by associating each digit with a choice.

Requirements
Implement Stream Audio and Collect Digits
Next Steps

Requirements

You must have the following:

TeleSign credentials - your customer ID and API key
Access to the Voice API
Caller ID if you do not want to use your own number. For details about purchasing a phone number for use as a caller ID, refer to the Get Started with TeleSign’s Phone Numbers API page.
For details about supported standards and codecs, see Supported Standards and Codecs
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.
You must provide your Account Manager with a URL where your audio file will reside, so that it can be whitelisted for use.
If you want to make a choice about how to handle a call without needing an event posted by TeleSign as a trigger, you will need to review:
- Customer Action API Reference
- Call Query API Reference

Note

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

Implement Stream Audio and Collect Digits

This section walks you through dialing a number, playing a message, and collecting digits from an end user. You could also begin this process by receiving an inbound call, then playing a message and collecting digits. If you want to start that way, see the Receive an Inbound Call page.

To set up the call, you do the following:

You create an outbound call using the dial action. You add a destination phone number for to and your callerID (phone number you bought from TeleSign) goes in the caller_id_number field if you decide to use a caller ID (recommended). If you reviewed the Make an Outbound Call page, this will look familiar.

Outbound Call with Python

from base64 import b64encode

import requests

customer_id = 'Your customer ID goes here.'
api_key = 'Your API key goes here.'

destination_number = 'The complete phone number you want to call, including country code, with no special characters or spaces.'
caller_id_number = 'The phone number you purchased from TeleSign goes here.'

url = "https://rest-ww.telesign.com/v2/voice"

payload = {
            "jsonrpc": "2.0",
            "method": "dial",
            "params": {
                "to": destination_number,
                "caller_id_number": caller_id_number
            }
    }


headers = {
    'Accept': "application/json",
    'Content-Type': "application/json",
    'Authorization': "Basic {}".format(b64encode(customer_id + ":" + api_key).decode('utf-8')),
    }

response = requests.request("POST", url, data=json.dumps(payload), headers=headers)

print(response.text)

TeleSign notifies you with a dial_completed event. You should have some code to check the status is answered.
If everything looks good, you move ahead and respond to the answered event with a request for the action of playing a message and collecting digits. Here is an example of what the payload of that request might look like:

{
  "jsonrpc": "2.0",
  "method": "play",
  "params": {
    "url": "https://url-pointing-to-audio-file.com",
    "collect_digits": {
      "max": 5,
      "timeout": 10000,
      "inter_digit_timeout": 3000,
      "terminators": "*"
    }
  }
}

Here is a code example showing how you might handle the event sent by TeleSign:

Play and Collect Digits in Python

from json import dumps, loads

from bottle import route, run, request, post

# This is a an example response to a dial_completed event that will play a message and collect digits during play.
# {
#   "jsonrpc": "2.0",
#   "method": "play",
#   "params": {
#     "url": "https://url-pointing-to-audio-file.com",
#     "collect_digits": {
#       "max": 5,
#       "timeout": 10000,
#       "inter_digit_timeout": 3000,
#				"terminators": "*"
#     }
#   }
# }

class Response:

    def __init__(self, method, params=None):
        if params is None:
            params = {}

        self.json_rpc = "2.0"
        self.method = method
        self.params = params

    def to_json(self):
        return dumps(self.__dict__)

@post('/')
def telesign_event():
    # Throughout a call session TeleSign will notify you of all events.
    # Each event requires you to send us an appropriate action defined in our documentation.
    # This endpoint needs to match the URL stored in our system to properly communicate.
    #
    # In this example, the server will respond to the dial_completed event.

    # First extract the event from the JSON body in the request.
    event = request.json.get('event')

    if event == 'dial_completed':
        # Check for an 'answered' status. For 'answered' fill out your parameters: 
          url = "https://url-pointing-to-audio-file.com" # This is your message you want to play. 
          max = 5 # This is the maximum number of digits you want to collect.
          timeout = 10000 # How long to wait for the first digit before ending collection. 
          inter_digit_timeout = 3000 # How long to wait for the next digit before ending collection, after at least one digit has been entered. 
          terminators = "#" # The characters to use as terminators for end user entry of digits.

        # Generate the command in the JSON format used by TeleSign.
        return Response(method='play',
                        params={
                                'url': url,
                                'collect_digits': { 'max': max, 'timeout': timeout, 'inter_digit_timeout': inter_digit_timeout, 'terminators': terminators }
                            }).to_json()
    else:

        return Response(method='hangup').to_json()

run(host='localhost', port=8080, debug=True)

For a diagram, refer to the Set up the Call section of the Make an Outbound Call page.

If playing the message and collecting the digits is successful, you get back the play_completed event from TeleSign. You can issue a request to hangup the call with hangup or you can send further messages by issuing additional play or speak commands.

Next Steps

This section offers some suggestions for next steps to take.

Make an Outbound Call - Review the basics for making an outbound call, or check out the flow diagrams for different scenarios.
Set up Anonymous 2-way Voice - Learn how to set up 2-way voice communication between callers where both their numbers are masked.