Programmable Voice quickstart for Python
This quickstart shows you how to build a Python application that can make and receive phone calls.
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:
- Go to Phone Numbers > Manage > Buy a Number.
- Under Capabilities, select Voice.
- Click Search. The page displays a list of available voice-capable phone numbers.
- 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:
1python --version2Python 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:
1python -m venv quickstart2source quickstart/bin/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/install2import os3from twilio.rest import Client45# Find your Account SID and Auth Token at twilio.com/console6# and set the environment variables. See http://twil.io/secure7account_sid = os.environ["TWILIO_ACCOUNT_SID"]8auth_token = os.environ["TWILIO_AUTH_TOKEN"]9client = Client(account_sid, auth_token)1011call = client.calls.create(12url="http://demo.twilio.com/docs/voice.xml",13to="+15558675310",14from_="+15017122661",15)1617print(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.
- Log in to the Twilio Console.
- Copy the Account SID and replace
os.environ["TWILIO_ACCOUNT_SID"]
with it in themake_call.py
file. - Copy the Auth Token and replace
os.environ["TWILIO_AUTH_TOKEN"]
with it.
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 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.
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. To learn about other trial account limitations, see how to work with your free Twilio trial account.
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.
1from flask import Flask2from twilio.twiml.voice_response import VoiceResponse34app = Flask(__name__)56@app.route("/", methods=['GET', 'POST'])7def answer_call():8"""Respond to incoming phone calls with a brief message."""9# Start our TwiML response10resp = VoiceResponse()1112# Read a message aloud to the caller13resp.say("Thank you for calling! Have a great day.", voice='Polly.Amy')1415return str(resp)1617if __name__ == "__main__":18app.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: on3* Running on http://127.0.0.1:50004Press 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:
1Session Status online2Version 3.23.23Web Interface http://127.0.0.1:40404Forwarding https://ff4660c91380.ngrok.app -> http://localhost:500056Connections ttl opn rt1 rt5 p50 p9070 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."
- Navigate to the Active Numbers page in the Twilio Console.
- Click on the phone number you purchased earlier.
- Visit the Configure tab and find the Voice Configuration section.
- 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
). - 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.