Flask-Twilio Documentation

Flask-Twilio Installation

Install the extension by running pip:

$ pip install Flask-Twilio

Set Up

Flask-Twilio can be initialized by first creating the application and then creating the flask_twilio.Twilio instance:

from flask import Flask
from flask_twilio import Twilio

app = Flask(__name__)
twilio = Twilio(app)

or using the factory method approach, creating the application first, then the flask_twilio.Twilio instance, and finally calling flask_twilio.Twilio.init_app():

twilio = Twilio()
app = Flask(__name__)

Making a Call

Making a call involves two steps: first, creating a call view, and second, placing a call. The view produces an XML file that serves as a script for Twilio to follow. Here is an example call view:

from flask_twilio import Response
from twilio.twiml.messaging_response import Message
from twilio.twiml.voice_response import Say

def call():
    resp = Response()
    resp.append(Say('This is a voice call from Twilio!', voice='female'))
    resp.append(Message('This is an SMS message from Twilio!'))
    return resp

The flask_twilio.Twilio.twiml decorator adds some validation and must come after the app.route decorator.

To place a call using this view, we use the flask_twilio.Twilio.call_for() method, which is based on flask.url_for():

twilio.call_for('call', to='+15005550006')

Sending a Text Message

The above example simultaneously places a voice call and sends a text message. If you only want to send a text message, there is a shortcut:

twilio.message('This is an SMS message from Twilio!', to='+15005550006')

Full Example Flask Application

See example.py on GitHub for a full example Flask application.

Configuration Variables

Flask-Twilio understands the following configuration values:

TWILIO_ACCOUNT_SID Your Twilio account SID.
TWILIO_AUTH_SID The SID that you use to authenticate with Twilio, if different from your account SID (for example, if you are using an API key).
TWILIO_AUTH_TOKEN Your Twilio authentication token.
TWILIO_FROM Your default ‘from’ phone number (optional). Note that there are some useful dummy numbers for testing.
SECRET_KEY Same as the standard Flask coniguration value. If provided, then Flask-Twilio will perform some sanity checking to ensure that requests from Twilio result from calls placed by this application.


class flask_twilio.Response(*args, **kwargs)

A response class for constructing TwiML documents, providing all of the verbs that are available through twilio.twiml.Response. See also https://www.twilio.com/docs/api/twiml.

class flask_twilio.Twilio(app=None)

This class is used to control Twilio calls.

call_for(endpoint, to, **values)

Initiate a Twilio call.

  • endpoint (str) – The view endpoint, as would be passed to flask.url_for().
  • to (str) – The destination phone number.
  • values (dict) – Additional keyword arguments to pass to flask.url_for().

call – An object representing the call in progress.

Return type:



An application-specific intance of twilio.rest.Client. Primarily for internal use.


Factory method.

message(body, to, **values)

Send an SMS message with Twilio.

  • body (str) – The body of the text message.
  • to (str) – The destination phone number.
  • values (dict) – Additional keyword arguments to pass to twilio.rest.resources.SmsMessages.create().

message – An object representing the message that was sent.

Return type:



An application-specific instance of itsdangerous.TimestampSigner, or None if no secret key is set. Primarily for internal use.


Decorator for marking view that will create TwiML documents.


An application-specific instance of twilio.request_validator.RequestValidator. Primarily for internal use.