> This page is for APIs.

> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes.

# Connection lifecycle

> How a browser or mobile Relay connection lives — from connect through token refresh, a graceful server disconnect, and reconnect.

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

1. **Open** the WebSocket to `wss://relay.signalwire.com`.
2. **Authenticate** with `signalwire.connect` as your first message. See [Authentication](/docs/apis/relay/client/authentication).
3. **Exchange** commands and events over the open socket. This is the steady state, and it lasts until either side closes the connection.
4. **Refresh** your token before it expires with `signalwire.reauthenticate`, so a short-lived JWT never drops an active call.
5. **Reconnect** if the socket drops or the service asks you to, restoring your session with the `authorization_state` you 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:

```json
{
  "method": "signalwire.reauthenticate",
  "params": {
    "authentication": {
      "jwt_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...."
    }
  }
}
```

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:

```json
{
  "jsonrpc": "2.0",
  "id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
  "method": "signalwire.disconnect",
  "params": { "restart": false }
}
```

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:

1. **Stop sending new requests** on this connection.
2. **Reply with an empty result** (`{}`) if you like. It's accepted, but the service doesn't wait for it.
3. **Reconnect** once the socket closes, following `restart`:
   * `false`: reconnect and restore your session by passing your saved `protocol` and `authorization_state` to `signalwire.connect`, as described under [Reconnecting](#reconnecting).
   * `true`: reconnect as a fresh connection, without the saved `protocol` and `authorization_state`.

> **Note**
>
> `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](/docs/apis/relay/client/authentication) page has the full reconnect message.

## Next steps

#### [Authentication](/docs/apis/relay/client/authentication)

The connect message, tokens, and the reconnect flow in full.

#### [Events and subscriptions](/docs/apis/relay/client/events)

How Relay pushes call, member, and room events to you.