twilio-python

twilio-python is Twilio’s official Python helper library for the Twilio REST API. It wraps every Twilio product — Programmable Messaging, Voice, Video, Verify, Lookups, Sync, Serverless, and dozens more — behind a single Client object whose resource tree mirrors Twilio’s API hierarchy, so client.messages.create(...) or client.calls.list(...) reads the same way the underlying REST endpoints are organized.

The library also ships TwiML generation helpers (twilio.twiml.voice_response, twilio.twiml.messaging_response) for building the XML responses Twilio expects from webhook callbacks, plus JWT-based access-token utilities for client-side Voice, Video, and Sync SDKs. Both synchronous (requests-based) and asynchronous (aiohttp-based, via *_async methods) request paths are supported from the same client instance.

Most of the resource and model code under twilio/rest/ is generated from Twilio’s OpenAPI specification, which keeps the library’s 30+ product surfaces consistent with each other and with Twilio’s public API as it evolves.

What You Get

• A single Client object whose attribute tree (client.messages, client.calls, client.verify, …) mirrors Twilio’s REST API resource hierarchy across 30+ products
• Automatic paging on list endpoints via .list() (eager) and .stream() (lazy iterator), with page_size and limit controls
• TwiML response builders (VoiceResponse, MessagingResponse) for generating the XML Twilio expects from webhook callbacks
• An async HTTP client (AsyncTwilioHttpClient) with matching *_async methods on every resource, for non-blocking request flows
• JWT access-token helpers for issuing client-side tokens used by Twilio’s Voice, Video, and Sync client SDKs
• Built-in region/edge configuration for routing requests through Twilio’s global infrastructure (e.g. Client(region='au1', edge='sydney'))

Common Use Cases

• Sending and receiving SMS/MMS messages from a Python backend via client.messages.create()
• Placing and managing outbound phone calls and querying call records with client.calls
• Generating TwiML to control how Twilio handles an inbound call or message webhook
• Issuing short-lived access tokens for browser or mobile clients using Twilio Voice, Video, or Sync
• Verifying phone numbers or building 2FA flows against the Twilio Verify API
• Making high-throughput async requests to the Twilio API from an asyncio-based service

Under The Hood

Architecture The library is built around a Client (in twilio/rest/__init__.py, extending twilio/base/client_base.py) that lazily exposes one domain object per Twilio product (Api, Messaging, Verify, Voice, and 30+ others), each rooted at a Domain (twilio/base/domain.py) that knows its subdomain base URL (e.g. api.twilio.com, lookups.twilio.com) and performs the actual HTTP request. Beneath each domain, resources follow a consistent List/Context/Instance pattern (twilio/base/list_resource.py, instance_context.py, instance_resource.py) that mirrors the REST hierarchy one-to-one — client.calls is a list resource, client.calls('CAxxxx') is a context bound to one call instance, .fetch()/.update()/.delete() operate on it, and nested resources like recordings hang off the call context the same way they hang off the URL path. This generated, path-mirroring structure is what lets the SDK scale to dozens of Twilio products without diverging conventions between them.

Tech Stack Pure Python 3.10+ (setup.py declares support back to 3.7, README states 3.10+ is actively tested), using requests for synchronous HTTP and aiohttp + aiohttp-retry for the async request path, PyJWT for signing and verifying access tokens, and setuptools/pyproject-style packaging. CI runs on GitHub Actions across the supported Python matrix with an Artifactory-backed dependency pipeline and a tox.ini for local multi-version testing; a Dockerfile is maintained for Twilio’s internal test tooling.

Code Quality The tests/ tree includes tests/unit with per-domain unit tests (20+ top-level test files) plus a tests/cluster suite and a holodeck.py request-mocking harness that intercepts HTTP calls to assert exact request bodies/headers without hitting the live API. Core client and base classes use Python type hints throughout (Optional, Dict, Tuple from typing). The bulk of twilio/rest/ is auto-generated from Twilio’s OpenAPI spec (files carry a generator header and “do not edit manually” notice), which trades hand-written flexibility for cross-product consistency and keeps behavior in lockstep with the published API contract.

API Design The library’s defining design choice is that its object graph is the API: navigating client.<product>.<resource> and chaining .create()/.fetch()/.update()/.delete()/.list()/.stream() requires no separate reference for how a given Twilio endpoint is shaped, because the Python attribute path is the same shape as the REST path. Sync and async are exposed as parallel methods on the same objects rather than a separate client class, so switching a call site to create_async() doesn’t require restructuring how the client is constructed or configured. Pagination defaults to eager .list() for convenience but offers .stream() for lazy iteration over large result sets, letting callers opt into memory-conscious paging without changing call syntax.