Skip to contentSkip to navigationSkip to topbar
On this page

Programmable Voice quickstart for Node.js


This quickstart will show you how to build a Node.js application with Twilio's Node.js helper library(link takes you to an external page).

Your application will make an outbound phone call and respond to an inbound phone call. It will use the Twilio REST API to make the outbound call, and TwiML to respond to the inbound call by reading a message using Text to Speech.


Get a phone number

get-a-phone-number page anchor

Sign up here(link takes you to an external page) to get a free Twilio trial account or log in(link takes you to an external page) to an account you already have.

If you don't have a Twilio phone number with voice call functionality then you'll need to buy one by doing the following:

  1. Go to the Buy a Number(link takes you to an external page) page.
  2. Check the Voice box.
  3. Click Search. You'll see a list of available phone numbers.
  4. Find the number you want, and 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(link takes you to an external page).


Install the Twilio Node.js helper library

install-the-twilio-nodejs-helper-library page anchor

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

Make an outgoing phone call with Node.js

make-an-outgoing-phone-call-with-nodejs page anchor

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:

Make an outbound callLink to code sample: Make an outbound call
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.

Replace the placeholder credential values

replace-the-placeholder-credential-values page anchor

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

  1. Log in to the Twilio Console(link takes you to an external page).
  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.
(error)

Danger

This quickstart hardcodes your credentials to get you started quickly. Use environment variables and API keys to keep credentials secret and control access when you deploy to production.

Replace the to and from phone numbers

replace-the-to-and-from-phone-numbers page anchor

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.

(information)

Info

If you're using a Twilio trial account, outgoing phone calls are limited to phone numbers you have verified with Twilio. Phone numbers can be verified via your Twilio Console's Verified Caller IDs(link takes you to an external page). For other trial account restrictions and limitations, check out our guide on how to work with your free Twilio trial account.


Take a phone call with your Twilio number

take-a-phone-call-with-your-twilio-number page anchor

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(link takes you to an external page) 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/(link takes you to an external page). You should see that the server responds with TwiML containing the message that we'd like to read to incoming calls.

Expose your local server to the Internet with ngrok

expose-your-local-server-to-the-internet-with-ngrok page anchor

If you don't already use ngrok then download and install it(link takes you to an external page).

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.

Configure your Twilio webhook

configure-your-twilio-webhook page anchor
  1. Navigate to the Active Numbers(link takes you to an external page) 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:

Let's build something amazing.