A. Getting Started
B. How to Set up a Vonage Voice Application
C. How to Implement a Python Flask Voice Application
Companies can improve their customer experience by enabling customer support via phone calls. Voice applications enable companies to create such custom phone lines to best suit end users. In this article, you will learn to build a Python Flask application in to develop a voice application to receive inbound phone calls. We will explore a few different scenarios that you can build to receive a phone call, all inside a Flask application!
Vonage voice applications build upon the concept of Vonage Call Control Objects (NCCOs). A Call Control Object comprises a JSON array of actions that can control inbound calls. An NCCO tells you 3 things:
action: tells what is to be done on the call
options: describes how to modify the action
type: describes the option, for instance,
type=phonefor an endpoint option
The actions listed in an NCCO are executed on a first-in, first-out (FIFO) basis. The 3 actions that we will use in this article are:
Stage 1: action = talk.
Stage 2: action = connect.
Stage 3: - actions = talk and then stream. Then when the agent can take the call transfer (via REST call) and connect the caller.
You can perform other actions which we won't cover here, such as recording calls or downloading recorded calls. Learn more here.
To complete this tutorial, you will need a Vonage API account. If you don’t have one already, you can sign up today and start building with free credit. Once you have an account, you can find your API Key and API Secret at the top of the Vonage API Dashboard.
Learn how to install Python3 here.
Ngrok: helps you run a web server to quickly and easily test your web applications. You can install Ngrok by following the installation instructions on the official website. You can run ngrok after installing it with the following command:
The running ngrok instance will generate a URL that tunnels localhost server. The Ngrok-generated URL will look like the following:
Note the URL that Ngrok generates for you. You will need it later in this tutorial to configure your application capabilities.
Open a new tab in your terminal. All further terminal commands will be in the new terminal tab as we will leave ngrok running in the background
Flask: a lightweight web framework for building web applications in Python. You can install Flask with the pip package manager that comes pre-installed with Python. Use the following command on your terminal:
The Vonage CLI is a nice tool for your Vonage account management and administrative tasks. You can use it instead of the Vonage dashboard UI for tasks like creating applications, purchasing virtual phone numbers, and more. You can install it with the npm package manager. Use the following command in your terminal:
You need your account API key and API Secret to configure the Vonage CLI. Login into your Vonage account in the API developer dashboard and you'll see both values at the top of the page.
Then, set the two values in your terminal as shown in the following code:
Vonage Python SDK: This is a great CLI toolkit that makes it easy to work with Vonage while building Python applications. You can install it with the pip package manager
You will use the Vonage CLI to create a new Vonage app. Create a new directory and use the Vonage CLI to create a Vonage app as shown by the following terminal commands.
To create a new directory named project:
To create a new Vonage application:
You should get an output that looks like this:
2 Things To Note
The
APPLICATION_IDthat is returned, you will need it later as you follow this guide.a private.key file created in your project
Ngrok creates tunnels to allow your application to be accessed publicly and safely. However, you need to connect your running Python script with the Vonage application that you created from the terminal earlier in the article.
Steps to activate the Voice feature on your Vonage application.
Go to your dashboard's Applications section and select the application you created.
Click the Edit button to open the application settings page.
On the settings page, scroll down to the Capabilities section to see the Voice feature card.
Click the toggle button on the Voice feature card to activate the Voice capability on the application. This makes the feature card expand and shows the fields for the needed URLs.
You can input your Answer and Event URLs in their respective fields.
The Answer URL is where Vonage relays the calls that come in on the Vonage number
The Event URL is where event information about calls comes in through. You can use events to monitor or confirm your call requests.
Your URLs should look similar to this:
Answer URL: https://3eab-197-210-8-199.ngrok.io/webhooks/answer
Event URL: https://3eab-197-210-8-199.ngrok.io/webhooks/event
Scroll down the page and click the Save changes button.
You need to search for a Vonage virtual number before you can purchase it. Use the following terminal command to search for a number.
You can replace [COUNTRY_CODE] in the above command with the alpha-2 country code of any country you want the number domiciled in. This is demonstrated in the following bash command:
The terminal output should be like the following:
Select a suitable number and purchase it with the following terminal command:
An example:
You will get an output like this:
Use the following command to assign the newly purchased number to the Vonage application you created earlier.
You should get a bash output similar to the following:
When an Inbound Call is received, a text-to-speech message can be played to the caller. This scenario will involve writing the code for the implementation.
Create a new file inside the project directory and name it scenario-1.py. Add the following code inside it:
from flask import Flask, request, jsonify
app = Flask(__name__)
ncco = [
{
"action": "talk",
"text": "Hello, our office hours are Monday to Friday nine until five-thirty. Please call back then.",
"language": "en-GB"
}
]
@app.route("/webhooks/answer")
def answer_call():
return jsonify(ncco)
@app.route("/webhooks/event")
def events():
return ("200")
if __name__ == '__main__':
app.run(host="localhost", port=9000)In the above code:
you specified an Answer webhook URL where a callback is generated when your Vonage number receives a call. An NCCO is then returned as a response.
The NCCO controls the call by the
actionof playing a text-to-speech message into the call. The NCCO consists of the message that the caller hears and Vonage terminates the call at the end of the message.You also have a webhook event for listening to events.
In a separate tab from your ngrok tunnel, use the following terminal command to run the code
python scenario-1.pyTry It Out:
Call the Vonage virtual number and you should hear the message.
In this scenario, we will include a new NCCO action, connect to connect the caller to an agent after playing the talk NCCO message.
Create a new file can save it as scenario-2.py. Add the following code and save the file.
from flask import Flask, request, jsonify
VONAGE_NUMBER = "1**********" # Replace with your virtual Vonage number
YOUR_SECOND_NUMBER = "1**********" #Replace with your number
app = Flask(__name__)
ncco = [
{
"action": "talk",
"text": "Hello, one moment please, your call is being forwarded to our agent."
},
{
"action": "connect",
"from": VONAGE_NUMBER,
"endpoint": [{
"type": 'phone',
"number": YOUR_SECOND_NUMBER
}]
}
]
@app.route("/webhooks/answer")
def answer_call():
return jsonify(ncco)
@app.route("/webhooks/event")
def events():
return ("200")
if __name__ == '__main__':
app.run(host="localhost", port=9000)In the above code:
Vonage receives a call in the virtual number and generates a callback on the answer webhook URL.
The NCCO which controls the call firsts plays the text-to-speech message into the call. That is the first action,
talk.Upon completion of the
talkaction, theconnectaction is invoked which forwards the call to another number which could be your agent in a call, until one of them hangs up.
Try It Out:
Call your Vonage number. You will hear the message and then your call will be forwarded to the second number you specified.
The implementation here puts the caller on hold (listening to music) until an agent is available. Then, the call is transferred to the agent.
The implementation goes by the following steps:
A call comes in and a test-to-speech message is played
Since an agent is unavailable, the call is played a music
When an agent becomes available (after a simulated 30 seconds time delay), the call is then forwarded to the new NCCO,
ncco2When
ncco2receives the forwarded call, it plays a message and then forwards the call to the now-available agent.
You can create a new file called scenario-3.py and add the following code to it:
from flask import Flask, request, jsonify
from threading import Timer
import vonage
UUID = ""
APPLICATION_ID = "YOUR_APP_ID"
PRIVATE_KEY = "voice_app.key"
TIMEOUT = 30 # Agent becomes available after this period
VONAGE_NUMBER = "1**********" # Replace with your virtual number
YOUR_SECOND_NUMBER = "1**********" #Replace with your number
# audio_url = "https://your_domain.com/your_music.mp3"
audio_url = "https://download.samplelib.com/mp3/sample-12s.mp3"
ncco_url = "https://1234abcd.ngrok.io/ncco"
ncco = [
{
"action": "talk",
"text": "Hello, I'm sorry, but all our agents are helping customers right now. Please hold, and we will put you through as soon as possible."
},
{
"action": "stream",
"streamUrl": [audio_url],
"loop": 0
}
]
ncco2 = [
{
"action": "talk",
"text": "Now connecting you. Thanks for waiting."
},
{
"action": "connect",
"from": VONAGE_NUMBER,
"endpoint": [{"type": 'phone',"number": YOUR_SECOND_NUMBER}]
}
]
def transfer_call ():
print ("Transferring call...")
client = vonage.Client(application_id = APPLICATION_ID, private_key=PRIVATE_KEY)
dest = {"type": "ncco", "url": [ncco_url]}
response = client.update_call(UUID, action="transfer", destination=dest)
def register_timer_callback():
t = Timer(TIMEOUT, transfer_call)
t.start()
register_timer_callback()
app = Flask(__name__)
@app.route("/webhooks/answer")
def answer_call():
global UUID
UUID = request.args['uuid']
print("UUID:====> %s" % UUID)
return (jsonify(ncco))
@app.route("/webhooks/event", methods=['POST'])
def events():
return ("200")
@app.route("/ncco")
def build_ncco():
return jsonify(ncco2)
if __name__ == '__main__':
app.run(host="localhost", port=9000)The Vonage Python library enables us to make a REST API call with the update_call function. The REST API call uses the transfer action to transfer the call, identified by a unique id UUID to a specified destination NCCO.
Instead of specifying a static NCCO here, we call an endpoint, build_ncco which returns the new controlling NCCO in JSON format.
The new NCCO then performs a connect action to connect the caller, currently listening to soothing music, to an agent.
Try It Out Call your Vonage number. You will hear a message and then music. After a short delay you will hear a message saying you will be connected to the agent. You are then connected to the agent in a call.
We have seen how to build Python voice applications with the help of Vonage. We used the method of playing a text-to-speech message, forwarding a call to another number, and even playing audio to a caller who kept waiting. You also saw how to transfer control to a new NCCO. With this foundation, you can program much more complicated Python applications.
Now you can also add more advanced actions like recording the call and more.
Check out the Voice API reference for an exhaustive list of things you can build into your voice applications
You can also read more about NCCO actions in the official guide.
If you have questions or feedback, join the Vonage Developer Slack or send Vonage a message on X, formerly known as Twitter!
){kind=small}
Jẹ́káyinOlúwa is a software craftsman and product manager passionate about technology and its impact on people. He works on product management, backend development, DevOps, technical writing, and community strategy. He enjoys dealing in the intersection of software, design, and human interaction. He likes reading and music.
