Programmable Voice quickstart for Python

Log in to your Twilio account or sign up for a new one.

If you need a Twilio phone number, buy one in the Twilio Console:

1. Go to Phone Numbers > Manage > Buy a Number.
2. Under Capabilities, select Voice.
3. Click Search. The page displays a list of available voice-capable phone numbers.
4. Click Buy next to a phone number to add it to your account.

Verify that your computer has Python installed. Open a terminal and run the following command:

python --version

If your computer has Python then you should see a Python version number like this:

1
python --version
2
Python 3.13.5

If you don't have Python 3.3 or higher then install or upgrade Python before continuing.

Create a new directory for this project and navigate to it using the command line. Then, run the following commands to create and activate your Python virtual environment:

1
python -m venv quickstart
2
source quickstart/bin/activate

1
python -m venv quickstart
2
quickstart\Scripts\activate

Run this command to install the Flask web framework and Twilio's Python helper library:

pip install twilio Flask

Create a new file in your project directory named make_call.py with the following code:

1
# Download the helper library from https://www.twilio.com/docs/python/install
2
import os
3
from twilio.rest import Client
4

5
# Find your Account SID and Auth Token at twilio.com/console
6
# and set the environment variables. See http://twil.io/secure
7
account_sid = os.environ["TWILIO_ACCOUNT_SID"]
8
auth_token = os.environ["TWILIO_AUTH_TOKEN"]
9
client = Client(account_sid, auth_token)
10

11
call = client.calls.create(
12
    url="http://demo.twilio.com/docs/voice.xml",
13
    to="+15558675310",
14
    from_="+15017122661",
15
)
16

17
print(call.sid)

This code starts a phone call between the two phone numbers that you pass as arguments. The from_ number is your Twilio number, and the to number is the call recipient.

The url argument points to a TwiML file that tells Twilio what to do when the call recipient answers their phone. This TwiML instructs Twilio to read a message using text-to-speech and then play an MP3.

Swap the placeholder values for account_sid and auth_token with your personal Twilio credentials.

1. Log in to the Twilio Console.
2. Copy the Account SID and replace os.environ["TWILIO_ACCOUNT_SID"] with it in the make_call.py file.
3. Copy the Auth Token and replace os.environ["TWILIO_AUTH_TOKEN"] with it.

Replace the from_ number with your new Twilio phone number in E.164 format. Then, replace the to number with your own personal phone number in E.164 format.

Save your changes and then run the script using this command:

python make_call.py

Your phone should ring with a call from your Twilio number. Answer it and you'll hear a short message.

Create a file in your project directory called answer_phone.py. Add the following code to your file to create a Flask app that serves TwiML.

1
from flask import Flask
2
from twilio.twiml.voice_response import VoiceResponse
3

4
app = Flask(__name__)
5

6
@app.route("/", methods=['GET', 'POST'])
7
def answer_call():
8
    """Respond to incoming phone calls with a brief message."""
9
    # Start our TwiML response
10
    resp = VoiceResponse()
11

12
    # Read a message aloud to the caller
13
    resp.say("Thank you for calling! Have a great day.", voice='Polly.Amy')
14

15
    return str(resp)
16

17
if __name__ == "__main__":
18
    app.run(debug=True)

Save the file and start your Flask app with the following command:

python answer_phone.py

You should see output that looks this:

1
 * Serving Flask app 'answer_phone'
2
 * Debug mode: on
3
 * Running on http://127.0.0.1:5000
4
Press CTRL+C to quit

If you don't already use ngrok then download and install it.

Then, open a new command line window and start ngrok with this command:

ngrok http 5000

You should see output that resembles this:

1
Session Status                online                                                                       
2
Version                       3.23.2                                                                       
3
Web Interface                 http://127.0.0.1:4040                                                        
4
Forwarding                    https://ff4660c91380.ngrok.app -> http://localhost:5000                      
5
                                                                                                           
6
Connections                   ttl     opn     rt1     rt5     p50     p90                                  
7
                              0       0       0.00    0.00    0.00    0.00 

Copy the URL ending in ngrok.app and paste it into your browser. You should see a TwiML document that says "Thank you for calling! Have a great day."

1. Navigate to the Active Numbers page in the Twilio Console.
2. Click on the phone number you purchased earlier.
3. Visit the Configure tab and find the Voice Configuration section.
4. In the A call comes in row, select the Webhook option. Paste your ngrok public URL in the URL field (for example, https://ff4660c91380.ngrok.app).
5. Click on Save configuration.

Head back to your terminal. Make sure that ngrok is still running in one tab and your application's web server is running in another tab.

Make a phone call to your Twilio phone number. You'll hear a short message once the call connects and it should match the TwiML instructions served by your Flask application.

Our Flask app here only used the <Say> TwiML verb to read a message to the caller using text-to-speech, but you can do more with other TwiML verbs like <Record>, <Gather>, and <Conference>.

Check out these pages to learn more:

• Gather user input via keypad (DTMF tones) in Python
• Learn how to record incoming and outgoing Twilio Voice phone calls using Python
• Create conference calls in Python
• Dive into the API Reference documentation for Twilio Programmable Voice
• Learn how to modify calls in progress with Python
• Looking to make a call from your browser or mobile application? Use a Twilio Voice SDK to integrate high-quality VoIP calling.
• Retrieve information about in-progress and completed calls from your Twilio account using Python.
• Check out our full sample application tutorial on how to transfer calls from one support agent to another with Python and Flask

Let's build something amazing.