Bonga Chat API, Chat API
Add chat to your web and mobile apps, with the users and ids you already have
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
Request
POST /api/v1/tokens
Authorization: Bearer bga_…
Content-Type: application/json
{
"userId": "42",
"name": "Alice Wanjiku",
"avatarUrl": "https://…/alice.png",
"ttlSeconds": 3600
}
Response
{
"token": "eyJ…",
"expiresAt": "2026-10-09T18:45:12Z",
"user": {
"id": "42",
"name": "Alice Wanjiku",
…
}
}
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.
How it works
-
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.
-
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.
-
Your front end chats
The front end lists conversations and sends messages and files over REST, and hears what happens live on a WebSocket.
-
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.
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 /creates or updates a group for your order and its members. Your server posts notes into it and closes it when done.conversations/ external/ order-10247 -
Messages numbered without gaps
Each message has a
seq, so unread counts, read receipts and catching up are simple comparisons. AclientIdmakes sending safe to repeat. -
Replies, edits and reactions
Reply, edit, delete for everybody, react, mention and search. A
customTypeandmetadatalet 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.createdlists 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.
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 / for unread counts, then GET …/ 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
Tell us what you are building, and we will set you up with keys to try it.