Skip to main content

Making and Receiving Phone Calls

This guide is using Relay V4

This guide is available for Relay V3 and for Relay V4. You are currently viewing the guide for Relay V4. To switch to the older Relay V3 guide, please use the selection field below:

This introductory guide will show you how to make and receive calls from your own Node.js application.

Obtaining and configuring a number

Log in to your SignalWire Space. From the Phone Numbers section, you can buy a new phone number. You will need at least one number to make and receive calls. After you have acquired a number, open its settings by clicking on "Edit Settings". Scroll down until you reach "Voice and Fax Settings", as shown in the next figure, and configure it to:

  • handle incoming calls using a Relay application,
  • forward the call to the "office" Relay context
A screenshot of the Voice and Fax Settings pane. Incoming calls will be accepted as voice calls, and handled with a Relay Application defined as the 'office' Relay context.
Voice configuration setting for handling incoming calls.

What is a context?  

Contexts are used to segregate messages and calls. If you associate a group of phone numbers to context A and a different group of numbers to context B, then from your code you can decide whether to receive events (such as incoming calls or messages) only for the numbers in A, only for the numbers in B, or for both. We are going to use "office" in this guide, but you can pick any name.

Installation of the SDK

First, you need to obtain the Realtime SDK from npm. From your terminal you can run the following command to install it:

npm install --save @signalwire/realtime-api@~3

Then, include the package in JavaScript as follows:

import { Voice } from "@signalwire/realtime-api";

Making your first call

To make a call from Node.js you need to instantiate a Voice client, and then call one of its dialing methods.

import { Voice } from "@signalwire/realtime-api";

const client = new Voice.Client({
project: "your-project-id",
token: "your-api-token",
contexts: ["office"],

try {
const call = await client.dialPhone({
from: "+1xxx", // Must be a number in your SignalWire Space
to: "+1yyy",
timeout: 30,

console.log("The call has been answered!",;
} catch (e) {

We used the "office" context when initializing the Voice client. You use the contexts array in the Client constructor to indicate which group of calls you want to receive. For the moment we are not listening for incoming calls, to the context doesn't have any effect. Still, it will be useful for later, when we are going to listen for incoming calls.

You also need to specify a Project ID and API token: find these in the API section of your space, as shown in the following figure. Make sure that your token has the "Voice" scope enabled.

A screenshot of the API tab, showing the Project ID, Space URL, and API Token.

You can find your Project ID and Token from the API tab in your SignalWire Space. Make sure your token has the "Voice" scope enabled.

Receiving incoming calls

Once a Client is initialized, you can listen for incoming calls on the selected contexts (in our example, just "office"). For example:

client.on("call.received", async (call) => {
console.log("Call received:",, call.from,;

try {
await call.answer();
console.log("Inbound call answered");
} catch (error) {
console.error("Error answering inbound call", error);

Your event handler receives a call object, which you can use to answer the call, to access fields such as call.from and, or to call additional methods (playing audio, prompting for input, transferring the call, etc.)

Next steps

Congratulations! You can now make and receive calls with your Node.js application. You are now ready to explore the advanced guides in the Voice section from the left menu.