Add chat to your app with one API.

How Bonga fits into your application

Bonga is a chat server that any number of applications plug into. Your application keeps its own users, its own ids and its own way of signing people in. Bonga gives it conversations, messages and files over a REST API and a WebSocket, and tells your server what happens through webhooks.

At a glance

Base URL

https://bonga.kweepa.com/api/v1

WebSocket

wss://bonga.kweepa.com/api/v1/ws

Authentication

Authorization: Bearer bga_… for your server, a user token for your front end.

Format

JSON in and out, camelCase, nulls left out, times in ISO-8601 UTC.

Webhooks

Signed with HMAC-SHA256, tried again for up to 8 attempts.

Errors

RFC 9457 problem details.

The words the guide uses

App

One application that uses Bonga. Everything belongs to exactly one app, and is invisible to every other.

User

Known to Bonga by the id your application already has for them. You never store an id of Bonga's. Users are not registered: the first time your server mentions one, by asking for a token or adding them to a conversation, they exist.

API key

bga_…, for your server. It may do everything within the app. With the header X-Bonga-User: <user id> it acts as that user.

User token

For your front end, fetched by your server for one user. It may do what that user may: only the conversations they are in, by the rules of their role.

Webhook

How Bonga tells your server what happens, which is how you send push notifications to people who are not connected.

Get an app and an API key

1. Ask Kweepa for an app

   Tell us what your application is called and a short key for it, such as duka. We make the app and send you its first API key. The key is shown once, and only its hash is kept, so keep it where it was put.

   To rotate a key

   Ask for a second key, deploy it, then have the first revoked. A key that is revoked, or reaches its expiresAt, stops working at once on every node, and the WebSocket connections opened with it are closed with 4401 within seconds.

2. Keep the key on your server

   Environment

   BONGA_API_URL=https://bonga.kweepa.com/api/v1
   BONGA_API_KEY=bga_...
   

   Every request carries Authorization: Bearer <credential>. Whatever goes wrong at the door, the caller learns no more than that it was not let in (401).

3. Settle your app's rules

   An app's rules are set when it is made, and Kweepa changes them with you. With both of the first two switched off, only your server starts conversations: right for an application where who may talk to whom is its own business, such as a customer and their rider, or a buyer and a seller.

   Rules of an app

   Rule	Default	Meaning
   allowClientDirect	true	Users may start a direct conversation with any user of the app.
   allowClientGroups	true	Users may create groups.
   allowUserDirectory	false	Users may search and look up all users of the app, not only those they share a conversation with.
   maxGroupMembers	500	The most members of a group.
   maxMessageLength	10000	Characters in a message.
   maxFileBytes	26214400	25 MB. 0 switches uploads off.
   editWindowSeconds	none	How long a sender may edit a message.
   status	ACTIVE	SUSPENDED turns the whole app away at once: keys, tokens and open connections.

A first conversation, from a terminal

Two users, a conversation and a message, with nothing but your API key. Alice and Bob exist the moment your server names them.

BONGA_API_URL=https://bonga.kweepa.com/api/v1

# Your server: a token for alice (who is created by being named), and one for bob
ALICE_TOKEN=$(curl -s -X POST $BONGA_API_URL/tokens -H "Authorization: Bearer $BONGA_API_KEY" \
        -H 'Content-Type: application/json' \
        -d '{"userId":"alice","name":"Alice"}' | jq -r .token)
curl -s -X POST $BONGA_API_URL/tokens -H "Authorization: Bearer $BONGA_API_KEY" \
     -H 'Content-Type: application/json' \
     -d '{"userId":"bob","name":"Bob"}' > /dev/null

