Prerequisites
- You must be a member of the Branch you want to message.
- Your session cookie must be valid (you are logged in).
- If you want to attach files, upload them first — see Media Uploads.
Step 1 — Find or Create a Branch
Get a summary of all your Branches (with unread counts) usingGET /api/branches/overview:
id, name, ispm, members, unread, and last_at. Use the id field in subsequent calls.
If you need a new Branch, create one first — see the Branches concept page for details.
Step 2 — Send a Message
POST /api/bm/create
An optional array of filenames previously uploaded to the Branch CDN. Maximum 10 items. See Media Uploads.
new_bmessage Socket.IO event with the same payload.
Step 3 — Attach Files
Upload your file to the Branch CDN first, then include the returnedfilename in the cdn array:
GET /cdn/benches/<branch_id>/<filename> (requires an active session).
Step 4 — Listen for Real-Time Replies
After sending a message, subscribe tonew_bmessage on your Socket.IO connection so you see replies without polling:
List Messages (Pagination)
POST /api/bm/list
Return only messages with an ID lower than this value. Use the smallest
id from your previous page to load older messages.has_more is true, pass "before_id": <lowest_id_in_current_page> to fetch the next older batch.
Edit a Message
POST /api/bm/edit — you can only edit your own messages.
"edited": true) is returned and broadcast to all Branch members as an update_bmessage event.
Delete a Message
POST /api/bm/delete — you can only delete your own messages.
delete_bmessage event: {"id": 1045, "branch_id": 12}.
Mark a Message as Read
POST /api/bm/mark_read — records your read receipt on the message.
update_bmessage event is broadcast to all members with the updated read array so every client can update its unread indicator.
Fetch a Single Message
POST /api/bm/get