Everything is under /api/v1. JSON in and out, camelCase, nulls left out, times in ISO-8601 UTC.
Fields a client does not know are to be ignored: more may be added.
Users
| Who | ||
|---|---|---|
POST /tokens |
issue a user token; creates or updates the user | server |
PUT /users/{userId} |
create or update a user (name, avatarUrl, metadata, active); an avatarUrl that is no http or https address is left out |
server |
DELETE /users/{userId} |
deactivate: they can neither connect nor send; what they wrote stays | server |
DELETE /users/{userId}/tokens |
sign out everywhere: every token issued for them until now is refused, and their connections are closed; a token issued afterwards works | server |
GET /users/{userId} |
a user, with online and lastSeenAt; their metadata only for your server and for the user themself |
server; a user for whom they may know of |
GET /users?query=&cursor=&limit= |
search by name or id | server; users where the app keeps a directory |
GET /presence?userIds=a,b |
who of some users is online | anybody, for whom they may know of |
GET /me, GET /me/unread |
the calling user; their unread messages and conversations in all | user |
GET /me/blocks, PUT/DELETE /me/blocks/{userId} |
blocking: neither of the two writes in their direct conversation or sees whether the other is online, and nobody is added to a group by somebody they blocked. Only a user one may know of can be blocked; unblocking answers alike whoever is named | user |
"User" means a user token, or an API key with X-Bonga-User.
Conversations
POST /conversations |
{"type":"DIRECT","memberIds":["bob"]} is the one conversation of two users: 201 when made, 200 when it was there. {"type":"GROUP","title":…,"memberIds":[…]} makes a new group, whose creator owns it. |
PUT /conversations/external/{externalId} |
server: make sure of a group under an id of your own, and of its members |
GET /conversations?cursor=&limit=&archived= |
a user's list: pinned first, then by latest activity, each with me (role, unreadCount, lastReadSeq, muted, pinned), peer (the other person of a direct conversation) and lastMessage. A server gets all conversations of the app, newest first. |
GET /conversations/{id}, GET /conversations/external/{externalId} |
one conversation |
PATCH /conversations/{id} |
title, description, avatarUrl (an http or https address), metadata, joinPolicy (INVITE, OPEN), postPolicy (MEMBERS, ADMINS), closed |
DELETE /conversations/{id} |
with everything in it, for good |
GET /conversations/{id}/members |
each with role, lastReadSeq, lastDeliveredSeq, online |
POST /conversations/{id}/members |
add (userIds; shareHistory: false hides what was said before, quoted in an answer too) |
PATCH /conversations/{id}/members/{userId} |
change a role; OWNER hands the group over |
DELETE /conversations/{id}/members/{userId} |
remove a member |
POST /conversations/{id}/join, /leave |
join a group that is open to join; leave a group |
PUT /conversations/{id}/settings |
for oneself: muted, mutedUntil, pinned, archived |
POST /conversations/{id}/read, /delivered |
mark read, or received, up to seq (the latest when left out) |
POST /conversations/{id}/clear |
empty the conversation for oneself alone |
POST /conversations/{id}/typing |
say that one is typing, for a client without a WebSocket |
Who may do what in a group:
| Owner | Admin | Member | |
|---|---|---|---|
| write, react, read | ✓ | ✓ | ✓ (not where postPolicy is ADMINS) |
| rename, describe, close, set policies, add members | ✓ | ✓ | |
| remove a member | ✓ | plain members | |
| delete anybody's message | ✓ | ✓ | |
| change roles, hand over, delete the group | ✓ |
Your server may do all of it in every conversation of its app. A user who is not in a conversation is
told 404 about it, whether it exists or not. When an owner leaves, the group goes to the admin, or
else the member, of longest standing.
Messages
POST /conversations/{id}/messages |
send: text, attachments (ids of uploaded files), replyTo, mentions, metadata, customType, clientId; a server may add systemEvent |
GET /conversations/{id}/messages?before=&after=&around=&limit= |
a stretch, earliest first, with hasMoreBefore and hasMoreAfter. Nothing given: the latest. |
GET /conversations/{id}/messages/search?query= |
messages whose text contains the phrase, latest first |
GET, PATCH, DELETE /conversations/{id}/messages/{messageId} |
read, edit (text, metadata), delete for everybody |
PUT, DELETE /conversations/{id}/messages/{messageId}/reactions/{emoji} |
react, take back; answers the message's reactions as they now stand. A message takes thirty different emoji, and a thousand reactions in all (or one for every member, where the app's groups may be larger) |
Four things worth knowing:
- A
customTypebeginning withapp.is your server's: only an API key sends a message of such a type, or edits one, even one sent in a user's name. A client can so trust a card of that type to be the app's own, and not a user's imitation of it; other types are anybody's. seqnumbers the messages of a conversation 1, 2, 3 … without gaps. Sort by it. A client that has seen 41 and receives 43 has missed one and fetches?after=41. A member has read every message with aseqno higher than theirlastReadSeq, so "read by" and "unread" are comparisons, and whoever sends a message has read everything up to it.clientIdmakes sending safe to repeat. Give every message an id of the client's own (a UUID); sent again with the same one, by the same sender, the message is stored once and the one already there is answered.- A deleted message keeps its place and its
seq, withdeleted: trueand nothing else: no text, no files, no reactions.
The notes the server writes itself are messages of type: "SYSTEM" with a systemEvent
(MEMBER_ADDED, MEMBER_JOINED, MEMBER_REMOVED, MEMBER_LEFT, CONVERSATION_RENAMED,
CONVERSATION_CLOSED, CONVERSATION_REOPENED) and, in metadata, the actor and the users it is
about. They have no text: each client says it in its own words and language.
Lists
Lists answer { "items": […], "nextCursor": "…", "hasMore": true }; pass nextCursor back as cursor
for the next page. A cursor is opaque. Messages are paged by seq instead, as above.