Voice - Play audio and collect digits
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 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
You must have the following:
- Telesign authentication credentials: Your Customer ID and API key.
- Customer event URL: A notification service you have set up for Telesign to send Event notifications to. See Voice - Receive Events with webhooks for instructions on how to set that up.
If you do not want to use your own number, you should also have:
- 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.
NOTE
For full API reference details for this service, including definitions for each parameter, see POST https://rest-ww.telesign.com/v2/voice.
CAUTION
Use only codecs and standards for audio files supported by Voice. See Voice - Supported standards and codecs for more details.
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.
To set up the call, do the following:
- Create an outbound call using the
dialAction. Add a destination phone number fortoand your caller ID (phone number you bought from Telesign) forcaller_id_number(using a caller ID is optional but recommended).
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.'
external_id = 'An external ID you generated for this transaction.' # Optional parameter
url = "https://rest-ww.telesign.com/v2/voice"
payload = {
"jsonrpc": "2.0",
"method": "dial",
"params": {
"to": destination_number,
"caller_id_number": caller_id_number,
"external_id": external_id
}
}
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_completedEvent. You should have some code to check the status isanswered. -
If everything looks good, you move ahead and respond to the
answeredEvent 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/file.wav",
"collect_digits": {
"max": 5,
"timeout": 10000,
"inter_digit_timeout": 3000,
"terminators": "*"
}
}
}
Here is a code sample showing how you might handle Telesign Events:
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/file.wav",
# "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/file.wav" # 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 showing the outbound call logic, refer to Possible call flows.
- If playing the message and collecting the digits is successful, you get back the
play_completedEvent from Telesign. You can hang up the call by sending thehangupAction or you can send further messages by sending additionalplayorspeakActions.
Updated about 2 months ago