Menu

Expand
Rate this page:

The Twilio Node Helper Library

The twilio-node helper library lets you write Node.js code to make HTTP requests to the Twilio API.

This library is open-source, so if you find a feature missing or a bug, we encourage you to file an issue or contribute back to the twilio-node project.

Server-Side only, not Front-End

This library is intended for back-end applications running on Node.js. If you are building a front-end, client-side application with React, Angular, Vue, Svelte, or plain HTML/CSS/Javascript, then your application client should only use one of the Twilio JavaScript SDKs below.

  • JavaScript SDKs

    Twilio's JavaScript SDKs are used in the browser to create video conversations, make VoIP phone calls, or implement real-time chat. Get started with the SDK you need.

  • Do 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.

    For general HTTP requests to the Twilio API, consider writing a Twilio Function and making an HTTP request to the Function from within your app's client-side code.

    If you want to see how to put this Node.js library together with the Twilio Client Javascript library for voice, check out the Browser Dialer with Node.js and Vue.js. You'll see how to secure your Twilio account credentials from your end-users. The example creates capability tokens with a Node.js endpoint. Not using Vue? That guide also has example code for React, Angular, and Ember, if you prefer any of those frameworks.

    Installation

    The easiest way to install twilio-node is from NPM. You can run the command below from your project directory to install the library:

    npm install twilio
    

    Then in your code:

    const twilio = require('twilio');
    

    Testing your installation

    Try sending yourself an SMS message, like this:

    const accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'; // Your Account SID from www.twilio.com/console
    const authToken = 'your_auth_token'; // Your Auth Token from www.twilio.com/console
    
    const twilio = require('twilio');
    const client = new twilio(accountSid, authToken);
    
    client.messages
      .create({
        body: 'Hello from Node',
        to: '+12345678901', // Text this number
        from: '+12345678901', // From a valid Twilio number
      })
      .then((message) => console.log(message.sid));
    

    It'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 out How to Set Environment Variables for more information.

    Using This Library

    Authenticate Client

    const accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
    const authToken = 'your_auth_token';
    const client = require('twilio')(accountSid, authToken);
    

    Create A New Record

    const accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
    const authToken = 'your_auth_token';
    const client = require('twilio')(accountSid, authToken);
    
    client.calls
      .create({
        url: 'http://demo.twilio.com/docs/voice.xml',
        to: '+14155551212',
        from: '+15017250604',
      })
      .then(call => console.log(call.sid));
    

    Get Existing Record

    const accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
    const authToken = 'your_auth_token';
    const client = require('twilio')(accountSid, authToken);
    
    client
      .calls('CA42ed11f93dc08b952027ffbc406d0868')
      .fetch()
      .then(call => console.log(call.to));
    

    Iterate Through Records

    const accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
    const authToken = 'your_auth_token';
    const client = require('twilio')(accountSid, authToken);
    
    client.calls.each(call => console.log(call.direction));
    

    The library automatically handles paging for you. Collections, such as calls and messages, have list and each methods that page under the hood. With both list and each, 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, whereas each streams records and lazily retrieves pages of records as you iterate over the collection. You can also page manually using the page method.

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

    Handling Exceptions

    If the Twilio API returns a 400 or a 500 level HTTP response, the twilio-node library will include information in the error parameter of the callback. 400-level errors are normal during API operation ("Invalid number", "Cannot deliver SMS to that number", for example) and should be handled appropriately.

    More Documentation

    Once you're up and running with the Node helper library, you'll find code samples using the latest version in our REST API docs and in the documentation for every Twilio product. You can also find auto-generated library docs for the latest SDK here.

    Accessing the 2.x Version of the SDK

    The most recent version of the Node SDK is not API compatible with the previous 2.x version of the Node SDK you may have used in previous Twilio applications. The older version will continue to work, and you will continue to find sample code for this version throughout our documentation. Should you need to install this version from NPM, you can do so with the following command.

    npm install twilio@2.1.1
    

    Alternately, you can view this version of the SDK on GitHub and download it directly from there.

    Rate this page:

    Need some help?

    We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Community Forums or browsing the Twilio tag on Stack Overflow.

    Thank you for your feedback!

    We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

    Sending your feedback...
    🎉 Thank you for your feedback!
    Something went wrong. Please try again.

    Thanks for your feedback!

    Refer us and get $10 in 3 simple steps!

    Step 1

    Get link

    Get a free personal referral link here

    Step 2

    Give $10

    Your user signs up and upgrade using link

    Step 3

    Get $10

    1,250 free SMSes
    OR 1,000 free voice mins
    OR 12,000 chats
    OR more