Docs Integrating

Integrating in three steps

Your server hands your front end a token, the front end talks to Bonga, and your server hears what happens.

Documentation

Step 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:

POST /api/v1/tokens
Authorization: Bearer bga_…

{ "userId": "42", "name": "Alice Wanjiku", "avatarUrl": "https://…/alice.png", "ttlSeconds": 3600 }
{ "token": "eyJ…", "expiresAt": "2026-10-09T18:45:12Z", "user": { "id": "42", "name": "Alice Wanjiku", … } }

The same call keeps the user's name and picture up to date: what is given replaces what is on record, what is left out stays. A user id is whatever yours are (letters, digits and . _ : @ | + = -, up to 128 characters), so a number, a UUID, an e-mail address or auth0|5f7c… all do.

Step 2 — your front end talks to Bonga

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 list = await api('GET', '/conversations');                  // each with unread count and preview
const chat = await api('POST', '/conversations', { type: 'DIRECT', memberIds: ['43'] });
const page = await api('GET', `/conversations/${chat.id}/messages`);   // the latest 50, earliest first

const ws = new WebSocket('wss://bonga.foxshard.com/api/v1/ws');
ws.onopen = () => ws.send(JSON.stringify({ type: 'auth', token }));
ws.onmessage = (e) => {
  const frame = JSON.parse(e.data);
  if (frame.type === 'message.created') show(frame.data.message);
};
ws.send(JSON.stringify({ type: 'message.send', ref: '1', conversationId: chat.id,
                         text: 'Habari!', clientId: crypto.randomUUID() }));

Step 3 — your server hears what happens

Register an endpoint and Bonga posts every event of the app to it (see Webhooks). 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.

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 $API/conversations/external/order-10247 -H "Authorization: Bearer $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 $API/conversations/external:order-10247/messages -H "Authorization: Bearer $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 $API/conversations/external:order-10247 -H "Authorization: Bearer $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.