Voice - Send a TTS message and collect digits
NOTE:
To add this product to your account, contact a Telesign expert. This product is available for full-service accounts only.
Telesign Voice enables you to convert text into a voice-based message using text-to-speech (TTS). Provide a localized customer experience in any of 26 languages and dialects.
You can use TTS as part of an outbound call, or you can receive an inbound call, answer it, and play a TTS message.
Before you begin
You must have the following before sending a TTS message:
-
Telesign authentication credentials: Your Customer ID and API key.
-
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.
-
Supported standards and phone number formats: Verify that the standards and phone number formats that you want to use are supported by Telesign before following the steps below. See Voice - Supported standards and codecs.
NOTE:
Be sure that you are using the correct language table. See this list of other language tables for Voice and Voice Verify.
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.
Implement a message with TTS
This section walks you through dialing a number, playing a text-to-speech (TTS) message, and collecting digits from an end user.
To set up the call, do the following:
- Create an outbound call using the
dial
Action. You add a destination phone number forto
and your caller ID (phone number you bought from Telesign) goes in thecaller_id_number
field. You can add other optional parameters.
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 = {
"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_completed
Event. Check that the value of thedata.status
property in the Event isanswered
. -
If everything looks good, respond to the
dial_completed
Event with thespeak
Action to play a custom TTS message and collect digits. You can either send a plain text message or use speech synthesis markup language (SSML). For more details on SSML tags that we support, see Voice - Use SSML for TTS.
Example Speak Action
{
"method": "speak",
"params": {
"tts": {
"message": "<speak>Press <prosody volume='loud'>1</prosody> for your account balance. Press <prosody volume='loud'>2</prosody> to speak with a customer service representative.</speak>",
"language": "en-US",
"type": "ssml"
},
"collect_digits": {
"max": 1,
"timeout": 10000,
"inter_digit_timeout": 3000,
"terminators": "*"
}
}
}
Here is a code sample showing how you might handle Telesign Events:
TTS and Collect Digits in Python
from json import dumps, loads
from bottle import route, run, request, post
# This is an example response to a dial_completed event that will play a message and collect digits during play.
# {
# "method": "speak",
# "params": {
# "tts": {
# "message": "Press 1 for your account balance. Press 2 to speak with a customer service
# representative",
# "language": "en-US"
# },
# "collect_digits": {
# "max": 1,,
# "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:
message = "Press 1 for your account balance. Press 2 to speak with a customer service representative."
language = "en-US"
max = 1
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='speak',
params={
'tts': { 'message': message, 'language': language },
'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)
- If speaking the message and collecting digits is successful, you get back
speak_completed
in an Event from Telesign. You can send an Action to hangup the call withhangup
or you can send further messages withplay
orspeak
Actions.
Updated 23 days ago