0
# Twilio Python SDK
1

2
A comprehensive Python client library for the Twilio communications platform, enabling developers to programmatically send SMS messages, make voice calls, manage phone numbers, and handle various telecommunications services through Twilio's APIs. It offers both synchronous and asynchronous HTTP clients for API requests, supports TwiML generation for call flow control, provides OAuth 2.0 authentication capabilities, and includes extensive error handling with custom exception classes.
3

4
## Package Information
5

6
- **Package Name**: twilio
7
- **Language**: Python
8
- **Installation**: `pip install twilio`
9

10
## Core Imports
11

12
```python
13
from twilio.rest import Client
14
```
15

16
Common for TwiML generation:
17

18
```python
19
from twilio.twiml.voice_response import VoiceResponse
20
from twilio.twiml.messaging_response import MessagingResponse
21
```
22

23
Authentication and JWT:
24

25
```python
26
from twilio.jwt.access_token import AccessToken
27
from twilio.jwt.access_token.grants import VideoGrant, ChatGrant
28
```
29

30
Request validation:
31

32
```python
33
from twilio.request_validator import RequestValidator
34
```
35

36
## Basic Usage
37

38
```python
39
from twilio.rest import Client
40

41
# Initialize the client
42
client = Client('account_sid', 'auth_token')
43

44
# Send an SMS message
45
message = client.messages.create(
46
    body="Hello from Python!",
47
    from_='+1234567890',
48
    to='+0987654321'
49
)
50
print(message.sid)
51

52
# Make a voice call
53
call = client.calls.create(
54
    twiml='<Response><Say>Hello World</Say></Response>',
55
    from_='+1234567890',
56
    to='+0987654321'
57
)
58
print(call.sid)
59

60
# Generate TwiML for voice response
61
from twilio.twiml.voice_response import VoiceResponse
62

63
response = VoiceResponse()
64
response.say('Hello from Twilio!')
65
response.dial('+1234567890')
66
print(response)  # Outputs XML
67
```
68

69
## Architecture
70

71
The Twilio Python SDK follows a hierarchical resource structure:
72

73
- **Client**: Main entry point providing access to all Twilio services
74
- **Services**: Domain-specific APIs (messaging, voice, video, etc.)
75
- **Resources**: API endpoints organized as lists and instances
76
- **TwiML**: XML generation classes for call/message flow control
77
- **JWT**: Token-based authentication for client-side applications
78
- **Infrastructure**: HTTP clients, authentication strategies, and utilities
79

80
This design provides both high-level convenience methods and low-level resource access, supporting everything from simple SMS sending to complex multi-party video conferences and automated call flows.
81

82
## Capabilities
83

84
### REST Client
85

86
The main Twilio client class providing access to all Twilio services and resources. Handles authentication, regional configuration, and provides both service-specific and direct resource access patterns.
87

88
```python { .api }
89
class Client:
90
    def __init__(
91
        self,
92
        username: str = None,
93
        password: str = None,
94
        account_sid: str = None,
95
        region: str = None,
96
        http_client: HttpClient = None,
97
        environment: dict = None,
98
        edge: str = None,
99
        user_agent_extensions: list = None,
100
        credential_provider: CredentialProvider = None
101
    ): ...
102
    
103
    # Service domain properties
104
    api: ApiV2010
105
    messaging: MessagingV1  
106
    chat: ChatV1
107
    video: VideoV1
108
    voice: VoiceV1
109
    verify: VerifyV2
110
    # ... 25+ more services
111
    
112
    # Direct resource shortcuts  
113
    messages: MessageList
114
    calls: CallList
115
    # ... many more
116
```
117

118
[REST Client](./rest-client.md)
119

120
### Core Communications
121

122
Fundamental telecommunications capabilities including SMS/MMS messaging, voice calls, phone number management, and basic account operations. These APIs form the core of Twilio's communication platform.
123

124
```python { .api }
125
# Message sending
126
def create(
127
    to: str,
128
    from_: str = None,
129
    body: str = None,
130
    media_url: list = None,
131
    **kwargs
132
) -> MessageInstance: ...
133

134
# Voice calls
135
def create(
136
    to: str,
137
    from_: str = None,
138
    twiml: str = None,
139
    url: str = None,
140
    **kwargs
141
) -> CallInstance: ...
142
```
143

144
[Core Communications](./core-communications.md)
145

146
### TwiML Generation
147

148
XML markup language generation for controlling voice calls and messaging flows. Provides Python classes that generate TwiML XML for call routing, text-to-speech, user input collection, and message handling.
149

