# twilio-python
[](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)
## Documentation
The documentation for the Twilio API can be found [here][apidocs].
The Python library documentation can be found [here][libdocs].
## Versions
`twilio-python` uses a modified version of [Semantic Versioning](https://semver.org) for all changes. [See this document](VERSIONS.md) for details.
### Supported Python Versions
This library supports the following Python implementations:
- Python 3.7
- Python 3.8
- Python 3.9
- Python 3.10
- Python 3.11
## Installation
Install from PyPi using [pip](https://pip.pypa.io/en/latest/), a
package manager for Python.
```shell
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:
```shell
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:
```shell
python3 setup.py install
```
> **Info**
> If the command line gives you an error message that says Permission Denied, try running the above commands with `sudo` (e.g., `sudo pip3 install twilio`).
### Test your installation
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.
```python
from twilio.rest import Client
# Your Account SID and Auth Token from console.twilio.com
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:
```shell
python3 send_sms.py
```
After a brief delay, you will receive the text message on your phone.
> **Warning**
> It's okay to hardcode your credentials when testing locally, but you should use environment variables to keep them secret before committing any code or deploying to production. Check out [How to Set Environment Variables](https://www.twilio.com/blog/2017/01/how-to-set-environment-variables.html) for more information.
## OAuth Feature for Twilio APIs
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)
## Use the helper library
### API Credentials
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:
```python
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:
```python
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.
```python
from twilio.rest import Client
client = Client()
```
### Specify Region and/or Edge
To take advantage of Twilio's [Global Infrastructure](https://www.twilio.com/docs/global-infrastructure), specify the target Region and/or Edge for the client:
```python
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:
```python
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`.
### Make a Call
```python
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)
```
### Get data about an existing call
```python
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)
```
### Iterate through records
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.
#### Use the `list` method
```python
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)
```
### Asynchronous API Requests
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.
```python
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())
```
### Enable Debug Logging
Log the API request and response data to the console:
```python
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:
```python
import logging
client = Client(account_sid, auth_token)
logging.basicConfig(filename='./log.txt')
client.http_client.logger.setLevel(logging.INFO)
```
### Handling Exceptions
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:
```python
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)
```
### Generating TwiML
To control phone calls, your application needs to output [TwiML][twiml].
Use `twilio.twiml.Response` to easily create such responses.
```python
from twilio.twiml.voice_response import VoiceResponse
r = VoiceResponse()
r.say("Welcome to twilio!")
print(str(r))
```
```xml
<?xml version="1.0" encoding="utf-8"?>
<Response><Say>Welcome to twilio!</Say></Response>
```
### Other advanced examples
- [Learn how to create your own custom HTTP client](./advanced-examples/custom-http-client.md)
### Docker Image
The `Dockerfile` present in this repository and its respective `twilio/twilio-python` Docker image are currently used by Twilio for testing purposes only.
### Getting help
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
Raw data
{
"_id": null,
"home_page": "https://github.com/twilio/twilio-python/",
"name": "twilio",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7.0",
"maintainer_email": null,
"keywords": "twilio, twiml",
"author": "Twilio",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/f2/4c/bd94644bf83bf67190a6668815fb7f77c91a087b5b7fe8e3f389ee9fa5ae/twilio-9.4.1.tar.gz",
"platform": null,
"description": "# twilio-python\n\n[](https://github.com/twilio/twilio-python/actions/workflows/test-and-deploy.yml)\n[](https://pypi.python.org/pypi/twilio)\n[](https://pypi.python.org/pypi/twilio)\n[](https://twil.io/learn-open-source)\n\n## Documentation\n\nThe documentation for the Twilio API can be found [here][apidocs].\n\nThe Python library documentation can be found [here][libdocs].\n\n## Versions\n\n`twilio-python` uses a modified version of [Semantic Versioning](https://semver.org) for all changes. [See this document](VERSIONS.md) for details.\n\n### Supported Python Versions\n\nThis library supports the following Python implementations:\n\n- Python 3.7\n- Python 3.8\n- Python 3.9\n- Python 3.10\n- Python 3.11\n\n## Installation\n\nInstall from PyPi using [pip](https://pip.pypa.io/en/latest/), a\npackage manager for Python.\n\n```shell\npip3 install twilio\n```\n\nIf 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.\n\nDon't have pip installed? Try installing it, by running this from the command\nline:\n\n```shell\ncurl https://bootstrap.pypa.io/get-pip.py | python\n```\n\nOr, you can [download the source code\n(ZIP)](https://github.com/twilio/twilio-python/zipball/main 'twilio-python\nsource code') for `twilio-python`, and then run:\n\n```shell\npython3 setup.py install\n```\n\n> **Info**\n> If the command line gives you an error message that says Permission Denied, try running the above commands with `sudo` (e.g., `sudo pip3 install twilio`).\n\n### Test your installation\n\nTry 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.\n\n```python\nfrom twilio.rest import Client\n\n# Your Account SID and Auth Token from console.twilio.com\naccount_sid = \"ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\"\nauth_token = \"your_auth_token\"\n\nclient = Client(account_sid, auth_token)\n\nmessage = client.messages.create(\n to=\"+15558675309\",\n from_=\"+15017250604\",\n body=\"Hello from Python!\")\n\nprint(message.sid)\n```\n\nSave the file as `send_sms.py`. In the terminal, `cd` to the directory containing the file you just saved then run:\n\n```shell\npython3 send_sms.py\n```\n\nAfter a brief delay, you will receive the text message on your phone.\n\n> **Warning**\n> It's okay to hardcode your credentials when testing locally, but you should use environment variables to keep them secret before committing any code or deploying to production. Check out [How to Set Environment Variables](https://www.twilio.com/blog/2017/01/how-to-set-environment-variables.html) for more information.\n\n## OAuth Feature for Twilio APIs\nWe are introducing Client Credentials Flow-based OAuth 2.0 authentication. This feature is currently in beta and its implementation is subject to change.\n\nAPI examples [here](https://github.com/twilio/twilio-python/blob/main/examples/public_oauth.py)\n\nOrganisation API examples [here](https://github.com/twilio/twilio-python/blob/main/examples/organization_api.py)\n\n## Use the helper library\n\n### API Credentials\n\nThe `Twilio` client needs your Twilio credentials. You can either pass these directly to the constructor (see the code below) or via environment variables.\n\nAuthenticating with Account SID and Auth Token:\n\n```python\nfrom twilio.rest import Client\n\naccount_sid = \"ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\"\nauth_token = \"your_auth_token\"\nclient = Client(account_sid, auth_token)\n```\n\nAuthenticating with API Key and API Secret:\n\n```python\nfrom twilio.rest import Client\n\napi_key = \"XXXXXXXXXXXXXXXXX\"\napi_secret = \"YYYYYYYYYYYYYYYYYY\"\naccount_sid = \"ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\"\nclient = Client(api_key, api_secret, account_sid)\n```\n\nAlternatively, a `Client` constructor without these parameters will\nlook for `TWILIO_ACCOUNT_SID` and `TWILIO_AUTH_TOKEN` variables inside the\ncurrent environment.\n\nWe suggest storing your credentials as environment variables. Why? You'll never\nhave to worry about committing your credentials and accidentally posting them\nsomewhere public.\n\n```python\nfrom twilio.rest import Client\nclient = Client()\n```\n\n### Specify Region and/or Edge\n\nTo take advantage of Twilio's [Global Infrastructure](https://www.twilio.com/docs/global-infrastructure), specify the target Region and/or Edge for the client:\n\n```python\nfrom twilio.rest import Client\n\nclient = Client(region='au1', edge='sydney')\n```\n\nA `Client` constructor without these parameters will also look for `TWILIO_REGION` and `TWILIO_EDGE` variables inside the current environment.\n\nAlternatively, you may specify the edge and/or region after constructing the Twilio client:\n\n```python\nfrom twilio.rest import Client\n\nclient = Client()\nclient.region = 'au1'\nclient.edge = 'sydney'\n```\n\nThis will result in the `hostname` transforming from `api.twilio.com` to `api.sydney.au1.twilio.com`.\n\n### Make a Call\n\n```python\nfrom twilio.rest import Client\n\naccount_sid = \"ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\"\nauth_token = \"your_auth_token\"\nclient = Client(account_sid, auth_token)\n\ncall = client.calls.create(to=\"9991231234\",\n from_=\"9991231234\",\n url=\"http://twimlets.com/holdmusic?Bucket=com.twilio.music.ambient\")\nprint(call.sid)\n```\n\n### Get data about an existing call\n\n```python\nfrom twilio.rest import Client\n\naccount_sid = \"ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\"\nauth_token = \"your_auth_token\"\nclient = Client(account_sid, auth_token)\n\ncall = client.calls.get(\"CA42ed11f93dc08b952027ffbc406d0868\")\nprint(call.to)\n```\n\n### Iterate through records\n\nThe 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.\n\n`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.\n\n#### Use the `list` method\n\n```python\nfrom twilio.rest import Client\n\naccount_sid = \"ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\"\nauth_token = \"your_auth_token\"\nclient = Client(account_sid, auth_token)\n\nfor sms in client.messages.list():\n print(sms.to)\n```\n\n### Asynchronous API Requests\n\nBy 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.\n\n```python\nfrom twilio.http.async_http_client import AsyncTwilioHttpClient\nfrom twilio.rest import Client\n\nasync def main():\n account_sid = \"ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\"\n auth_token = \"your_auth_token\"\n http_client = AsyncTwilioHttpClient()\n client = Client(account_sid, auth_token, http_client=http_client)\n\n message = await client.messages.create_async(to=\"+12316851234\", from_=\"+15555555555\",\n body=\"Hello there!\")\n\nasyncio.run(main())\n```\n\n### Enable Debug Logging\n\nLog the API request and response data to the console:\n\n```python\nimport logging\n\nclient = Client(account_sid, auth_token)\nlogging.basicConfig()\nclient.http_client.logger.setLevel(logging.INFO)\n```\n\nLog the API request and response data to a file:\n\n```python\nimport logging\n\nclient = Client(account_sid, auth_token)\nlogging.basicConfig(filename='./log.txt')\nclient.http_client.logger.setLevel(logging.INFO)\n```\n\n### Handling Exceptions\n\nVersion 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:\n\n```python\nfrom twilio.rest import Client\nfrom twilio.base.exceptions import TwilioRestException\n\naccount_sid = \"ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\"\nauth_token = \"your_auth_token\"\nclient = Client(account_sid, auth_token)\n\ntry:\n message = client.messages.create(to=\"+12316851234\", from_=\"+15555555555\",\n body=\"Hello there!\")\nexcept TwilioRestException as e:\n print(e)\n```\n\n### Generating TwiML\n\nTo control phone calls, your application needs to output [TwiML][twiml].\n\nUse `twilio.twiml.Response` to easily create such responses.\n\n```python\nfrom twilio.twiml.voice_response import VoiceResponse\n\nr = VoiceResponse()\nr.say(\"Welcome to twilio!\")\nprint(str(r))\n```\n\n```xml\n<?xml version=\"1.0\" encoding=\"utf-8\"?>\n<Response><Say>Welcome to twilio!</Say></Response>\n```\n\n### Other advanced examples\n\n- [Learn how to create your own custom HTTP client](./advanced-examples/custom-http-client.md)\n\n### Docker Image\n\nThe `Dockerfile` present in this repository and its respective `twilio/twilio-python` Docker image are currently used by Twilio for testing purposes only.\n\n### Getting help\n\nIf 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.\n\nIf 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!\n\n[apidocs]: https://www.twilio.com/docs/api\n[twiml]: https://www.twilio.com/docs/api/twiml\n[libdocs]: https://twilio.github.io/twilio-python\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Twilio API client and TwiML generator",
"version": "9.4.1",
"project_urls": {
"Homepage": "https://github.com/twilio/twilio-python/"
},
"split_keywords": [
"twilio",
" twiml"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8f6ad8cc06a41436ffe0e2ef4a049d06ce88b904027581b82df3d7d13d34d57d",
"md5": "b50d29894face2499b9f847121e169b5",
"sha256": "2447e041cec11167d7765aaa62ab1dae3b82b712245ca9a966096acd8b9f426f"
},
"downloads": -1,
"filename": "twilio-9.4.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "b50d29894face2499b9f847121e169b5",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.7.0",
"size": 1873180,
"upload_time": "2024-12-13T14:00:36",
"upload_time_iso_8601": "2024-12-13T14:00:36.220825Z",
"url": "https://files.pythonhosted.org/packages/8f/6a/d8cc06a41436ffe0e2ef4a049d06ce88b904027581b82df3d7d13d34d57d/twilio-9.4.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f24cbd94644bf83bf67190a6668815fb7f77c91a087b5b7fe8e3f389ee9fa5ae",
"md5": "8e5a72ef2792892b7a390e2ed80ca2ce",
"sha256": "e24c640696ccc726bba14160951da3cfc6b4bcb772fdcb3e8c16dc3cc851ef12"
},
"downloads": -1,
"filename": "twilio-9.4.1.tar.gz",
"has_sig": false,
"md5_digest": "8e5a72ef2792892b7a390e2ed80ca2ce",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7.0",
"size": 986984,
"upload_time": "2024-12-13T14:00:39",
"upload_time_iso_8601": "2024-12-13T14:00:39.343626Z",
"url": "https://files.pythonhosted.org/packages/f2/4c/bd94644bf83bf67190a6668815fb7f77c91a087b5b7fe8e3f389ee9fa5ae/twilio-9.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-13 14:00:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "twilio",
"github_project": "twilio-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "pygments",
"specs": [
[
">=",
"2.7.4"
]
]
},
{
"name": "requests",
"specs": [
[
">=",
"2.31.0"
]
]
},
{
"name": "PyJWT",
"specs": [
[
"<",
"3.0.0"
],
[
">=",
"2.0.0"
]
]
},
{
"name": "aiohttp",
"specs": [
[
">=",
"3.9.4"
]
]
},
{
"name": "aiohttp-retry",
"specs": [
[
"==",
"2.8.3"
]
]
},
{
"name": "certifi",
"specs": [
[
">=",
"2023.7.22"
]
]
}
],
"tox": true,
"lcname": "twilio"
}
JSON
