Chat

Open an attachment

Checks that the caller can still open one attachment of a message, and returns what to open: the file's name, type and size and a link to it in Backbuild Files. Access is checked every time: the caller must still be a member, the conversation's access to the file must still stand, and the sender must still be allowed to share it. At most 30 attachment requests a minute per user.

Auth Session JWT (Bearer)

Request Body

Responses

Download an attachment

Checks access exactly as opening does, then returns the file's bytes. There is no shareable link: each download is made with the caller's own session, so someone removed from the conversation cannot reuse it. The file is sent as a download (`Content-Disposition: attachment`) and is not cached. At most 30 attachment requests a minute per user.

Auth Session JWT (Bearer)

Parameters

Responses

Remove a conversation's access to an attachment

Ends the conversation's access to one attached file: every attachment of that file in the conversation then opens as access removed, and the file itself stays where it is in Backbuild Files. The message's sender, an owner or manager of the conversation, or a Chat administrator can do this, also in an archived conversation. Repeating it answers `revoked: false`. At most 30 attachment requests a minute per user.

Auth Session JWT (Bearer)

Request Body

Responses

List your conversations

Lists the conversations the caller belongs to, with the caller's own membership state for each (role, notification setting, star, section, read position and unread mentions) and whether it has unread messages. Exact unread counts are not computed. At most 240 reads a minute per user.

Auth Session JWT (Bearer)

Parameters

Responses

Create a channel or group conversation

Creates a channel or a group conversation and makes the caller its owner. A channel name is lowercase letters, digits, `.`, `_` and `-`, up to 80 characters, and must be free (`NAME_EXISTS`). Creating a channel needs the permission to create channels, and the organization's settings may limit who can. A group conversation holds at most 9 people including the caller; asking for the same set of people again returns the existing conversation (`existing: true`). A one-to-one conversation is opened with `POST /v1/chat/dm/open`, not here. `zero_knowledge` conversations cannot be created yet. At most 30 changes to conversations, memberships and settings a minute per user, together.

Auth Session JWT (Bearer)

Request Body

{
  "type": "channel",
  "name": "launch-planning",
  "visibility": "private",
  "topic": "Q4 launch",
  "member_user_ids": []
}

Responses

Get a conversation

Returns a conversation and the caller's membership in it. A member sees it in full; anyone in the organization can see a public channel's details (null membership) without its messages. At most 240 reads a minute per user.

Auth Session JWT (Bearer)

Parameters

Responses

Rename or describe a conversation

Changes a channel's name, emoji, topic, description or posting rule, or a group conversation's title and emoji. Send at least one field; `null` clears a field. In a channel, renaming and the posting rule need the owner role or the organization's channel management permission, and the topic and description need the manager role or above. Any participant can set a group conversation's title and emoji. A one-to-one conversation cannot be renamed. A rename, a topic, title or posting-rule change posts a notice in the conversation; a description change does not. At most 30 changes to conversations, memberships and settings a minute per user, together.

Auth Session JWT (Bearer)

Parameters

Request Body

{
  "topic": "Launch on the 14th"
}

Responses

Archive a channel

Archives a channel: its members can still read it, but it takes no new messages. Needs the owner role or the organization's channel management permission; the organization's default channel cannot be archived. Repeating it changes nothing. Send no body, or `{}`. At most 30 changes to conversations, memberships and settings a minute per user, together.

Auth Session JWT (Bearer)

Parameters

Responses

Check attachments before sending

Checks Backbuild Files items the caller wants to attach and returns them in the form a send stores. Only files from Backbuild Files can be attached (`CHIP_UNSUPPORTED`, with the `chip_index`), and the caller must be allowed to share each one. Nothing is shared until the message is sent; the send then gives the conversation access to each file. At most 30 attachment requests a minute per user.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

Turn a group conversation into a private channel

