[](https://github.com/twilio/twilio-python/actions/workflows/test-and-deploy.yml)

[](https://pypi.python.org/pypi/twilio)

[](https://pypi.python.org/pypi/twilio)

[](https://twil.io/learn-open-source)

The documentation for the Twilio API can be found [here][apidocs].

The Python library documentation can be found [here][libdocs].

`twilio-python` uses a modified version of [Semantic Versioning](https://semver.org) for all changes. [See this document](VERSIONS.md) for details.

This library supports the following Python implementations:

- Python 3.7

- Python 3.8

- Python 3.9

- Python 3.10

- Python 3.11

Install from PyPi using [pip](https://pip.pypa.io/en/latest/), a

package manager for Python.

pip3 install twilio

If pip install fails on Windows, check the path length of the directory. If it is greater 260 characters then enable [Long Paths](https://docs.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation) or choose other shorter location.

Don't have pip installed? Try installing it, by running this from the command

line:

curl https://bootstrap.pypa.io/get-pip.py | python

Or, you can [download the source code

(ZIP)](https://github.com/twilio/twilio-python/zipball/main 'twilio-python

source code') for `twilio-python`, and then run:

python3 setup.py install

Try sending yourself an SMS message. Save the following code sample to your computer with a text editor. Be sure to update the `account_sid`, `auth_token`, and `from_` phone number with values from your [Twilio account](https://console.twilio.com). The `to` phone number will be your own mobile phone.

from twilio.rest import Client

account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

auth_token = "your_auth_token"

client = Client(account_sid, auth_token)

message = client.messages.create(

to="+15558675309",

from_="+15017250604",

body="Hello from Python!")

print(message.sid)

Save the file as `send_sms.py`. In the terminal, `cd` to the directory containing the file you just saved then run:

python3 send_sms.py

After a brief delay, you will receive the text message on your phone.

We are introducing Client Credentials Flow-based OAuth 2.0 authentication. This feature is currently in beta and its implementation is subject to change.

API examples [here](https://github.com/twilio/twilio-python/blob/main/examples/public_oauth.py)

Organisation API examples [here](https://github.com/twilio/twilio-python/blob/main/examples/organization_api.py)

The `Twilio` client needs your Twilio credentials. You can either pass these directly to the constructor (see the code below) or via environment variables.

Authenticating with Account SID and Auth Token:

from twilio.rest import Client

account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

auth_token = "your_auth_token"

client = Client(account_sid, auth_token)

Authenticating with API Key and API Secret:

from twilio.rest import Client

api_key = "XXXXXXXXXXXXXXXXX"

api_secret = "YYYYYYYYYYYYYYYYYY"

account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

client = Client(api_key, api_secret, account_sid)

Alternatively, a `Client` constructor without these parameters will

look for `TWILIO_ACCOUNT_SID` and `TWILIO_AUTH_TOKEN` variables inside the

current environment.

We suggest storing your credentials as environment variables. Why? You'll never

have to worry about committing your credentials and accidentally posting them

somewhere public.

from twilio.rest import Client

client = Client()

To take advantage of Twilio's [Global Infrastructure](https://www.twilio.com/docs/global-infrastructure), specify the target Region and Edge for the client:

from twilio.rest import Client

client = Client(region='au1', edge='sydney')

A `Client` constructor without these parameters will also look for `TWILIO_REGION` and `TWILIO_EDGE` variables inside the current environment.

Alternatively, you may specify the edge and/or region after constructing the Twilio client:

from twilio.rest import Client

client = Client()

client.region = 'au1'

client.edge = 'sydney'

This will result in the `hostname` transforming from `api.twilio.com` to `api.sydney.au1.twilio.com`.

from twilio.rest import Client

account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

auth_token = "your_auth_token"

client = Client(account_sid, auth_token)

call = client.calls.create(to="9991231234",

from_="9991231234",

url="http://twimlets.com/holdmusic?Bucket=com.twilio.music.ambient")

print(call.sid)

from twilio.rest import Client

account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

auth_token = "your_auth_token"

client = Client(account_sid, auth_token)

call = client.calls.get("CA42ed11f93dc08b952027ffbc406d0868")

print(call.to)

The library automatically handles paging for you. Collections, such as `calls` and `messages`, have `list` and `stream` methods that page under the hood. With both `list` and `stream`, you can specify the number of records you want to receive (`limit`) and the maximum size you want each page fetch to be (`page_size`). The library will then handle the task for you.

`list` eagerly fetches all records and returns them as a list, whereas `stream` returns an iterator and lazily retrieves pages of records as you iterate over the collection. You can also page manually using the `page` method.

from twilio.rest import Client

account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

auth_token = "your_auth_token"

client = Client(account_sid, auth_token)

for sms in client.messages.list():

print(sms.to)

By default, the Twilio Client will make synchronous requests to the Twilio API. To allow for asynchronous, non-blocking requests, we've included an optional asynchronous HTTP client. When used with the Client and the accompanying `*_async` methods, requests made to the Twilio API will be performed asynchronously.

from twilio.http.async_http_client import AsyncTwilioHttpClient

from twilio.rest import Client

async def main():

account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

auth_token = "your_auth_token"

http_client = AsyncTwilioHttpClient()

client = Client(account_sid, auth_token, http_client=http_client)

message = await client.messages.create_async(to="+12316851234", from_="+15555555555",

body="Hello there!")

asyncio.run(main())

Log the API request and response data to the console:

import logging

client = Client(account_sid, auth_token)

logging.basicConfig()

client.http_client.logger.setLevel(logging.INFO)

Log the API request and response data to a file:

import logging

client = Client(account_sid, auth_token)

logging.basicConfig(filename='./log.txt')

client.http_client.logger.setLevel(logging.INFO)

Version 8.x of `twilio-python` exports an exception class to help you handle exceptions that are specific to Twilio methods. To use it, import `TwilioRestException` and catch exceptions as follows:

from twilio.rest import Client

from twilio.base.exceptions import TwilioRestException

account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

auth_token = "your_auth_token"

client = Client(account_sid, auth_token)

try:

message = client.messages.create(to="+12316851234", from_="+15555555555",

body="Hello there!")

except TwilioRestException as e:

print(e)

To control phone calls, your application needs to output [TwiML][twiml].

Use `twilio.twiml.Response` to easily create such responses.

from twilio.twiml.voice_response import VoiceResponse

r = VoiceResponse()

r.say("Welcome to twilio!")

print(str(r))

<?xml version="1.0" encoding="utf-8"?>

<Response><Say>Welcome to twilio!</Say></Response>

- [Learn how to create your own custom HTTP client](./advanced-examples/custom-http-client.md)

The `Dockerfile` present in this repository and its respective `twilio/twilio-python` Docker image are currently used by Twilio for testing purposes only.

If you need help installing or using the library, please check the [Twilio Support Help Center](https://support.twilio.com) first, and [file a support ticket](https://twilio.com/help/contact) if you don't find an answer to your question.

If you've instead found a bug in the library or would like new features added, go ahead and open issues or pull requests against this repo!

[apidocs]: https://www.twilio.com/docs/api

[twiml]: https://www.twilio.com/docs/api/twiml

[libdocs]: https://twilio.github.io/twilio-python