Send, Edit, and Reply to Messages in Clody Branches

Messaging in Clody happens inside Branches — private spaces shared between friends. Every message you send is delivered instantly to all Branch members through Socket.IO, so conversations feel live. This guide walks you through the full message lifecycle: finding or creating a Branch, sending your first message, paginating history, and keeping messages tidy with edits and deletes.

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) using GET /api/branches/overview:

curl https://clody.lol/api/branches/overview \
  -b "session=<your_session_cookie>"

The response is an array of Branch objects, each including 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

number

required

The ID of the Branch you are sending to. You must be a member.

string

required

The message text. Maximum 5 000 characters.

array

An optional array of filenames previously uploaded to the Branch CDN. Maximum 10 items. See Media Uploads.

number

The ID of a message in the same Branch that this message is replying to.

curl -X POST https://clody.lol/api/bm/create \
  -H "Content-Type: application/json" \
  -b "session=<your_session_cookie>" \
  -d '{
    "branch": 12,
    "content": "Hey! Are we still on for Saturday?",
    "cdn": [],
    "answer_to": null
  }'

Response — message object:

{
  "id": 1045,
  "branch": 12,
  "author": 7,
  "content": "Hey! Are we still on for Saturday?",
  "cdn": [],
  "edited": false,
  "created_at": 1718200000,
  "read": [],
  "data": { "answer_to": null }
}

All Branch members receive a new_bmessage Socket.IO event with the same payload.

Step 3 — Attach Files

Upload your file to the Branch CDN first, then include the returned filename in the cdn array:

# 1. Upload
curl -X POST https://clody.lol/api/cdn/benches/upload \
  -b "session=<your_session_cookie>" \
  -F "file=@photo.jpg" \
  -F "id_bench=12"

# Response: {"filename": "a3f8...b2.jpg", "original_name": "photo.jpg"}

# 2. Send with attachment
curl -X POST https://clody.lol/api/bm/create \
  -H "Content-Type: application/json" \
  -b "session=<your_session_cookie>" \
  -d '{
    "branch": 12,
    "content": "Check out this photo",
    "cdn": ["a3f8b2.jpg"]
  }'

Retrieve an attached file with GET /cdn/benches/<branch_id>/<filename> (requires an active session).

Step 4 — Listen for Real-Time Replies

After sending a message, subscribe to new_bmessage on your Socket.IO connection so you see replies without polling:

socket.on("new_bmessage", (message) => {
  if (message.branch === currentBranchId) {
    appendMessageToUI(message);
  }
});

See Real-Time Events for connection setup.

List Messages (Pagination)

POST /api/bm/list

number

required

Branch ID to fetch messages from.

number

Return only messages with an ID lower than this value. Use the smallest id from your previous page to load older messages.

number

How many messages to return. Defaults to 30, maximum 100.

curl -X POST https://clody.lol/api/bm/list \
  -H "Content-Type: application/json" \
  -b "session=<your_session_cookie>" \
  -d '{"branch": 12, "limit": 30}'

Response:

{
  "messages": [ /* array of message objects, oldest first */ ],
  "has_more": true
}

When 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.

number

required

The message ID to edit.

string

required

The replacement text. Maximum 5 000 characters.

curl -X POST https://clody.lol/api/bm/edit \
  -H "Content-Type: application/json" \
  -b "session=<your_session_cookie>" \
  -d '{"id": 1045, "new_content": "Hey! Are we still on for Sunday?"}'

The updated message (with "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.

curl -X POST https://clody.lol/api/bm/delete \
  -H "Content-Type: application/json" \
  -b "session=<your_session_cookie>" \
  -d '{"id": 1045}'

All Branch members receive a 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.

curl -X POST https://clody.lol/api/bm/mark_read \
  -H "Content-Type: application/json" \
  -b "session=<your_session_cookie>" \
  -d '{"id": 1045}'

An 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

curl -X POST https://clody.lol/api/bm/get \
  -H "Content-Type: application/json" \
  -b "session=<your_session_cookie>" \
  -d '{"id": 1045}'

Error Reference

HTTP Status	Meaning
`400`	Missing required field, content too long, or too many CDN attachments
`403`	You are not a member of the Branch
`404`	Message or Branch not found

Get Started

Core Concepts

Guides

Send, Edit, and Reply to Messages in Clody Branches

Prerequisites

Step 1 — Find or Create a Branch

Step 2 — Send a Message

Step 3 — Attach Files

Step 4 — Listen for Real-Time Replies

Edit a Message

Delete a Message

Mark a Message as Read

Fetch a Single Message

Error Reference

​Prerequisites

​Step 1 — Find or Create a Branch

​Step 2 — Send a Message

​Step 3 — Attach Files

​Step 4 — Listen for Real-Time Replies

​List Messages (Pagination)

​Edit a Message

​Delete a Message

​Mark a Message as Read

​Fetch a Single Message

​Error Reference

Prerequisites

Step 1 — Find or Create a Branch

Step 2 — Send a Message

Step 3 — Attach Files

Step 4 — Listen for Real-Time Replies

List Messages (Pagination)

Edit a Message

Delete a Message

Mark a Message as Read

Fetch a Single Message

Error Reference