0
# Twilio Node.js SDK
1

2
The Twilio Node.js SDK is a comprehensive library that provides a complete interface to the Twilio communications platform. It enables developers to integrate SMS, voice, video, chat, and other communication services into their Node.js applications with full TypeScript support and modern async/await patterns.
3

4
## Package Information
5

6
- **Package Name**: twilio
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install twilio`
10

11
## Core Imports
12

13
```typescript
14
import TwilioSDK from "twilio";
15

16
// Create client with auto-discovery of credentials
17
const client = TwilioSDK(process.env.TWILIO_ACCOUNT_SID, process.env.TWILIO_AUTH_TOKEN);
18

19
// Access individual components via namespace properties
20
const { 
21
  Twilio, 
22
  jwt, 
23
  twiml,
24
  validateRequest,
25
  webhook,
26
  ClientCredentialProviderBuilder,
27
  OrgsCredentialProviderBuilder,
28
  NoAuthCredentialProvider,
29
  RestException,
30
  RequestClient
31
} = TwilioSDK;
32

33
// Access nested components
34
const { AccessToken, ClientCapability, ValidationToken } = jwt;
35
const { VoiceResponse, MessagingResponse, FaxResponse } = twiml;
36
const { TaskRouterCapability, util } = jwt.taskrouter;
37
```
38

39
For CommonJS:
40

41
```javascript
42
const TwilioSDK = require("twilio");
43
const client = TwilioSDK(accountSid, authToken);
44

45
// Access components the same way
46
const { jwt, twiml, validateRequest } = TwilioSDK;
47
```
48

49
## Basic Usage
50

51
```typescript
52
import TwilioSDK from "twilio";
53

54
// Initialize the Twilio client
55
const client = TwilioSDK(
56
  process.env.TWILIO_ACCOUNT_SID,
57
  process.env.TWILIO_AUTH_TOKEN
58
);
59

60
// Send an SMS message
61
const message = await client.messages.create({
62
  body: "Hello from Twilio!",
63
  from: "+1234567890",
64
  to: "+0987654321"
65
});
66

67
// Make a voice call
68
const call = await client.calls.create({
69
  url: "http://demo.twilio.com/docs/voice.xml",
70
  from: "+1234567890",
71
  to: "+0987654321"
72
});
73

74
// Generate TwiML response
75
const { twiml } = TwilioSDK;
76
const response = new twiml.VoiceResponse();
77
response.say("Hello World");
78
console.log(response.toString());
79
```
80

81
## Architecture
82

83
The Twilio SDK is organized around several key architectural components:
84

85
- **REST Client**: The main `Twilio` class provides access to 38+ service domains through a unified interface
86
- **Service Domains**: Each Twilio service (messaging, voice, video, etc.) is exposed as a separate domain with its own resources and methods
87
- **TwiML Builders**: Declarative classes for generating Twilio Markup Language (TwiML) responses for webhooks
88
- **JWT Utilities**: Token generation and validation for client-side applications and capability management
89
- **Webhook Validation**: Security utilities for validating incoming Twilio requests
90
- **Credential Providers**: Flexible authentication strategies including OAuth2 and API keys
91
- **HTTP Client**: Advanced HTTP client with automatic retries, request signing, and comprehensive error handling
92

93
## Capabilities
94

95
### REST API Client
96

97
The core REST client providing access to all Twilio services including messaging, voice, video, and platform services. Supports automatic authentication, request retries, and comprehensive error handling.
98

99
```typescript { .api }
100
function TwilioSDK(
101
  accountSid?: string, 
102
  authToken?: string, 
103
  opts?: ClientOpts
104
): Twilio;
105

106
interface ClientOpts {
107
  httpClient?: RequestClient;
108
  accountSid?: string;
109
  env?: NodeJS.ProcessEnv;
110
  edge?: string;
111
  region?: string;
112
  lazyLoading?: boolean;
113
  logLevel?: string;
114
  userAgentExtensions?: string[];
115
  autoRetry?: boolean;
116
  maxRetryDelay?: number;
117
  maxRetries?: number;
118
  timeout?: number;
119
  keepAlive?: boolean;
120
}
121
```
122

123
[REST API Client](./rest-client.md)
124

125
### TwiML Generation
126

127
TwiML (Twilio Markup Language) builders for creating XML responses to handle incoming calls, messages, and faxes. Provides a fluent, type-safe interface for constructing complex call flows and messaging logic.
128

129
```typescript { .api }
130
class VoiceResponse {
131
  constructor();
132
  say(message?: string, attributes?: SayAttributes): Say;
133
  play(url?: string, attributes?: PlayAttributes): Play;
134
  gather(attributes?: GatherAttributes): Gather;
135
  dial(number?: string, attributes?: DialAttributes): Dial;
136
  record(attributes?: RecordAttributes): Record;
137
  redirect(url?: string, attributes?: RedirectAttributes): Redirect;
138
  pause(attributes?: PauseAttributes): Pause;
139
  hangup(): Hangup;
140
  reject(attributes?: RejectAttributes): Reject;
141
}
142

