twilio

What is twilio?

The Twilio npm package is a Node.js client library that provides tools to interact with the Twilio API for various communication solutions, including SMS, voice calls, video, chat, and more. It allows developers to programmatically send and receive text messages, make and receive phone calls, handle authentication with two-factor authentication, and work with other Twilio services.

What are twilio's main functionalities?

Sending SMS

This feature allows you to send SMS messages to a specified phone number using Twilio's messaging API.

const twilio = require('twilio');
const client = new twilio('ACCOUNT_SID', 'AUTH_TOKEN');
client.messages.create({
  body: 'Hello from Twilio!',
  to: '[phone]',
  from: '[phone]'
}).then(message => console.log(message.sid));

Making Voice Calls

This feature enables you to make outbound voice calls to phones around the world with a specified TwiML URL to control the call flow.

const twilio = require('twilio');
const client = new twilio('ACCOUNT_SID', 'AUTH_TOKEN');
client.calls.create({
  url: 'http://demo.twilio.com/docs/voice.xml',
  to: '[phone]',
  from: '[phone]'
}).then(call => console.log(call.sid));

Handling Two-Factor Authentication

This feature is used for sending verification tokens for two-factor authentication, enhancing security for user accounts.

const twilio = require('twilio');
const client = new twilio('ACCOUNT_SID', 'AUTH_TOKEN');
client.verify.services('SERVICE_SID')
  .verifications
  .create({to: '[phone]', channel: 'sms'})
  .then(verification => console.log(verification.status));

Working with Video

This feature allows you to create video rooms where multiple participants can join for video conferencing.

const twilio = require('twilio');
const client = new twilio('ACCOUNT_SID', 'AUTH_TOKEN');
client.video.rooms.create({
  uniqueName: 'DailyStandup'
}).then(room => console.log(room.sid));

Other packages similar to twilio

nexmo

Nexmo, now known as Vonage API, is a service similar to Twilio that provides APIs for SMS, voice, phone verifications, and other communication services. It offers similar functionality but with different pricing and API design.

plivo

Plivo is another cloud communication platform that enables businesses to integrate voice and SMS capabilities into their applications. It is often compared to Twilio in terms of features and services offered.

bandwidth

Bandwidth offers a range of communication APIs, including voice, messaging, and 911 access. It is a direct competitor to Twilio and provides similar services with a focus on enterprise solutions.

sinch

Sinch provides cloud-based communication services and APIs for SMS, voice, video, and verification. It competes with Twilio by offering a suite of communication tools for developers.

README

twilio-node

Documentation

The documentation for the Twilio API can be found here.

The Node library documentation can be found here.

Versions

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

Supported Node.js Versions

This library supports the following Node.js implementations:

• Node.js 14
• Node.js 16
• Node.js 18

TypeScript is supported for TypeScript version 2.9 and above.

Installation

npm install twilio or yarn add twilio

Sample Usage

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

Environment Variables

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 and TWILIO_AUTH_TOKEN.

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

Client Initialization

If you invoke any V2010 operations without specifying an account SID, twilio-node will automatically use the TWILIO_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:

var accountSid = process.env.TWILIO_ACCOUNT_SID; // Your Account SID from www.twilio.com/console
var authToken = process.env.TWILIO_AUTH_TOKEN;   // Your Auth Token from www.twilio.com/console
var subaccountSid = process.env.TWILIO_ACCOUNT_SUBACCOUNT_SID; // Your Subaccount SID from www.twilio.com/console

const client = require('twilio')(accountSid, authToken);
const mainAccountCalls = client.api.v2010.account.calls.list; // SID not specified, so defaults to accountSid
const subaccountCalls = client.api.v2010.account(subaccountSid).calls.list // SID specified as subaccountSid

Lazy Loading

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 the lazyLoading flag set to false:

var accountSid = process.env.TWILIO_ACCOUNT_SID; // Your Account SID from www.twilio.com/console
var authToken = process.env.TWILIO_AUTH_TOKEN;   // Your Auth Token from www.twilio.com/console

const client = require('twilio')(accountSid, authToken, {
    lazyLoading: false
});

Enable Auto-Retry with Exponential Backoff

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

Optionally, the maximum number of retries performed by this feature can be set with the maxRetries flag. The default maximum number of retries is 3.

var accountSid = process.env.TWILIO_ACCOUNT_SID; // Your Account SID from www.twilio.com/console
var authToken = process.env.TWILIO_AUTH_TOKEN;   // Your Auth Token from www.twilio.com/console

const client = require('twilio')(accountSid, authToken, {
    autoRetry: true,
    maxRetries: 3
});

Specify Region and/or Edge

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

var accountSid = process.env.TWILIO_ACCOUNT_SID; // Your Account SID from www.twilio.com/console
var authToken = process.env.TWILIO_AUTH_TOKEN;   // Your Auth Token from www.twilio.com/console

const client = require('twilio')(accountSid, authToken, {
    region: 'au1',
    edge: 'sydney',
});

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

const client = require('twilio')(accountSid, authToken);
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

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

var accountSid = process.env.TWILIO_ACCOUNT_SID; // Your Account SID from www.twilio.com/console
var authToken = process.env.TWILIO_AUTH_TOKEN;   // Your Auth Token from www.twilio.com/console

const client = require('twilio')(accountSid, authToken, {
  logLevel: 'debug'
});

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

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

Using webhook validation

See example for a code sample for incoming Twilio request validation.

Handling Exceptions

For an example on how to handle exceptions in this helper library, please see the Twilio documentation.

Using a Custom HTTP Client

To use a custom HTTP client with this helper library, please see the Twilio documentation.

Docker Image

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

Getting help

If you need help installing or using the library, please check the Twilio Support Help Center first, and file 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!

Contributing

Bug fixes, docs, and library improvements are always welcome. Please refer to our Contributing 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 the Contributing Guide.

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

Getting Started

If you want to familiarize yourself with the project, you can start by forking the repository and cloning it in your local development environment. The project requires Node.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:

npm test

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.\*