150
```python { .api }
151
class VoiceResponse:
152
    def say(self, message: str, **kwargs) -> Say: ...
153
    def dial(self, number: str = None, **kwargs) -> Dial: ...
154
    def gather(self, **kwargs) -> Gather: ...
155
    def record(self, **kwargs) -> Record: ...
156
    def hangup(self) -> Hangup: ...
157
    def to_xml(self) -> str: ...
158

159
class MessagingResponse:
160
    def message(self, body: str = None, **kwargs) -> Message: ...
161
    def redirect(self, url: str, **kwargs) -> Redirect: ...
162
    def to_xml(self) -> str: ...
163

164
class FaxResponse:
165
    def receive(self, **kwargs) -> Receive: ...
166
    def reject(self, reason: str = None) -> Reject: ...
167
    def to_xml(self) -> str: ...
168
```
169

170
[TwiML Generation](./twiml-generation.md)
171

172
### Authentication & JWT
173

174
Token-based authentication system for client-side applications and access control. Includes access tokens, capability tokens, and various grant types for different Twilio services.
175

176
```python { .api }
177
class AccessToken:
178
    def __init__(
179
        self,
180
        account_sid: str,
181
        signing_key_sid: str,
182
        secret: str,
183
        ttl: int = 3600,
184
        identity: str = None,
185
        nbf: int = None
186
    ): ...
187
    
188
    def add_grant(self, grant: AccessTokenGrant) -> AccessToken: ...
189
    def to_jwt(self) -> str: ...
190

191
# Grant types
192
class VideoGrant(AccessTokenGrant): ...
193
class ChatGrant(AccessTokenGrant): ...
194
class VoiceGrant(AccessTokenGrant): ...
195
class SyncGrant(AccessTokenGrant): ...
196
```
197

198
[Authentication & JWT](./authentication-jwt.md)
199

200
### Advanced Services
201

202
Specialized Twilio services including video conferencing, real-time chat, identity verification, push notifications, visual workflows, serverless functions, and contact center solutions.
203

204
```python { .api }
205
# Video service
206
video.rooms.create(
207
    unique_name: str = None,
208
    type: str = None,
209
    **kwargs
210
) -> RoomInstance
211

212
# Chat/Conversations
213
conversations.conversations.create(
214
    friendly_name: str = None,
215
    **kwargs
216
) -> ConversationInstance
217

218
# Verify service  
219
verify.services.create(
220
    friendly_name: str,
221
    **kwargs
222
) -> ServiceInstance
223
```
224

225
[Advanced Services](./advanced-services.md)
226

227
### Webhooks & Validation
228

229
Request signature validation for securing webhook endpoints and ensuring requests originate from Twilio. Provides utilities for computing and validating request signatures.
230

231
```python { .api }
232
class RequestValidator:
233
    def __init__(self, auth_token: str): ...
234
    
235
    def validate(
236
        self,
237
        uri: str,
238
        params: dict,
239
        signature: str
240
    ) -> bool: ...
241
    
242
    def compute_signature(
243
        self,
244
        uri: str,
245
        params: dict
246
    ) -> str: ...
247
```
248

249
[Webhooks & Validation](./webhooks-validation.md)
250

251
### Infrastructure
252

253
Low-level infrastructure including HTTP clients, authentication strategies, credential providers, base classes, and exception handling. These components support the high-level APIs and can be customized for advanced use cases.
254

255
```python { .api }
256
class TwilioHttpClient(HttpClient):
257
    def request(
258
        self,
259
        method: str,
260
        uri: str,
261
        data: dict = None,
262
        headers: dict = None,
263
        **kwargs
264
    ) -> Response: ...
265

266
class TwilioException(Exception): ...
267
class TwilioRestException(TwilioException): ...
268
```
269

270
[Infrastructure](./infrastructure.md)
271

272
## Error Handling
273

274
The SDK provides comprehensive error handling with specific exception types:
275

276
```python { .api }
277
class TwilioException(Exception):
278
    """Base exception for all Twilio errors"""
279

280
class TwilioRestException(TwilioException):
281
    """REST API errors with detailed information"""
282
    status: int
283
    uri: str  
284
    code: int
285
    message: str
286
    details: dict
287
    more_info: str
288
```
289

290
Common error handling pattern:
291

292
```python
293
from twilio.base.exceptions import TwilioRestException
294

295
try:
296
    message = client.messages.create(
297
        body="Hello World",
298
        from_='+1234567890',
299
        to='+invalid'
300
    )
301
except TwilioRestException as e:
302
    print(f"Error {e.code}: {e.message}")
303
    print(f"More info: {e.more_info}")
304
```