Programmable Voice quickstart for Node.js

Log in to your Twilio account or sign up for a new one.

If you need a Twilio phone number, buy one in the Twilio Console:

1. Go to Phone Numbers > Manage > Buy a Number.
2. Under Capabilities, select Voice.
3. Click Search. The page displays a list of available voice-capable phone numbers.
4. Click Buy next to a phone number to add it to your account.

Check if you already have Node.js installed on your computer by opening a command line and running the following command:

node -v

You should see something like:

1
node -v
2
v22.14.0

You'll need Node.js version 14 or later to run this quickstart. If you don't have a matching version of Node.js on your computer then download and install it.

The easiest way to install the library is using npm, the Node.js package manager. Run the following command in a new directory:

npm install twilio

Let's put that Twilio Node.js library to good use. With a single API request, you can make an outbound call from your Twilio phone number.

Open a new file called make_call.js and paste in the following code:

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function createCall() {
11
  const call = await client.calls.create({
12
    from: "+987654321",
13
    to: "+123456789",
14
    url: "http://demo.twilio.com/docs/voice.xml",
15
  });
16

17
  console.log(call.sid);
18
}
19

20
createCall();

This code starts a phone call between the two phone numbers that you pass as arguments. The from number is your Twilio number, and the to number is who you want to call.

The url argument points to a TwiML file that tells Twilio what to do when the call recipient answers their phone. This TwiML instructs Twilio to read a message using text to speech and then play an MP3.

Swap the placeholder values for accountSid and authToken with your personal Twilio credentials.

1. Log in to the Twilio Console.
2. Copy the Account SID and replace process.env.TWILIO_ACCOUNT_SID with it in the make_call.js file.
3. Copy the Auth Token and replace process.env.TWILIO_AUTH_TOKEN with it.

Remember that phone number you bought just a few minutes ago? Go ahead and replace the existing from number with that one, making sure to use E.164 formatting:

[+][country code][phone number including area code]

Next, replace the to phone number with your mobile phone number. As above, you should use E.164 formatting for this value. Save your changes and run the code by running the following command from your terminal:

node make_call.js

Your phone should ring with a call from your Twilio number.

To handle incoming phone calls, we'll need a web application that can accept HTTP requests from Twilio.

On the command line, install the Express framework by running the below command:

npm install express --save

Now, create a file called server.js and use the following code to create a server that can handle incoming messages:

1
const express = require('express');
2
const VoiceResponse = require('twilio').twiml.VoiceResponse;
3

4
const app = express();
5

6
// Create a route that will handle Twilio webhook requests, sent as an
7
// HTTP POST to /voice in our application
8
app.post('/voice', (request, response) => {
9
  // Use the Twilio Node.js SDK to build an XML response
10
    const twiml = new VoiceResponse();
11

12
    twiml.say('Hello from your pals at Twilio! Have fun.');
13

14
  // Render the response as XML in reply to the webhook request
15
  response.type('text/xml');
16
  response.send(twiml.toString());
17
});
18

19
// Create an HTTP server and listen for requests on port 1337
20
app.listen(1337, () => {
21
    console.log('TwiML server running at http://127.0.0.1:1337/');
22
});

Run this server with the following command:

node server.js

Open a web browser and visit http://127.0.0.1:1337. You should see that the server responds with TwiML containing the message that we'd like to read to incoming calls.

If you don't already use ngrok then download and install it.

Start the server again if it's not still running:

node server.js

Then open a new command line window and start ngrok with this command:

ngrok http 1337

You should see output similar to this:

1
Session Status                online                                                                       
2
Version                       3.23.2                                                                       
3
Web Interface                 http://127.0.0.1:4040                                                        
4
Forwarding                    https://ff4660c91380.ngrok.app -> http://localhost:1337                      
5
                                                                                                           
6
Connections                   ttl     opn     rt1     rt5     p50     p90                                  
7
                              0       0       0.00    0.00    0.00    0.00 

Copy the URL ending in ngrok.app and paste it into your browser. You should see your Express application's "Hello from your pals at Twilio!" message.

1. Navigate to the Active Numbers page in the Twilio Console.
2. Click on the phone number you purchased earlier.
3. Visit the Configure tab and find the Voice Configuration section.
4. In the A call comes in row, select the Webhook option. Enter your ngrok public URL in the URL field (for example, https://ff4660c91380.ngrok.app).
5. Click on Save configuration.

Head back to your terminal. Make sure that ngrok is still running in one tab and your Express server is running in another tab.

Make a phone call to your Twilio phone number. Within a few moments, you'll see an HTTP request in your ngrok console, and you'll hear a short message once the call connects.

And there you go - you've successfully made and received a call with Node.js.

Your new application uses the <Say> TwiML verb to read a message to the caller using text to speech. You can create create more powerful constructs and call flows using other TwiML verbs. Try a few, such as <Record>, <Gather>, and <Conference>.

Check out these pages to learn more:

• Dig into the Programmable Voice API reference documentation
• Gather user input via keypad (DTMF tones) in Node.js
• Learn how to record incoming and outgoing Twilio Voice phone calls using Node.js and Express
• Create conference calls with Node.js
• Learn how to modify calls in progress
• Check out our full sample application tutorial on how to transfer calls from one support agent to another using Node.js and Express

Let's build something amazing.