Overview
SignalWire Relay gives your backend one persistent WebSocket connection to SignalWire. Over that single connection you place and control voice calls, send and receive messages, hand work to long-running processes, and react to real-time events the moment they happen.
That’s the key difference from the REST API, where each request is its own HTTP round trip. Relay keeps the connection open, so SignalWire can push events straight to you — a call was answered, a recording finished, a message arrived — without you polling for them. You open the connection once, authenticate, then send commands and receive events over the same socket for as long as it stays open.
This is the Server reference, for backend code that holds your SignalWire credentials. Building a browser or mobile app? See the Client reference for the Call Fabric and WebRTC surface.
How a connection works
Every Relay session follows the same shape:
- Open the WebSocket to
wss://relay.signalwire.com. - Authenticate by sending
signalwire.connectas your very first message. A WebSocket has noAuthorizationheader, so your credentials — a project ID and API token — travel in that first message instead. See Authentication. - Send commands and receive events over the connection — dial a call, send a message, and listen for the events each service emits.
Every response carries a result you check for success or failure. See Errors.
Services
Relay groups its commands and events into services. They all share the one connection you open with signalwire.connect.
Browse the full command-and-event reference for each service in the API reference under this tab.
Use Relay from an SDK
You can speak the Relay WebSocket protocol directly, but most developers use a SignalWire SDK that wraps the connection, authentication, and every command in idiomatic, type-safe methods.
The Server SDKs — the Realtime clients for backend code (Python, Node, and more) — expose the calling, messaging, and tasking services as native objects. See the Realtime reference.
Pick the language that matches your stack, or read on to work with the protocol directly.