Contact Sales

All fields are required

Getting Started with Relay | SignalWire

Getting Started with Relay

User Guide

Solutions Architect

Luca Pradovera

Relay is the next generation of interactive communication APIs available at SignalWire. It is a new, real-time web service protocol that provides for persistent, asynchronous connections to the SignalWire network.

Most providers use REST APIs that rely on one-way communication. This adds latency and limits interactivity of real-time events. SignalWire's Relay APIs use WebSocket technology, which allow for simultaneous, bi-directional data transmission. Using Relay, you can deploy reliable, low latency, real-time communications.

Relay allows for interactive and advanced command and control. Complete control will enable easy transfers and injections across all endpoints, making it easier and quicker to build applications. Relay integrates easily with your products and infrastructure, enabling simple but powerful applications using Artificial Intelligence (AI) tools, data exchange, serverless technologies and more.

Finally, Relay enables communications tools to perform in the most popular and widely used environments, like web browsers, mobile devices, in the cloud, or within your own infrastructure.

How do I get started?

The Relay documentation page has links to the SDK for all languages we support: C#, Node.JS, Ruby, PHP, Python, and Go.

You can install the SDK of your choice, or get started using our ready to go Docker images.

We will be basing the tutorial on the code contained in the latter repo.

What do I need?

If you would like to test this example out, the first thing to do is getting your SignalWire API keys.

Signing up

You can create a SignalWire account and space here.

Your account will start in trial mode, which you can exit by making a manual top up of $5.00. You can find more information on the Trial Mode resource page.

If you are looking for more information about using SignalWire, refer to our Getting Started guide.

Getting your credentials

Head to API in your dashboard and create a new token. Take note of the Project ID and token and keep it on hand for later.

Get a phone number

You will also need to set up a phone number to handle a call with Relay. Purchase a DID from the SignalWire dashboard, select "Relay" as the handler, and input office as the context.

Relay Consumer

The starting point for all Relay application is a Consumer. This class encapsulates the main connection and call handling features of Relay, and makes it very easy to add real time communications to your application.

In this article, we will be setting up our code for receiving a phone call.

Here is an example Consumer in various languages:

Anatomy of a Consumer 

Looking at the Node.JS example in particular, we can see a few moving parts:

Running the consumer

To run the consumer using Docker, execute:

 docker run -e SIGNALWIRE_PROJECT_KEY=<YOUR PROJECT> -e SIGNALWIRE_TOKEN=<YOUR TOKEN> -e ENABLE_DEBUG=true -v "/path/to/your/consumer.js:/app/consumer.js" signalwire/relay-example-node

You can find the complete Docker example here.

Deploying Relay

Relay runs in its own process, not within an HTTP server, and requires no open ports, just an outbound connection to the SignalWire servers. This allows a Consumer to be very efficient, with a small footprint. The process can communicate with the other parts of your application using mechanisms such as REST, a processing queue, or using Relay Tasks, which we will touch on in Part 2.

Make a phone call!

Call the SignalWire number you purchased above, and hear the welcome!

Remember, if you are in Trial Mode you will need to call in from a verified phone number, or add $5 in credit to your account.


Relay offers a huge amount of features, including speech recognition, text-to-speech, answering machine detection, media manipulation and much more.

This was a first introduction, but stay tuned for Part 2, where we will cover inter-process communication with Relay Tasks, outbound dialing, and messaging.

Refer to the Relay Documentation, and make sure you go through Getting Started with SignalWire if you are new to the platform.

Our Relay Dialer Demo and Live Sentiment Analyis Demo provide a look at more complex Relay apps.

Please feel free to reach out to us on our Community Slack or create a Support ticket if you need guidance!