# Bonga Chat API: Add chat to your web and mobile apps, with the users and ids you already have

*Web page: https://foxshard.com/solutions/bonga. Updated 2026-11-17*

*Chat API, by FoxShard*

Bonga, Swahili for "to chat", is one chat server that any number of applications plug into. Each keeps its own users, ids and sign-in. Your front end talks to Bonga over REST and a WebSocket, and your server hears what happens through signed webhooks.

- REST API and WebSocket
- Signed, retried webhooks
- Uses your own user ids
- Many apps, kept apart

## Who it is for

- **App developers**: Add direct and group chat, files, receipts and typing to web and mobile apps, without running a chat server of your own.
- **Marketplaces and services**: Give each order, ride or ticket its own conversation under your id, between the people your server puts in it.
- **Teams with their own sign-in**: Keep users where they are: Bonga knows them by your ids and accepts tokens from the OpenID Connect provider they already use.
- **Mobile app teams**: Send a push notification to whoever was offline: each message's webhook says who was connected, who muted and who was mentioned.

## What it does

- **Direct and group conversations**: One direct conversation for each pair of users, and groups with owner, admin and member roles and rules for who may join and post. A closed one can still be read.
- **Conversations under your own ids**: `PUT /conversations/external/order-10247` creates or updates a group for your order and its members. Your server posts notes into it and closes it when done.
- **Messages numbered without gaps**: Each message has a `seq`, so unread counts, read receipts and catching up are simple comparisons. A `clientId` makes sending safe to repeat.
- **Replies, edits and reactions**: Reply, edit, delete for everybody, react, mention and search. A `customType` and `metadata` let your front end draw a message as a card of its own.
- **Live over one WebSocket**: New messages, edits, reactions, read and delivery receipts, typing and presence arrive on one connection, whether Bonga runs on one server or many.
- **Files checked by their bytes**: Any file up to the app's limit, ten to a message, typed by its content and not its name. Images get a 320-pixel preview, and links are signed and expire.
- **Signed webhooks for push**: Bonga posts the app's events to your server, signed with HMAC-SHA256 and tried up to eight times. `message.created` lists who was offline, muted or mentioned.
- **Many apps, one server**: Each app has its own users, API keys, rules and data, hidden from the others. A key you revoke stops working at once, and its open connections are closed.

## How it works

1. **Get an app and an API key**: Your app is signed up in the dashboard or by FoxShard. Its first API key is shown once, and Bonga keeps only its hash.
2. **Your server issues a token**: When a signed-in user opens a page that chats, your server asks Bonga for a user token and hands it to the front end.
3. **Your front end chats**: The front end lists conversations and sends messages and files over REST, and hears what happens live on a WebSocket.
4. **Your server hears events**: Bonga posts the app's events to your webhook, signed. Whoever was offline when a message arrived gets a push notification from you.

## A request to the API

Your server asks for a token for a signed-in user, who is created or updated on the way. The front end then chats with that token.

```http
POST /api/v1/tokens
Authorization: Bearer bga_…
Content-Type: application/json

{
  "userId": "42",
  "name": "Alice Wanjiku",
  "avatarUrl": "https://…/alice.png",
  "ttlSeconds": 3600
}
```

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

## Questions

### Do our users need Bonga accounts?

No. Bonga knows each user by the id your application already has, such as a number, a UUID or an e-mail address. A user exists the first time your server names them, when it asks for a token or adds them to a conversation.

### How do we send push notifications?

Register a webhook for `message.created`. Each delivery lists the `recipients` with `online`, `muted` and `mentioned`, so whoever was offline is whom to notify. Deliveries are signed, tried up to eight times and may arrive twice: drop an `id` you have seen.

### Can users sign in with the accounts they already have?

Yes. Once your OpenID Connect provider is registered for the app, the front end calls Bonga with that provider's access token and the `X-Bonga-App` header. Bonga checks the signature, issuer, audience and expiry, and creates the user the first time.

### What if a client misses messages while offline?

It catches up over REST. Messages are numbered by `seq` without gaps, so after every reconnect a client fetches `GET /conversations` for unread counts, then `GET …/messages?after=<last seq>` until `hasMoreAfter` is false.

### What are the limits?

A user may send 120 messages and 30 uploads a minute, and upload 1 GB a day; past that the answer is `429` with `Retry-After`. Your server's API key has higher limits for the whole app, such as 6,000 messages a minute. Files are up to 25 MB by default, set per app.

### What does an error look like?

Every error is an RFC 9457 problem with a `type`, `status`, `detail` and `trace_id`. Match on `type`, show `detail`, and quote `trace_id` when you ask about a request: it finds that request in the server's log.

## Talk to us about Bonga Chat API

Use the form at https://foxshard.com/contact?solution=bonga. Email: support@foxshard.com.
