Skip to contentSkip to navigationSkip to topbar
On this page

Programmable Voice quickstart for Python


This quickstart shows you how to build a Python application that can make and receive phone calls.


Get a phone number

get-a-phone-number page anchor

Log in to your Twilio account(link takes you to an external page) or sign up for a new one(link takes you to an external page).

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

  1. Go to Phone Numbers > Manage > Buy a Number(link takes you to an external page).
  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(link takes you to an external page) before continuing.


Activate a virtual environment

activate-a-virtual-environment page anchor

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:

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

Install Flask and the Twilio Python helper library

install-flask-and-the-twilio-python-helper-library page anchor

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

pip install twilio Flask

Make an outgoing phone call with Python

make-an-outgoing-phone-call-with-python page anchor

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

Make a phone call using TwilioLink to code sample: Make a phone call using Twilio
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.

Replace the placeholder credential values

replace-the-placeholder-credential-values page anchor

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

  1. Log in to the Twilio Console(link takes you to an external page).
  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.
(error)

Danger

This quickstart hardcodes your credentials to get you started quickly. Use environment variables and API keys to keep credentials secret and control access when you deploy to production.

Replace the to and from phone numbers

replace-the-to-and-from-phone-numbers page anchor

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.

(information)

Twilio trial account limitations

Twilio trial accounts limit outgoing phone calls to phone numbers you have verified with Twilio. To verify your phone numbers, use your Twilio Console's Verified Caller IDs(link takes you to an external page). To learn about other trial account limitations, see how to work with your free Twilio trial account.


Take a phone call with your Twilio number

take-a-phone-call-with-your-twilio-number page anchor

Create a file in your project directory called answer_phone.py. Add the below 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

Expose your local server to the Internet with ngrok

expose-your-local-server-to-the-internet-with-ngrok page anchor

If you don't already use ngrok then download and install it(link takes you to an external page).

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."

Configure your Twilio webhook

configure-your-twilio-webhook page anchor
  1. Navigate to the Active Numbers(link takes you to an external page) 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:

Let's build something amazing.