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 to notice when the connection has stopped working, how to rotate credentials in place, and how to come back quickly after a drop.
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.
- Reconnect if the socket drops, 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 an SDK, it opens the socket, keeps it alive, and reconnects for you.
Detecting a dropped connection
On a connection opened with protocol version 2.0.0, SignalWire doesn’t send you keepalive pings or a warning before it closes the socket. When the service restarts, during a routine redeploy for example, your socket simply closes.
Watch for two signals instead:
- The socket closes. Reconnect right away.
- Your own pings go unanswered. Send
signalwire.pingperiodically; the service replies with thetimestampandpayloadyou sent. A ping with no reply means the socket has stopped working even though it hasn’t closed, so close it and reconnect.
The Server SDKs send these pings and reconnect for you.
Rotating your API token
To switch a live connection to a new API token without reconnecting, send signalwire.reauthenticate with your Project ID and the new token:
The project must be the one the connection already authenticated with. On success you get back your refreshed authorization, and a new signalwire.authorization.state event follows; save its authorization_state as usual. If project is missing or doesn’t match, you get a JSON-RPC error and the connection stays open. If the token itself is rejected, you get a JSON-RPC error and the service then closes the socket, as it does for a failed signalwire.connect; reconnect with valid credentials.
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, reconnect by sending signalwire.connect again with your credentials, 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 credentials behind it are no longer valid, the service authenticates you with the credentials in the same message instead. That’s why the reconnect message always carries them. The Authentication page has the full reconnect message.