Converts a group conversation into a private channel with the name given (any participant can), or a public channel into a private one (owner role or the organization's channel management permission). Conversion is one way. At most 30 changes to conversations, memberships and settings a minute per user, together.

Auth Session JWT (Bearer)

Parameters

Request Body

{
  "to": "private_channel",
  "name": "launch-core"
}

Responses

Join a public channel

Adds the caller to a public channel. Joining one you already belong to returns `existing: true`; the first person to join an empty channel becomes its owner. A private channel, or one the caller cannot see, answers 404. Send no body, or `{}`. At most 30 changes to conversations, memberships and settings a minute per user, together.

Auth Session JWT (Bearer)

Parameters

Responses

Leave a conversation

Removes the caller from a channel or group conversation and posts a notice. The conversation's key is then replaced, so the caller cannot open messages sent afterwards (`rekey_required`). When the last owner leaves, the longest-standing manager, else member, becomes owner; the last member leaving a private channel archives it. A one-to-one conversation and the organization's default channel cannot be left. Send no body, or `{}`. At most 30 changes to conversations, memberships and settings a minute per user, together.

Auth Session JWT (Bearer)

Parameters

Responses

List a conversation's members

Lists the people in a conversation: its members can read it, anyone in the organization can read a public channel's, and channel managers in the organization can read any channel's. Only names, roles and join details are listed, never a member's own read, notification or star settings. A channel lists active members; a direct or group conversation also lists deactivated ones (`is_deactivated: true`). At most 240 reads a minute per user.

Auth Session JWT (Bearer)

Parameters

Responses

Add people to a conversation

Adds active people from the organization. In a public channel any member can add people; in a private channel the manager role or above can. A group conversation holds at most 9 people (`GROUP_DM_LIMIT`; convert it to a channel for more). People already in the conversation are listed in `already_members`. New members can read messages from the conversation's current key onward. At most 30 changes to conversations, memberships and settings a minute per user, together.

Auth Session JWT (Bearer)

Parameters

Request Body

{
  "user_ids": [
    "0190a6f2-3c1e-7d4b-9a2f-5b6c7d8e9f01"
  ]
}

Responses

Change a member's role in a channel

Sets a channel member's role to owner, manager or member. Needs the owner role or the organization's channel management permission; the last owner cannot be demoted. At most 30 changes to conversations, memberships and settings a minute per user, together.

Auth Session JWT (Bearer)

Parameters

Request Body

{
  "role": "manager"
}

Responses

Remove a member from a channel

Removes someone from a channel and posts a notice; the conversation's key is then replaced so they cannot open later messages (`rekey_required`). Needs the manager role or above, or the organization's channel management permission; an owner can be removed only by another owner. Removing someone who is not a member answers `removed: false`. Removing yourself is the same as leaving. At most 30 changes to conversations, memberships and settings a minute per user, together.

Auth Session JWT (Bearer)

Parameters

Responses

Set your own preferences for a conversation

Changes the caller's own settings in a conversation: notification override, mute, star and sidebar section. Send at least one field; `null` clears it. Works on archived conversations too. At most 30 changes to conversations, memberships and settings a minute per user, together.

Auth Session JWT (Bearer)

Parameters

Request Body

{
  "is_starred": true
}

Responses

List messages

Returns a page of a conversation's messages, newest first by default, as sealed envelopes the caller's device opens (`envelope_b64`), with their cleartext details: sender, time, mentions, attachments, reactions, pin flag, thread counts and edit or delete marks. Deleted messages appear as tombstones without a body. `inactive_people` names anyone the page mentions or shows who has left or been deactivated, so their name still shows. Members only. At most 240 reads a minute per user.

Auth Session JWT (Bearer)

Parameters

Responses

Send a message

Sends a message to a conversation the caller belongs to. Message bodies are end-to-end encrypted: the API carries a sealed envelope (`envelope_b64`) that the sender's device encrypted with the conversation's key, and that members' devices open. In a standard conversation Backbuild opens a new or edited message once, on the server, with the organization's chat key, to check its mentions and build its search index; the plaintext is not stored. Sealing and opening need the conversation key on a registered Chat device, which the Backbuild apps manage; that device-key protocol is not part of this reference. `key_epoch` must be the conversation's current key generation; after a key change the send is refused with `STALE_EPOCH`, and the client fetches the new key, seals again and retries. `client_msg_id` makes a send safe to retry: the same id returns the first message with `deduplicated: true`. Mentions are listed in cleartext so the right people are notified, and must match the mentions sealed in the message. The conversation's posting rule applies (`POSTING_RESTRICTED`), and `everyone` is allowed only in the organization's default channel by people with that permission. Attachments are Backbuild Files items passed as chips (see `POST /v1/chat/conversations/{id}/chips/resolve`). At most 60 sends, edits, deletes, reactions, pins and read marks a minute per user, together.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

Edit a message

Replaces the body of the caller's own message with a newly sealed envelope. `expected_revision` is the revision the client loaded; if the message changed since then, for example through an edit from another device, the edit is refused (`REVISION_CONFLICT`). The organization's edit window applies (`EDIT_WINDOW_EXPIRED`). Mentions and chips follow the same rules as a send; leaving `chips` out keeps the attachments, and removing an attachment ends the conversation's access to that file unless another message still carries it. Message bodies are end-to-end encrypted: the API carries a sealed envelope (`envelope_b64`) that the sender's device encrypted with the conversation's key, and that members' devices open. In a standard conversation Backbuild opens a new or edited message once, on the server, with the organization's chat key, to check its mentions and build its search index; the plaintext is not stored. Sealing and opening need the conversation key on a registered Chat device, which the Backbuild apps manage; that device-key protocol is not part of this reference. At most 60 sends, edits, deletes, reactions, pins and read marks a minute per user, together.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

Delete a message

Deletes a message, leaving a tombstone: the body, search entry, reactions and pins are removed, and attachments it carried stop being shared with the conversation unless another message still carries them. The sender can delete within the organization's delete window; a Chat administrator who is a member of the conversation can delete any of its messages when the organization allows it. At most 60 sends, edits, deletes, reactions, pins and read marks a minute per user, together.

Auth Session JWT (Bearer)

Parameters

Responses

React to a message

Adds the caller's reaction. Adding the same reaction again returns it (`deduplicated: true`). A message holds at most 50 different reactions and 23 from one person (`REACTION_LIMIT`); a custom emoji must exist (`EMOJI_UNAVAILABLE`). At most 60 sends, edits, deletes, reactions, pins and read marks a minute per user, together.

Auth Session JWT (Bearer)

Parameters

Responses

Remove your reaction

Removes the caller's own reaction. At most 60 sends, edits, deletes, reactions, pins and read marks a minute per user, together.

Auth Session JWT (Bearer)

Parameters

Responses

List pinned messages

Lists a conversation's pinned messages, newest pin first, each with its message. Members only. At most 240 reads a minute per user.

Auth Session JWT (Bearer)

Parameters

Responses

Pin a message

Pins a message in the conversation for every member. Pinning it again returns the pin (`deduplicated: true`). A conversation has a limit on pins (`PIN_LIMIT`). At most 60 sends, edits, deletes, reactions, pins and read marks a minute per user, together.

Auth Session JWT (Bearer)

Parameters

Responses

Unpin a message

Removes a pin. At most 60 sends, edits, deletes, reactions, pins and read marks a minute per user, together.

Auth Session JWT (Bearer)

Parameters

Responses

Mark a conversation read

Moves the caller's read position forward to a message of this conversation (an older message changes nothing) and clears the unread-mention count when it reaches the newest message. While the caller shares read receipts, the move also updates what others see as read in a direct conversation. At most 60 sends, edits, deletes, reactions, pins and read marks a minute per user, together.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

Read delivery and read receipts

Returns how far every other member of a direct conversation has received and seen it, as the oldest such message id over those members: what the sender's ticks show. Nothing per member is returned. Channels have no receipts (`mode: none`). `read_through` is null unless the caller shares their own read receipts. Members only. At most 240 reads a minute per user.

Auth Session JWT (Bearer)

Parameters

Responses

Unarchive a channel

Reverses an archive, with the same permissions. Send no body, or `{}`. At most 30 changes to conversations, memberships and settings a minute per user, together.

Auth Session JWT (Bearer)

Parameters

Responses

Browse channels

Lists channels the caller can see: every public channel, and the private channels the caller belongs to. A private channel the caller is not in is never returned. `query` matches a channel's name or description. At most 240 reads a minute per user.

Auth Session JWT (Bearer)

Parameters

Responses

Report delivered messages

Reports, for up to 100 direct conversations at once, the newest message the caller's app has received, so senders see it as delivered. Each conversation may appear once. Conversations whose delivered position moved are listed in `advanced`; the rest in `skipped`. At most 60 sends, edits, deletes, reactions, pins and read marks a minute per user, together.

Auth Session JWT (Bearer)

Request Body

Responses

Open a direct conversation

Opens the direct conversation for a set of people, creating it the first time: no ids opens the caller's own space, one id the one-to-one conversation with that person, and more ids a group conversation (at most 9 people in all). Asking again returns the same conversation (`existing: true`). Every id must be an active person in the organization; a virtual worker or service account is refused like a non-member. At most 30 changes to conversations, memberships and settings a minute per user, together.

Auth Session JWT (Bearer)

Request Body

{
  "user_id": "0190a6f2-3c1e-7d4b-9a2f-5b6c7d8e9f01"
}

Responses

List the people you chat with

Lists the active people in the organization the caller has exchanged direct messages with, plus anyone whose one-to-one conversation the caller starred, most recent activity first. Virtual workers and service accounts are not people here. Conversation ids and messages are never included. At most 240 reads a minute per user.

Auth Session JWT (Bearer)

Parameters

Responses

Get your Chat settings

Returns the caller's own Chat settings in the active organization: notification mode, keywords, do-not-disturb, notification schedule, status and app preferences. Defaults are returned (`exists: false`) until the caller saves any. At most 240 reads a minute per user.

Auth Session JWT (Bearer)

Responses

Change your Chat settings

Changes the caller's own Chat settings; send at least one field. Only the caller's own settings can be changed: a `user_id` is refused. `prefs` is a small object the apps use for preferences such as pinned virtual workers (at most 8 KiB). At most 30 changes to conversations, memberships and settings a minute per user, together.

Auth Session JWT (Bearer)

Request Body

{
  "notification_mode": "mentions",
  "keywords": [
    "launch"
  ]
}

Responses