Sign in Talk to us Free trial
Free trial

Design and software studio
Colour

The live board feed

Connect to the WebSocket feed that pushes call changes to boards the moment they happen, and know how it signs in and stays healthy.

For
AdministratorDispatcher
Hosting
Any hosting
Devices
All devices
Business
Towing

Checked against Pop Street Dispatch 0.1.0

The board stays current through a WebSocket at /tow/board/ws. You will be able to connect a board, read its messages and handle a dropped connection.

Before you start #

  • A token for a role with towing access (owner, manager, advisor or dispatcher), with a scope that reaches /tow.
  • A WebSocket client. Browsers send no Authorization header on a WebSocket, so this feed signs in a different way.

Steps #

  1. Open a WebSocket to /api/v1/tow/board/ws and offer the protocol psd.board.v1.
  2. Sign in in one of two ways:
    • Send {"type":"auth","token":"<token>"} as the first message, within 10 seconds.
    • Or offer the extra protocol psd.token.<token> next to psd.board.v1. A token in the address is ignored, because addresses end up in logs.
  3. The server answers {"type":"ready","now":...,"protocol":"psd.board.v1"}.
  4. Read the messages:
    • board: a call changed. It carries event (call.created, call.assigned or call.status), call_id, status, at and the call.
    • resync: the connection fell behind. Reload the board with GET /tow/board.
    • pong: the answer to a {"type":"ping"} message you send.
    • error: a refusal, with a code and a message.
  5. Answer the server's pings. The server pings every 30 seconds and closes a connection that missed the last pong.

Limits and closing #

  • A business account can hold 50 open boards. The 51st gets too_many_connections and the close code 1013.
  • A refusal closes the connection with code 1008: no first message in time, a bad token, a role outside towing or a scope that excludes the board.
  • The server re-checks the token on every ping. A revoked token, a deactivated user or a changed role closes the connection with "session ended".
Technical details
  • Each business account has its own channel, so one account never sees another account's calls.
  • The call in a board message leaves out the timeline and files to stay small.
  • Messages that a slow client misses are replaced by one resync.
  • The route is public at the HTTP layer and checks the token after the upgrade.

If something goes wrong #

  • The connection closes straight after opening: send the auth message within 10 seconds.
  • Close code 1008: check the token, the role and the scope.
  • Close code 1013: close another board for this account.
  • Missing changes after a network drop: reconnect and call GET /tow/board once.