Chat

The Chat API is the surface the Backbuild apps use for Backbuild Chat: channels, direct and group conversations, their members, messages and their edits, reactions, pins, delivery and read receipts, the people you chat with, and attachments from Backbuild Files. This page covers what is particular to Chat: how a message body travels, paging, limits and errors. Every route, with its fields, is in the Chat endpoint reference.

Who Can Call It

Every route is under /v1/chat and takes a signed-in user’s access token, and acts in that session’s organization; API keys are not accepted on these routes. Chat must be on for that organization (otherwise 403 FEATURE_DISABLED), and the caller must be an active member with permission to use Chat. A route about a conversation also needs the caller to be in it, or to be allowed to see it; a conversation the caller may not know about answers 404, the same as one that does not exist. Roles inside a channel (owner, manager, member) decide who can rename it, add and remove people, and archive it; they are described in Conversations and People.

How a Message Body Travels

A message body never crosses the API as plaintext. The sending device encrypts it with the conversation’s key and sends the sealed envelope as base64 in envelope_b64, with the key generation it used in key_epoch. Message lists return the same envelopes, which the members’ devices open. Everything around the body stays in cleartext so the service can route and list it: the sender, the time, the mentions, the attachments, reactions, pins, and read and delivered positions.

• Who else can open it. In a standard conversation, Backbuild opens a new or edited message once, on the server, with your organization’s chat key, to check its mentions and build its search index, and does not store the plaintext. That is why Chat is end-to-end encrypted between devices but not zero-access; the full account, and what the service can see, is in Security and Administration. Zero-knowledge conversations cannot be created yet.
• Keys change. When someone leaves or is removed, the conversation’s key is replaced and key_epoch moves on. A send or edit sealed with an older key is refused with 409 and error.details.code STALE_EPOCH: fetch the new key, seal again, and retry.
• Sends are safe to retry. Each send carries a client_msg_id the client chooses. Sending again with the same id returns the first message with deduplicated: true, so a retry after a dropped connection never posts twice.
• Edits are checked. An edit names the revision it replaces in expected_revision, so two edits cannot silently overwrite each other (REVISION_CONFLICT).
• Mentions are declared. A send lists its mentions in cleartext so the right people are notified, and they must match the mentions inside the sealed body.

Sealing and opening need the conversation key on a Chat device of the caller’s. The Backbuild apps create each device’s keys, receive conversation keys and handle key changes; that device-key protocol is not part of the public reference. The conversation, member, reaction, pin, receipt, people and attachment routes work without it.

Attachments

A message attaches files from Backbuild Files as chips. Check them first with POST /v1/chat/conversations/{id}/chips/resolve, then pass the chips with the send. Sending gives the conversation access to each file; opening (POST /v1/chat/chips/authorize) and downloading (GET /v1/chat/chips/file) check that access again every time, and POST /v1/chat/chips/revoke ends it. Files are protected by Backbuild Files, not by the conversation’s key; see Messages and Files.

Paging

List routes return a page and a next_cursor; pass it back as cursor for the next page, and stop when it is null. Treat cursors as opaque. Message lists page newest first by default; direction=after pages forward from a cursor instead, oldest first. Page sizes: up to 200 messages (default 50), 500 conversations (default 200), 200 members (default 50), 100 channels when browsing (default 50) and 100 pins (default 50). A deleted message stays in the list as a tombstone without a body.

Rate Limits

Over a limit, the answer is 429 RATE_LIMIT_EXCEEDED; wait for the Retry-After time.

Errors

Errors use the standard envelope. A 403 or 409, and a 404 for a deleted file, carries the specific reason in error.details.code, and the apps branch on it:

Where to Go Next

• Chat endpoint reference: every route, field and answer.
• Backbuild Chat: how people use it.
• Security and Administration: encryption, what the service can see, and the controls for administrators.
• Authentication: get a user’s access token.