Connection lifecycle
A Relay connection is long-lived: you open one WebSocket, authenticate, and then send commands and receive events over it for as long as it stays up. This page covers that lifecycle — how the connection stays healthy, how to refresh your short-lived token, what happens when the service needs to close it, and how to come back quickly.
The connection at a glance
- Open the WebSocket to
wss://relay.signalwire.com. - Authenticate with
signalwire.connectas your first message. See Authentication. - Exchange commands and events over the open socket. This is the steady state, and it lasts until either side closes the connection.
- Refresh your token before it expires with
signalwire.reauthenticate, so a short-lived JWT never drops an active call. - Reconnect if the socket drops or the service asks you to, restoring your session with the
authorization_stateyou saved.
Keep to one connection and reuse it — every command and every event share it. If you use the Browser SDK, it opens the socket, keeps it alive, refreshes the token, and reconnects for you.
Answering keepalive pings
While the connection is open, the service periodically sends you a signalwire.ping request. Reply with a result that echoes back the timestamp and payload you received; if you don’t answer, the service closes the connection. You can also send signalwire.ping yourself to check that the socket still works. The Browser SDK handles both directions for you.
Refreshing your token
Client credentials are short-lived by design. Before the JWT expires, send signalwire.reauthenticate with a fresh token to extend the session in place — without tearing down the connection or the call:
Your backend issues the new token the same way it issued the first one.
When the service disconnects you
SignalWire sometimes needs to close your connection, most often during a routine redeploy. Rather than dropping you abruptly, it sends a signalwire.disconnect request first:
The socket closes a few seconds later. The service doesn’t wait for a reply, so the close comes on schedule whatever you do. When you receive it:
- Stop sending new requests on this connection.
- Reply with an empty result (
{}) if you like. It’s accepted, but the service doesn’t wait for it. - Reconnect once the socket closes, following
restart:false: reconnect and restore your session by passing your savedprotocolandauthorization_statetosignalwire.connect, as described under Reconnecting.true: reconnect as a fresh connection, without the savedprotocolandauthorization_state.
signalwire.disconnect is receive-only: the service sends it to you, and you never send it.
Reconnecting
Right after you connect, and periodically after that, you receive a signalwire.authorization.state event carrying an authorization_state value. Save the latest one.
If the connection drops — whether the socket failed or the service disconnected you — reconnect by sending signalwire.connect again with a valid token, plus that saved authorization_state and the protocol you were given. This restores your permissions and state on the new connection without re-running your full setup.
A saved authorization_state can restore your session for up to 7 days after you received it. When it can’t be used, because it’s too old or the token behind it has expired, the service authenticates you with the jwt_token in the same message instead, so always send a valid one. The Authentication page has the full reconnect message.