# Alice's front end: the conversation with bob (asked for again, it is the same one), and a message
CONVERSATION_ID=$(curl -s -X POST $BONGA_API_URL/conversations -H "Authorization: Bearer $ALICE_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{"type":"DIRECT","memberIds":["bob"]}' | jq -r .id)
curl -s -X POST $BONGA_API_URL/conversations/$CONVERSATION_ID/messages -H "Authorization: Bearer $ALICE_TOKEN" \
     -H 'Content-Type: application/json' -d '{"text":"Habari Bob!"}'

# Your server, acting as bob: his list, with the unread count and a preview
curl -s $BONGA_API_URL/conversations -H "Authorization: Bearer $BONGA_API_KEY" -H 'X-Bonga-User: bob'

Integrate in three steps

1. Your server hands your front end a token

   When a signed-in user opens a page that chats, your server asks for a token and passes it on.

   Request

   POST /api/v1/tokens
   Authorization: Bearer bga_…
   
   { "userId": "42", "name": "Alice Wanjiku", "avatarUrl": "https://…/alice.png",
     "ttlSeconds": 3600 }
   

   Answer

   { "token": "eyJ…", "expiresAt": "2026-10-09T18:45:12Z",
     "user": { "id": "42", "name": "Alice Wanjiku", … } }
   

   • A user id is whatever yours are: letters, digits and . _ : @ | + = -, up to 128 characters. A number, a UUID, an email address or auth0|5f7c… all do.
   • The same call keeps the user's name and picture up to date: what is given replaces what is on record, and what is left out stays.
   • A token lasts 24 hours unless ttlSeconds asks otherwise, and 7 days at the most.

2. Your front end talks to Bonga

   The front end calls the REST API with the token, and opens a WebSocket for what happens while the page is open.

   JavaScript

   const callBonga = (method, path, body) => fetch('https://bonga.kweepa.com/api/v1' + path, {
     method, headers: { Authorization: 'Bearer ' + token, 'Content-Type': 'application/json' },
     body: body && JSON.stringify(body),
   }).then((response) => response.json());
   
   const conversations = await callBonga('GET', '/conversations');   // each with unread count and preview
   const conversation = await callBonga('POST', '/conversations', { type: 'DIRECT', memberIds: ['43'] });
   const messages = await callBonga('GET', `/conversations/${conversation.id}/messages`);   // the latest 50, earliest first
   
   const webSocket = new WebSocket('wss://bonga.kweepa.com/api/v1/ws');
   webSocket.onopen = () => webSocket.send(JSON.stringify({ type: 'auth', token }));
   webSocket.onmessage = (event) => {
     const frame = JSON.parse(event.data);
     if (frame.type === 'message.created') show(frame.data.message);
   };
   webSocket.send(JSON.stringify({ type: 'message.send', ref: '1', conversationId: conversation.id,
                                   text: 'Habari!', clientId: crypto.randomUUID() }));
   

3. Your server hears what happens

   Register an endpoint and Bonga posts every event of the app to it. The one most applications want is message.created, which says who the message was for and whether each of them was connected: whoever was not is whom to send a push notification. See webhooks.

Conversations your application owns

Often a conversation belongs to something of yours: an order, a ride, a ticket. Give it that thing's id and never keep one of Bonga's.

# Makes sure of the conversation of order 10247, and of who is in it. Call it as often as you like.
curl -s -X PUT $BONGA_API_URL/conversations/external/order-10247 -H "Authorization: Bearer $BONGA_API_KEY" \
     -H 'Content-Type: application/json' -d '{
       "title": "Order 10247",
       "metadata": { "orderId": 10247 },
       "members": [ { "id": "cust-9", "name": "Achieng" }, { "id": "rider-7", "name": "Juma" } ] }'

# A note about the conversation, from the application itself
curl -s -X POST $BONGA_API_URL/conversations/external:order-10247/messages -H "Authorization: Bearer $BONGA_API_KEY" \
     -H 'Content-Type: application/json' \
     -d '{"text":"Your rider has arrived","systemEvent":"RIDER_ARRIVED","metadata":{"riderId":"rider-7"}}'

# When the order is done: nobody but your server writes in it any more; it can still be read
curl -s -X PATCH $BONGA_API_URL/conversations/external:order-10247 -H "Authorization: Bearer $BONGA_API_KEY" \
     -H 'Content-Type: application/json' -d '{"closed":true}'

Wherever the id of a conversation goes, in a path or in a WebSocket frame, external:<your id> goes as well. What comes back always carries the conversation's own id and its externalId. A message may also carry a customType (say order_card) and metadata for your front end to render in its own way. Such a message needs no text.

Credentials and sign-in

Every request carries Authorization: Bearer <credential>. There are five kinds, and three of them are your application's.

Users who already sign in somewhere

If your users have access tokens of an OpenID Connect provider, such as your own sign-in or Kweepa Identity, Kweepa registers it for your app and no token of Bonga's is needed. This is what is registered:

{ "issuerUri": "https://id.example.com", "audience": "duka-chat" }

The front end then calls with Authorization: Bearer <access token> and X-Bonga-App: duka.

