Docs WebSocket

The WebSocket

Signing in, what a client sends and is told, and staying in step.

Documentation

wss://<host>/api/v1/ws. Every frame is a JSON object with a type.

Signing in

Any of:

  • a first frame {"type":"auth","token":"…"} (for an identity provider's token add "app":"<app key>") — the way for a browser, since an address ends up in logs;
  • the Authorization header of the handshake (and X-Bonga-App or X-Bonga-User) — for a client that can set one;
  • ?token=… in the address (and &app=), for a user's token: an API key there is refused and the connection closed (4401), since every proxy on the way writes the address into its log. Revoke a key that went there.

The server answers {"type":"connected","data":{"user":{…},"sessionId":"…","serverTime":"…","heartbeatSeconds":25,"expiresAt":"…"}}. A connection that has not signed in within 10 seconds is closed. Shortly before a token runs out the server sends {"type":"auth.expiring","data":{"expiresAt":"…"}}; send an auth frame with a new token for the same user and the connection stays.

What a client sends

A frame may carry a ref of the client's choosing; the answer to it carries the same one. A ref is a number or a text of up to 64 characters: a frame with any other is answered with an error and not carried out. A client sends up to 1,000 frames in ten seconds, pings of the WebSocket protocol included, which the server answers.

Frame Answer
{"type":"message.send","ref":"1","conversationId":"…","text":"…","clientId":"…"} — and every other field of POST …/messages {"type":"ack","ref":"1","data":{"message":{…}}}
{"type":"read","conversationId":"…","seq":42} ack with lastReadSeq, lastDeliveredSeq, unreadCount
{"type":"delivered","conversationId":"…","seq":42} the same
{"type":"typing.start","conversationId":"…"}, typing.stop none. Passed on at most every two seconds.
{"type":"presence.subscribe","userIds":["bob"]} {"type":"presence.state","data":{"users":[{"userId":"bob","online":false,"lastSeenAt":"…"}]}}, then presence.changed as they come and go. Up to 500 users; those the caller may not know of are left out, and so are those with whom a block stands either way, who also stop being followed when it is made.
{"type":"presence.unsubscribe","userIds":["bob"]} ack
{"type":"ping"} {"type":"pong"}

What cannot be done is answered {"type":"error","ref":"1","error":{"status":403,"type":"forbidden","detail":"…"}} with the same statuses and types as the REST API, and the connection stays open.

What a client is told

{"type":"message.created","id":"…","createdAt":"…","data":{…}}, to every connection of every user it concerns, whichever node they are connected to:

Event data To
message.created, message.updated, message.deleted message members, the sender's other devices included; updated and deleted only those who can see the message
reaction.added, reaction.removed conversationId, messageId, seq, emoji, userId, reactions (as they now stand) members who can see the message
conversation.created, conversation.updated conversation (a new one with its members, when they are few) members
conversation.deleted conversationId, externalId members
member.added conversationId, actorId, members members, the new ones included: finding yourself there means a conversation you do not know yet
member.removed conversationId, userId, actorId, reason (left, removed) members, and whoever was removed
member.updated conversationId, member members
conversation.read conversationId, userId, lastReadSeq, readAt members (in a group of over 100, the reader's own devices only)
conversation.delivered conversationId, userId, lastDeliveredSeq members (not in a group of over 100)
conversation.settings, conversation.cleared the user's own settings; visibleFromSeq the user's own devices
typing.started, typing.stopped conversationId, userId the other members
presence.changed userId, online, lastSeenAt connections that subscribed

Nothing in an event depends on who reads it, but for one thing: a message that answers one the reader cannot see (said before they came in with shareHistory: false, or before they cleared the conversation) comes to them without replyTo. A conversation in an event has no me. Events are sent once and kept nowhere.

Staying in step

A WebSocket is for what happens while it is open. After connecting, and again after every reconnect:

  1. GET /conversations for the list with its unread counts;
  2. for the conversation on screen, GET …/messages?after=<the last seq you have> until hasMoreAfter is false.

Reconnect with a growing, randomised pause. The server sends protocol pings every 25 seconds; a client that hears nothing for twice that long should reconnect.

Why a connection is closed

Code Meaning What to do
4401 not signed in, or the credentials ran out: a token expired, the user was signed out everywhere, an API key was revoked or reached its expiresAt, or was put in the address get a new token, reconnect
4403 the user was deactivated or the app suspended stop
4408 no credentials within the time allowed send auth sooner
4409 the user opened more than 10 connections; the oldest goes nothing
4413 the client fell 512 frames behind, or two million characters reconnect and catch up
1008 the client sent more than 1,000 frames in ten seconds send fewer
1001, 1011 the server is going away, or failed reconnect