Docs REST API

The REST API

Users, conversations, messages and lists.

Documentation

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 customType beginning with app. 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.
  • seq numbers 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 a seq no higher than their lastReadSeq, so "read by" and "unread" are comparisons, and whoever sends a message has read everything up to it.
  • clientId makes 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, with deleted: true and 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.