Products Bonga

Add chat to your app
without building it

Bonga is a chat server your application plugs into. It gives you direct and group conversations, files and live delivery over a REST API and a WebSocket, and your app keeps its own users and its own sign-in.

Read the quick start Authorization: Bearer bga_…

The whole integration, in three places

Your server hands your front end a token, your front end chats with it, and your server is told what happens. This is what each one runs.

  1. Runs on your server

    Your server hands out a token

    When a signed-in user opens a page that chats, your server asks Bonga for a token for them. A user exists the first time you name them: there is nothing to register, and you never store an id of ours.

    Request
    POST /api/v1/tokens
    Authorization: Bearer bga_…
    
    { "userId": "42", "name": "Alice Wanjiku" }
    Answer
    { "token": "eyJ…", "expiresAt": "2026-11-14T09:30:00Z",
      "user": { "id": "42", "name": "Alice Wanjiku", … } }
  2. Runs in your front end

    Your front end chats

    With that token the web page or app calls Bonga directly and listens on one WebSocket. It can reach only the conversations that user is in, by the rules of their role.

    Browser
    const api = (method, path, body) =>
      fetch('https://bonga.foxshard.com/api/v1' + path, {
        method,
        headers: { Authorization: 'Bearer ' + token,
                   'Content-Type': 'application/json' },
        body: body && JSON.stringify(body),
      }).then((r) => r.json());
    
    const chat = await api('POST', '/conversations',
      { type: 'DIRECT', memberIds: ['43'] });
    await api('POST', `/conversations/${chat.id}/messages`,
      { text: 'Habari!' });
    
    const ws = new WebSocket('wss://bonga.foxshard.com/api/v1/ws');
    ws.onopen = () => ws.send(JSON.stringify({ type: 'auth', token }));
    ws.onmessage = (e) => show(JSON.parse(e.data));
  3. Runs on your server

    Your server hears what happens

    Register an endpoint and Bonga posts every event of your app to it, signed and retried. A new message says who it was for and whether each of them was connected: whoever was not is who a push notification is for.

    What arrives at your endpoint
    POST /hooks/bonga
    X-Bonga-Event: message.created
    X-Bonga-Signature: t=1791564312,v1=5257a8…
    
    { "type": "message.created", "app": "duka",
      "data": {
        "message": { "seq": 7, "text": "@carol tukutane kesho", … },
        "recipients": [
          { "userId": "bob",   "online": true  },
          { "userId": "carol", "online": false, "mentioned": true } ] } }

What Bonga takes off your hands

Conversations
Direct and group, with roles, join and post policies, and closing. Give a conversation your own id, such as order-10247, and never store one of ours.
Messages
Numbered without gaps in each conversation and safe to send twice. They can be answered, edited, deleted, reacted to and searched, and they carry your own metadata and types.
Live delivery
New messages, edits, reactions, read and delivery receipts, typing and presence, over one WebSocket.
Unread counts
Unread counts, read receipts and catching up are arithmetic on the message number, not bookkeeping for every message.
Files
Any file, typed by what its bytes are rather than what it claims. Images are measured and given a preview, and links are signed, expire and support ranges.
Webhooks
Signed and retried, with what a push notification needs: who was offline, who muted the conversation, who was mentioned.
Apps kept apart
Every application is an app with its own users, keys, rules and data, invisible to every other app.

How Bonga fits into your application