Logo icon Name



Relay Calling Example

async function main(numberToCall) {
  const call = await client.calling.newCall({ type: 'phone', from: '+18991112222', to: numberToCall })

  // Attach listeners for the events that you want..
  call.on('created', call => {
    console.log(`The call has been created.`)
  .on('answered', call => {
    console.log(`The call has been answered.`)
  .on('ended', call => {
    console.log(`The call has ended.`)

  await call.begin() // Start the call!

Welcome to SignalWire's Relay documentation and guides. 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 Representational State Transfer (REST) APIs that rely on one-way, HTTP callbacks. This can add latency and limit interactivity. SignalWire's Relay APIs use WebSocket technology, which allow for simultaneous, bi-directional data transmission. This way, you can deploy reliable, low latency, real-time communications.

In addition, 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 also allows for easy integration with Artificial Intelligence (AI) tools and has an intelligent exchange of data, which is controlled by your applications. This means that you can avoid losing data at every transfer.

In addition, Relay enables communications tools to perform in the most popular and widely used environments, like web browsers and mobile applications.


  1. To get started with Relay, you will need your Project ID and an Auth Token. You can find these on your SignalWire Dashboard under API. If you haven't signed up for a SignalWire Space, what are you waiting for! Sign Up for SignalWire

  2. Connect to Relay using one of the supported Relay Clients available. For more information on the supported languages instructions, see the Client & Libraries section.

  3. That's it! Try running some of our code examples such as Make a Call or Listen for Inbound Calls. We're excited to see what you build!

Data Formats

Dates and Times

All dates and times in requests to and from the SignalWire Relay API are UTC, and presented in ISO 8601 format.

For example, the date and time of 8:01 AM CDT on July 23rd, 2018 is presented as: 2018-07-23T13:01:00Z

Phone Numbers

All phone numbers in requests to or from the SignalWire Relay API are in E.164 format, an unambiguous general format for specifying international phone numbers. Numbers in this format start with a plus sign ("+") and the country code.

For example, a US-based phone number like (555) 123-4567 would be formatted like: +15551234567.

If a number cannot be represented in E.164 format, then SignalWire uses the raw Caller ID string that was received.



SignalWire uses the conventional HTTP response codes to indicate whether the request was successful.

In general:

  • codes in the 2xx range mean the request was successful
  • codes in the 4xx range mean an error occurred with your request and will contain an error message explaining what was wrong with the request
  • codes in the 5xx range indicates an error with SignalWire's servers (a rare occurrence!).

Relay Protocol

Aside from the conventional HTTP response codes, SignalWire has additional protocol errors at the Relay level.

  • 200: The request has succeeded (or started)
  • 400: The request is invalid
  • 402: The account lacks funds required to execute this request
  • 403: The request is not allowed
  • 404: The call (or resource) does not exist
  • 409: The request cannot be executed either because of a conflict or because another client has taken control of the resource.
  • 410: The call (or resource) did exist but is now gone
  • 500: The request failed due to a system problem