143
class MessagingResponse {
144
  constructor();
145
  message(body?: string, attributes?: MessageAttributes): Message;
146
  redirect(url?: string, attributes?: RedirectAttributes): Redirect;
147
}
148
```
149

150
[TwiML Generation](./twiml.md)
151

152
### JWT Authentication
153

154
JWT token generation and validation for Twilio Client applications, TaskRouter workers, and service capabilities. Supports access tokens, client capabilities, and request validation.
155

156
```typescript { .api }
157
class AccessToken {
158
  constructor(accountSid: string, keySid: string, secret: string, options?: AccessTokenOptions);
159
  addGrant(grant: Grant): AccessToken;
160
  toJwt(algorithm?: string): string;
161
}
162

163
class ClientCapability {
164
  constructor(options: ClientCapabilityOptions);
165
  addScope(scope: Scope): ClientCapability;
166
  toJwt(): string;
167
}
168
```
169

170
[JWT Authentication](./jwt.md)
171

172
### Webhook Validation
173

174
Security utilities for validating incoming Twilio webhook requests to ensure they originate from Twilio servers. Includes signature validation and Express.js middleware support.
175

176
```typescript { .api }
177
function validateRequest(
178
  authToken: string,
179
  twilioSignature: string,
180
  url: string,
181
  params: object
182
): boolean;
183

184
function validateRequestWithBody(
185
  authToken: string,
186
  twilioSignature: string,
187
  url: string,
188
  body: string
189
): boolean;
190

191
function webhook(options?: WebhookOptions): (req: any, res: any, next: Function) => void;
192
```
193

194
[Webhook Validation](./webhooks.md)
195

196
### Credential Providers
197

198
Advanced authentication strategies for OAuth2, organizational accounts, and custom credential management. Enables flexible authentication patterns beyond basic username/password.
199

200
```typescript { .api }
201
class ClientCredentialProviderBuilder {
202
  setClientId(clientId: string): ClientCredentialProviderBuilder;
203
  setClientSecret(clientSecret: string): ClientCredentialProviderBuilder;
204
  setTokenManager(tokenManager: TokenManager): ClientCredentialProviderBuilder;
205
  build(): ClientCredentialProvider;
206
}
207

208
class NoAuthCredentialProvider {
209
  constructor();
210
  toAuthStrategy(): AuthStrategy;
211
}
212
```
213

214
[Credential Providers](./credential-providers.md)
215

216
### HTTP Client Utilities
217

218
Core utilities for HTTP request handling and error management used throughout the SDK.
219

220
```typescript { .api }
221
class RestException extends Error {
222
  status: number;
223
  code: number;
224
  moreInfo: string;
225
  detail: string;
226
  
227
  constructor(response: any);
228
}
229

230
class RequestClient {
231
  constructor(options?: RequestClientOptions);
232
  request<T>(opts: RequestOpts): Promise<T>;
233
}
234

235
interface RequestClientOptions {
236
  timeout?: number;
237
  keepAlive?: boolean;
238
  keepAliveMsecs?: number;
239
  maxSockets?: number;
240
  maxTotalSockets?: number;
241
  maxFreeSockets?: number;
242
  ca?: string | Buffer;
243
}
244
```
245

246
## Types
247

248
```typescript { .api }
249
interface ClientOpts {
250
  httpClient?: RequestClient;
251
  accountSid?: string;
252
  env?: NodeJS.ProcessEnv;
253
  edge?: string;
254
  region?: string;
255
  lazyLoading?: boolean;
256
  logLevel?: string;
257
  userAgentExtensions?: string[];
258
  autoRetry?: boolean;
259
  maxRetryDelay?: number;
260
  maxRetries?: number;
261
  validationClient?: ValidationClientOptions;
262
  timeout?: number;
263
  keepAlive?: boolean;
264
  keepAliveMsecs?: number;
265
  maxSockets?: number;
266
  maxTotalSockets?: number;
267
  maxFreeSockets?: number;
268
  scheduling?: "fifo" | "lifo" | undefined;
269
  ca?: string | Buffer;
270
}
271

272
interface RequestOpts {
273
  method?: HttpMethod;
274
  uri?: string;
275
  username?: string;
276
  password?: string;
277
  authStrategy?: AuthStrategy;
278
  headers?: Headers;
279
  params?: object;
280
  data?: object;
281
  timeout?: number;
282
  allowRedirects?: boolean;
283
  logLevel?: string;
284
}
285

286
type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "HEAD" | "PATCH";
287

288
interface Headers {
289
  [key: string]: string;
290
}
291
```