Menu

The Twilio Python Helper Library

The twilio-python helper library lets you interact with the Twilio API from your Python application.

This library is open-source, so if you find a feature missing or a bug, we encourage you to file an issue or contribute back to the twilio-python project.

Install the library

Prerequisites

Prior to installation, make sure that you are running a compatible version of Python. You can verify your version by running the following in your command line:

python3 --version

twilio-python supports the following versions of Python:

  • Python 3.7
  • Python 3.8
  • Python 3.9
  • Python 3.10
  • Python 3.11

If you are running on Python 3.6 or older and cannot upgrade, you can install version 7.x of twilio-python instead.

Install

The primary way to install the library is from PyPi using pip, a package manager for Python. Run this in a terminal from your project directory to install the library:

pip3 install twilio

You can also use easy_install. Run this in your terminal:

easy_install twilio

Manual installation

You can download the source code (ZIP) for twilio-python, and install it by running the following in the directory that contains the downloaded twilio-python library:

python3 setup.py install

If the command line gives you an error message that says Permission Denied in the middle of it, 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. The to phone number can be your own mobile phone.

Loading Code Sample...
        
        

        Python Helper Library SMS Test

        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

        You will receive the text message on your phone.

        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 for more information.

        Using the library

        Here are some code samples for key library use cases.

        Authenticate the client

        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)
        

        Create a new record

        from twilio.rest import Client
        
        account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
        auth_token = "your_auth_token"
        client = Client(account_sid, auth_token)
        
        call = client.calls.create(
          to="+14155551212",
          from_="+15017250604",
          url="http://demo.twilio.com/docs/voice.xml"
        )
        
        print(call.sid)
        

        Get an existing record

        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

        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)
        

        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.

        For more information about these methods, view the library docs.

        Specify Region and/or Edge

        To take advantage of Twilio's Global Infrastructure, specify the target Region and/or 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.

        Enable Debug Logging

        Log the API request and response data to the console:

        import logging
        
        client = Client(account, 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, 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:

        from twilio.rest import Client
        from twilio.base.exceptions import TwilioRestException
        
        account = "ACXXXXXXXXXXXXXXXXX"
        token = "YYYYYYYYYYYYYYYYYY"
        client = Client(account, token)
        
        try:
          # This could potentially throw an exception!
          message = client.messages.create(
            to="+15558675309", 
            from_="+15017250604",
            body="Hello there!")
        except TwilioRestException as err:
          # Implement your fallback code here
          print(err)
        

        More documentation

        Once you’re up and running with the Python helper library, you’ll find code samples using the latest version in our REST API docs in the documentation for every Twilio product. You can also find auto-generated library docs for the latest SDK here.

        Access version 7.x of the helper library

        The 8.x version of the Twilio Python helper library is API-compatible with the 7.x version. Older versions such as 7.x will continue to work, but are not supported. Should you need to install a previous version, you can do so with the following command.

        pip3 install twilio==7.16.5
        

        Getting help

        We’d love to hear your feedback on the Twilio Python Helper Library and help you past any issues you may encounter. Feel free to drop us a line, and we’ll make sure to get you sorted!

        Rate this page:

        Need some help?

        We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

        Thank you for your feedback!

        Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

        Sending your feedback...
        🎉 Thank you for your feedback!
        Something went wrong. Please try again.

        Thanks for your feedback!

        thanks-feedback-gif