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
Authorizationheader of the handshake (andX-Bonga-ApporX-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:
GET /conversationsfor the list with its unread counts;- for the conversation on screen,
GET …/messages?after=<the last seq you have>untilhasMoreAfteris 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 |