• The token is checked for its signature (against the provider's published keys, asymmetric algorithms only), its issuer, its audience and its times.
• The audience is required: a provider issues tokens to other applications too, which are not to sign anybody in here.
• The user is created on first sight from the claims sub, name and picture. userIdClaim, nameClaim and avatarClaim name others, and jwkSetUri says where the keys are when the provider has no discovery document.
• The provider's keys are fetched again when a token names one that is not known, at most every 30 seconds, whatever tokens come in.

The REST API

Everything is under /api/v1. Fields a client does not know are to be ignored: more may be added. "A user" below means a user token, or an API key with X-Bonga-User.

Users

Conversations

Who may do what in a 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

Four things worth knowing

seq

Numbers the messages of a conversation 1, 2, 3 and so on, 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.

clientId

Makes sending safe to repeat. Give every message an id of the client's own, such as a UUID. Sent again with the same one by the same sender, the message is stored once and the one already there is answered.

customType

One that begins 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 trust a card of that type to be the app's own. Other types are anybody's.

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 answer { "items": […], "nextCursor": "…", "hasMore": true }. Pass nextCursor back as cursor for the next page. A cursor is opaque. Messages are paged by seq instead.

Live delivery over the WebSocket

wss://bonga.kweepa.com/api/v1/ws. Every frame is a JSON object with a type.

Signing in

• A first frame {"type":"auth","token":"…"}, with "app":"<app key>" added for an identity provider's token. This is the way for a browser, since an address ends up in logs.
• The Authorization header of the handshake, with X-Bonga-App or X-Bonga-User, for a client that can set one.
• ?token=… in the address, with &app=, for a user's token only. 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.

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.

Events are sent once and kept nowhere. A conversation in an event has no me. 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.

Staying in step

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

1. Fetch the list

   GET /conversations, for the list with its unread counts.

2. Catch up on 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

Webhooks

Register an endpoint and Bonga posts the events of your app to it.

curl -s -X POST $BONGA_API_URL/webhooks -H "Authorization: Bearer $BONGA_API_KEY" -H 'Content-Type: application/json' \
     -d '{"url":"https://api.example.com/hooks/bonga","eventTypes":["message.created"]}'

• The answer holds the endpoint's secret (whsec_…), shown then and when you ask for a new one (PATCH /webhooks/{webhookId} with {"rotateSecret":true}).
• Leave eventTypes out for every event. An app has up to 10 endpoints.
• GET /webhooks/{webhookId}/deliveries shows how the latest deliveries went. POST /webhooks/{webhookId}/test sends a webhook.test event, five at once and ten a minute.
• Endpoints are https and public. Redirects are not followed.

What a delivery looks like

POST /hooks/bonga
Content-Type: application/json
X-Bonga-Event: message.created
X-Bonga-Event-Id: 261009174512A1B2C3D4E5F6
X-Bonga-Delivery: 261009174512F6E5D4C3B2A1
X-Bonga-Signature: t=1791564312,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

{ "id": "261009174512A1B2C3D4E5F6", "type": "message.created", "app": "duka",
  "createdAt": "2026-10-09T17:45:12.345Z", "data": { … } }

data is what a client gets for the same event, in the table above. The events for clients alone, which are receipts, typing, presence and a user's own settings, are not sent. message.created carries more:

{ "message": { "id": "…", "seq": 7, "text": "@carol tukutane kesho", "sender": { "id": "alice", … }, … },
  "conversation": { "id": "…", "type": "GROUP", "title": "Chama", "externalId": null, … },
  "recipients": [
    { "userId": "bob",   "online": true,  "muted": false, "mentioned": false },
    { "userId": "carol", "online": false, "muted": true,  "mentioned": true } ] }

recipients is everybody in the conversation but the sender. Somebody with online: false had no connection when the message was sent: that is whom a push notification is for.

Check the signature

v1 is the HMAC-SHA256, in hex, of t, a dot, and the body exactly as it arrived, under the endpoint's secret. Work it out over the raw bytes, before any JSON parsing, and turn away what is more than a few minutes old.

// Express: app.post('/hooks/bonga', express.raw({ type: 'application/json' }), handler)
const crypto = require('crypto');

function verify(rawBody, header, secret) {
  const { t: timestamp, v1: signature } = Object.fromEntries(header.split(',').map((part) => part.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(timestamp + '.').update(rawBody).digest('hex');
  return signature.length === expected.length && crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

static boolean verify(byte[] rawBody, String header, String secret)
        throws GeneralSecurityException {
    String timestamp = header.substring(2, header.indexOf(','));
    String signature = header.substring(header.indexOf("v1=") + 3);
    if (Math.abs(Instant.now().getEpochSecond() - Long.parseLong(timestamp)) > 300)
        return false;
    Mac hmacSha256 = Mac.getInstance("HmacSHA256");
    hmacSha256.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
    hmacSha256.update((timestamp + ".").getBytes(StandardCharsets.UTF_8));
    String expected = HexFormat.of().formatHex(hmacSha256.doFinal(rawBody));
    return MessageDigest.isEqual(expected.getBytes(StandardCharsets.UTF_8),
            signature.getBytes(StandardCharsets.UTF_8));
}

What to count on

• Answer 2xx within 10 seconds. Anything else is tried again with a pause that doubles, from 30 seconds up to an hour, eight attempts in all. Then it is given up and kept for a month to look at (GET /webhooks/{webhookId}/deliveries, whose lastError says what kind of failure it was). A delivery not made within a day is given up however few times it was tried.
• An endpoint that keeps failing is paused. After five failed attempts in a row nothing is posted to it for a minute, twice as long after each failure that follows, half an hour at most, and the first attempt that arrives ends it. GET /webhooks shows pausedUntil meanwhile.
• A delivery may arrive more than once, since your answer can be lost. Every attempt of an event carries the same id: drop what you have seen.
• Deliveries are not ordered. What they report carries its own order: a message its seq.
• An event is queued in the transaction of the change it reports: your server never hears of something that was rolled back and never misses something that was not.

Files

Sending a file takes two steps: upload it, then send a message with its id.

FILE_ID=$(curl -s -X POST $BONGA_API_URL/files -H "Authorization: Bearer $ALICE_TOKEN" -F file=@photo.jpg | jq -r .id)
curl -s -X POST $BONGA_API_URL/conversations/$CONVERSATION_ID/messages -H "Authorization: Bearer $ALICE_TOKEN" \
     -H 'Content-Type: application/json' -d "{\"text\":\"Look\",\"attachments\":[\"$FILE_ID\"]}"

{ "id": "…", "name": "photo.jpg", "contentType": "image/jpeg", "kind": "IMAGE", "size": 482113,
  "width": 3024, "height": 4032,
  "url": "/api/v1/files/…/content?expires=1791568800&signature=…",
  "thumbnailUrl": "/api/v1/files/…/thumbnail?expires=1791568800&signature=…",
  "urlExpiresAt": "2026-10-09T19:00:00Z" }

• Any file is taken, up to the app's maxFileBytes, ten to a message.
• What a file is, is read from its bytes, not from its name or the type the upload claimed. kind is IMAGE, VIDEO or AUDIO for what was recognised as something a browser plays, and FILE for everything else. Only the first three are shown in place. The rest, an HTML page or an SVG among them, is a download.
• Images (JPEG, PNG, GIF) are measured and given a JPEG preview of 320 pixels, turned the way the photo was taken. WebP is measured.
• url and thumbnailUrl need no credentials, so they work in an <img> or a <video>. They are signed and good for an hour or a little more. Every time a message is read it comes with fresh ones, and GET /files/{fileId} gives fresh ones for one file. Ranges are served.
• Who may read a file: its uploader, anybody who can read a message it is attached to, and your server. A user can attach only a file they uploaded or can already read, which is what forwarding is.
• A file that no message carries is cleared away a day after it was uploaded.
• A user with a token of their own uploads up to 1 GB in 24 hours. The upload that goes past it is still taken, and the next is answered 429 until enough of the day has gone by. Your server is not held to it.
• 507 means there is no room for files just now, and 503, with Retry-After, that the store cannot be reached. Try again later.

Errors and limits

Every error is an RFC 9457 problem. Match on type, show detail, and quote trace_id when asking why: it finds the request in the server's log, and is your own X-Request-Id when you sent one.

{ "type": "/errors/not-found", "title": "Not Found", "status": 404,
  "detail": "Conversation not found: 261009174512A1B2C3D4E5F6", "trace_id": "9f2c41d07a6b3e58" }

Rate limits

A user with a token

Held per user: 30 messages at once and 120 a minute (sending, editing, reacting), 10 uploads at once and 30 a minute and 1 GB of them in 24 hours, 20 other changes at once and 60 a minute.

Your server with its API key

Held for the whole app, far above a person, acting as a user or not: 600 messages at once and 6,000 a minute, 120 uploads at once and 1,200 a minute, 600 other changes at once and 6,000 a minute (the tokens it asks for included), and five test deliveries of a webhook at once and ten a minute.

Common questions