Repository files navigation

The documentation for the Twilio API can be foundhere.

The Node library documentation can be foundhere.

twilio-node uses a modified version ofSemantic Versioning for all changes.See this document for details.

This library supports the following Node.js implementations:

• Node.js 14
• Node.js 16
• Node.js 18
• Node.js 20
• Node.js lts(22)

TypeScript is supported for TypeScript version 2.9 and above.

WarningDo not use this Node.js library in a front-end application. Doing so can expose your Twilio credentials to end-users as part of the bundled HTML/JavaScript sent to their browser.

npm install twilio oryarn add twilio

To make sure the installation was successful, try sending yourself an SMS message, like this:

// Your AccountSID and Auth Token from console.twilio.comconstaccountSid='ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';constauthToken='your_auth_token';constclient=require('twilio')(accountSid,authToken);client.messages.create({body:'Hello from twilio-node',to:'+12345678901',// Text your numberfrom:'+12345678901',// From a valid Twilio number}).then((message)=>console.log(message.sid));

After a brief delay, you will receive the text message on your phone.

WarningIt'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 outHow to Set Environment Variables for more information.

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 exampleshere

Organisation API exampleshere

Check out thesecode examples in JavaScript and TypeScript to get up and running quickly.

twilio-node supports credential storage in environment variables. If no credentials are provided when instantiating the Twilio client (e.g.,const client = require('twilio')();), the values in following env vars will be used:TWILIO_ACCOUNT_SID andTWILIO_AUTH_TOKEN.

If your environment requires SSL decryption, you can set the path to CA bundle in the env varTWILIO_CA_BUNDLE.

If you invoke any V2010 operations without specifying an account SID,twilio-node will automatically use theTWILIO_ACCOUNT_SID value that the client was initialized with. This is useful for when you'd like to, for example, fetch resources for your main account but also your subaccount. See below:

// Your Account SID, Subaccount SID Auth Token from console.twilio.comconstaccountSid=process.env.TWILIO_ACCOUNT_SID;constauthToken=process.env.TWILIO_AUTH_TOKEN;constsubaccountSid=process.env.TWILIO_ACCOUNT_SUBACCOUNT_SID;constclient=require('twilio')(accountSid,authToken);constmainAccountCalls=client.api.v2010.account.calls.list;// SID not specified, so defaults to accountSidconstsubaccountCalls=client.api.v2010.account(subaccountSid).calls.list;// SID specified as subaccountSid

twilio-node supports lazy loading required modules for faster loading time. Lazy loading is enabled by default. To disable lazy loading, simply instantiate the Twilio client with thelazyLoading flag set tofalse:

// Your Account SID and Auth Token from console.twilio.comconstaccountSid=process.env.TWILIO_ACCOUNT_SID;constauthToken=process.env.TWILIO_AUTH_TOKEN;constclient=require('twilio')(accountSid,authToken,{lazyLoading:false,});

twilio-node supports automatic retry with exponential backoff when API requests receive anError 429 response. This retry with exponential backoff feature is disabled by default. To enable this feature, instantiate the Twilio client with theautoRetry flag set totrue.

Optionally, the maximum number of retries performed by this feature can be set with themaxRetries flag. The default maximum number of retries is3.

constaccountSid=process.env.TWILIO_ACCOUNT_SID;constauthToken=process.env.TWILIO_AUTH_TOKEN;constclient=require('twilio')(accountSid,authToken,{autoRetry:true,maxRetries:3,});

twilio-node allows you to set HTTP Agent Options in the Request Client. This feature allows you to re-use your connections. To enable this feature, instantiate the Twilio client with thekeepAlive flag set totrue.

Optionally, the socket timeout and maximum number of sockets can also be set. See the example below:

constaccountSid=process.env.TWILIO_ACCOUNT_SID;constauthToken=process.env.TWILIO_AUTH_TOKEN;constclient=require('twilio')(accountSid,authToken,{timeout:30000,// HTTPS agent's socket timeout in milliseconds, default is 30000keepAlive:true,// https.Agent keepAlive option, default is falsekeepAliveMsecs:1000,// https.Agent keepAliveMsecs option in milliseconds, default is 1000maxSockets:20,// https.Agent maxSockets option, default is 20maxTotalSockets:100,// https.Agent maxTotalSockets option, default is 100maxFreeSockets:5,// https.Agent maxFreeSockets option, default is 5scheduling:"lifo",// https.Agent scheduling option, default is 'lifo'});

To take advantage of Twilio'sGlobal Infrastructure, specify the target Region and/or Edge for the client:

constaccountSid=process.env.TWILIO_ACCOUNT_SID;constauthToken=process.env.TWILIO_AUTH_TOKEN;constclient=require('twilio')(accountSid,authToken,{region:'au1',edge:'sydney',});

Alternatively, specify the edge and/or region after constructing the Twilio client:

constclient=require('twilio')(accountSid,authToken);client.region='au1';client.edge='sydney';

This will result in thehostname transforming fromapi.twilio.com toapi.sydney.au1.twilio.com.

The library automatically handles paging for you. Collections, such ascalls andmessages, havelist andeach methods that page under the hood. With bothlist andeach, you can specify the number of records you want to receive (limit) and the maximum size you want each page fetch to be (pageSize). The library will then handle the task for you.

list eagerly fetches all records and returns them as a list, whereaseach streams records and lazily retrieves pages of records as you iterate over the collection. You can also page manually using thepage method.

For more information about these methods, view theauto-generated library docs.

// Your Account SID and Auth Token from console.twilio.comconstaccountSid='ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';constauthToken='your_auth_token';constclient=require('twilio')(accountSid,authToken);client.calls.each((call)=>console.log(call.direction));

There are two ways to enable debug logging in the default HTTP client. You can create an environment variable calledTWILIO_LOG_LEVEL and set it todebug or you can set the logLevel variable on the client as debug:

constaccountSid=process.env.TWILIO_ACCOUNT_SID;constauthToken=process.env.TWILIO_AUTH_TOKEN;constclient=require('twilio')(accountSid,authToken,{logLevel:'debug',});

You can also set the logLevel variable on the client after constructing the Twilio client:

constclient=require('twilio')(accountSid,authToken);client.logLevel='debug';

To assist with debugging, the library allows you to access the underlying request and response objects. This capability is built into the default HTTP client that ships with the library.

For example, you can retrieve the status code of the last response like so:

constaccountSid='ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';constauthToken='your_auth_token';constclient=require('twilio')(accountSid,authToken);client.messages.create({to:'+14158675309',from:'+14258675310',body:'Ahoy!',}).then(()=>{// Access details about the last requestconsole.log(client.lastRequest.method);console.log(client.lastRequest.url);console.log(client.lastRequest.auth);console.log(client.lastRequest.params);console.log(client.lastRequest.headers);console.log(client.lastRequest.data);// Access details about the last responseconsole.log(client.httpClient.lastResponse.statusCode);console.log(client.httpClient.lastResponse.body);});

If the Twilio API returns a 400 or a 500 level HTTP response,twilio-node will throw an error including relevant information, which you can thencatch:

client.messages.create({body:'Hello from Node',to:'+12345678901',from:'+12345678901',}).then((message)=>console.log(message)).catch((error)=>{// You can implement your fallback code hereconsole.log(error);});

or withasync/await:

try{constmessage=awaitclient.messages.create({body:'Hello from Node',to:'+12345678901',from:'+12345678901',});console.log(message);}catch(error){// You can implement your fallback code hereconsole.error(error);}

If you are using callbacks, error information will be included in theerror parameter of the callback.

400-level errors arenormal during API operation ("Invalid number", "Cannot deliver SMS to that number", for example) and should be handled appropriately.

twilio-node now supports Public Key Client Validation authentication for Twilio APIs. To use this feature, refer to theexample file.Additional documentation can be found onPublic Key Client Validation Quickstart.

To use a custom HTTP client with this helper library, please see theadvanced example of how to do so.

Seeexample for a code sample for incoming Twilio request validation.

TheDockerfile present in this repository and its respectivetwilio/twilio-node Docker image are currently used by Twilio for testing purposes only.

If you need help installing or using the library, please check theTwilio Support Help Center first, andfile a support ticket 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!

Bug fixes, docs, and library improvements are always welcome. Please refer to ourContributing Guide for detailed information on how you can contribute.

⚠️ Please be aware that a large share of the files are auto-generated by our backend tool. You are welcome to suggest changes and submit PRs illustrating the changes. However, we'll have to make the changes in the underlying tool. You can find more info about this in theContributing Guide.

If you're not familiar with the GitHub pull request/contribution process,this is a nice tutorial.

If you want to familiarize yourself with the project, you can start byforking the repository andcloning it in your local development environment. The project requiresNode.js to be installed on your machine.

After cloning the repository, install the dependencies by running the following command in the directory of your cloned repository:

npm install

You can run the existing tests to see if everything is okay by executing:

npmtest

To run just one specific test file instead of the whole suite, provide a JavaScript regular expression that will match your spec file's name, like:

npm run test:javascript -- -m .\*client.\*