WebSocket connection

This page covers what the server does with your connection after you authenticate. For what the events contain, see Event reference.

What the server sends

After authentication the server sends two kinds of text frame:

• Event frames. Each is one JSON object. Every event has a type, a streamer object, a timestamp and an isTest flag that is true only for dashboard test samples.
• Empty keepalive frames. Each is a text frame with zero bytes, sent every 30 seconds.

Skip empty frames before you parse. JSON.parse("") throws in JavaScript, and the same happens in most languages.

Events are one-way. The server never reads commands from you.

One connection per streamer

NextQuest keeps one registered connection per streamer. If you open a second authenticated connection, the new one becomes the registered connection and receives all events from then on.

The server does not close the first connection. It stays open but receives nothing. It closes only when:

• you close it,
• it stays silent for 90 seconds (see below), or
• the network drops.

So if you leave an old tool running, it looks connected and receives no events. Close old clients before you start a new one.

Disabling the API or regenerating the key closes only the registered connection.

Events fire for every board you own, not only the public one. Each event carries a board object with the board's id.

No replay and no buffer

The server sends an event only to a connection that is open at that moment. It does not store events and does not resend them. There is also no way to ask for a snapshot of the current board.

If your tool was offline when a viewer voted, it never sees that event. When you reconnect, read your board on the public page or the dashboard to catch up.

The server does not retry a failed send. It logs the failure and drops the event.

Send data to keep the connection alive

The server drops a connection that sends it no data for 90 seconds. The timer counts frames the client sends to the server. Events the server sends to you do not reset it, and the server's own 30-second empty frames do not either.

Protocol-level ping and pong frames do not count. In a local test using the same receive logic, a client that sent only pings or pongs was dropped on schedule. A client that sent a text frame, even an empty one, stayed connected.

What this means for you:

• A client that only listens gets dropped after 90 seconds of silence.
• Send any text frame at least every 30 seconds. A short JSON message such as {"type":"ping"} is fine. The server reads it and ignores it.
• Browsers cannot send protocol pings from JavaScript anyway, so text frames are the way to do it.

When the server drops you for silence, it does not send a close frame. Your client sees an abnormal closure, code 1006 in browsers. Reconnect and authenticate again.

Reconnect

Plan for reconnects. They happen on deploys, network changes and key changes.

1. Wait before retrying. Start at 1 second and double each time, up to 30 seconds.
2. Reset the wait to 1 second after a connection stays up and authenticates.
3. Authenticate with the first frame on every new socket. Nothing carries over.
4. Do not retry after close 1008 with Authentication failed.. The key is wrong, old, or the API is off. Check Dashboard > API first. If the API is off, select Enable API. The same key works again.
5. Do not retry after close 1000 with API key regenerated. That key no longer works. Use the new key from the dashboard.
6. Do not open several sockets at once. Each unauthenticated socket counts toward the limit of 5 per address.

A working client is in Examples.

Message size and order

Event frames are small JSON objects, under a few kilobytes. The server sends one event per frame and never splits an event across frames.

Property order inside an event is not part of the contract. Read fields by name. Events for one connection arrive in the order the server sent them, but two actions at nearly the same moment can arrive in either order.