Text to Speech with Prompt Calls, Using Python on AWS Lambda

Published February 16, 2018 by Sam Machin

The Nexmo Voice API offers great flexibility in the call scenarios you can activate, however in order to do this you often need to make several interactions with the API. For some scenarios, you may want to have a single API call from your business logic that invokes a series of interactions with the Voice API. This is an ideal scenario to build a serverless application that you can then call and let it deal with the Voice API interactions.

In this example we will show you how to place a Text to Speech call which will play a message to a recipient then ask them to enter some digits on their keypad, perhaps to confirm a PIN number, you will then get a callback to a URL you specify once the interaction has completed. This is very similar to the deprecated TTS Prompt API that Nexmo offered but giving you greater flexibility.

Currently, the application will call a number, play an initial message and then wait for the user to enter the pin that you specify, if they get the pin wrong they are played an error message and then allowed to retry, up to 3 attempts are allowed although this could be edited in your code.

If they fail to enter the correct PIN on the 3rd attempt the call will be terminated with no message.

If they successfully enter the PIN, they will be played another message and then the call will terminate.
Once the call has ended, you will receive a callback to your webhook with the transaction ID of the call and the outcome of the PIN entry attempts.

View the source code on GitHub


For this tutorial, you will:

  • Need an AWS Account (you can run this on the Lambda free tier)
  • Have the AWS CLI tool and Chalice installed and configured on your machine
  • Create a Nexmo Voice Application and save the private key to a local file named private.key, along with a note of the Application ID
  • Have a Nexmo phone number purchased on your account, this is used for the CallerID


To deploy the function to your own AWS account:

Firstly clone the Git repo to your local machine:

git clone https://github.com/nexmo-community/voice-ttsprompt-lambda.git

Switch into the folder:

cd voice-ttsprompt-lambda

Deploy the function to AWS:

chalice deploy

You will see the following output as your function is deployed, confirm ‘Y’ that you want to add the execution policy

The final line is the base URL of your newly deployed function, make a note of this you can retrieve this at any time with the command chalice url


There is very little that needs to be configured as Chalice takes care of most of the AWS configuration on the first deploy. However, you will need to create the DynamoDB table that is used to store the call state.
You do this with an HTTP GET request to the /setup URL of your function.


You can now invoke your new function with a single HTTP POST request to your base URL with /call on the end.
You need to pass in the following parameters

Parameter Value Example
to The number to be called in e.164 format 14155550100
from The Nexmo number on your account to use for CallerID 14155550101
text The initial message played to the called party “Enter your pin”
pin_code The PIN that the user should enter 1234
callback The URL on your server where the result should be sent http://example.com/callback
callback_method The HTTP method used for your callback webhook GET or POST
bye_text The message to be played on a successful pin entry “Thank you, goodbye”
failed_text The message to be played on an incorrect pin with retry “Incorrect, try again”


The Lambda application does not hold any of your Nexmo credentials instead these are passed in at the time you invoke the function and are only used for that request.

There are two ways you can do this, either by generating a Nexmo JWT with our libraries and putting that in the request headers or by just posting the private key and applicationID as part of a cURL request. It is recommended that you use the JWT method of authentication.

cURL (Private key auth)

Edit the URL to match the one you were given when you deployed your function

Python (JWT)

Edit the URL to match the one you were given when you deployed your function.

You will need the Nexmo python library: install it with pip install nexmo

For either method, the response will be a JSON object containing a transaction ID (‘tid’) this is the reference for the call and will be used in the callback with the result.

Example Response:
"tid": "6a2827c9-4c68-46fc-b179-115f055dc0eb"


When the call has been completed the Lambda function will make a callback request to a webhook you specify when you invoked it—this will contain details of the call and the result:

Parameter Value Example
to The number called in e.164 format 14155550100
tid The transaction ID 6a2827c9-4c68-46fc-b179-115f055dc0eb
status The result ok

The following possible status values could be returned:

  • ok: the call completed and the user entered the correct PIN
  • failed: the call completed but the user failed to enter the correct PIN
  • error: the call was not completed

Next steps

You can modify the code to adjust parameters such as the number of retries the user gets on the pin or perhaps you want to change the voiceName used in the prompts.

The details of each of your calls will be stored in AWS DynamoDB, you may want to clean up these entries from time to time depending on your requirements.

Leave a Reply

Your email address will not be published.

Get the latest posts from Nexmo’s next-generation communications blog delivered to your inbox.

By signing up to our communications blog, you accept our privacy policy , which sets out how we use your data and the rights you have in respect of your data. You can opt out of receiving our updates by clicking the unsubscribe link in the email or by emailing us at privacy@nexmo.com.