v0.4.1 to v0.4.1

---

name: octo-messaging

version: 0.4.1

description: Messaging domain — send/edit/sync messages, read receipts, groups and threads (User Bot), and event polling. Covers App Bot DM-only constraints. Load after octo-shared.

metadata:

requires:

skills: ["octo-shared"]

---

# octo-messaging — messages, groups, threads, events

Three related domains live here. They all call `$OCTO_API_BASE_URL/v1/bot/*`.

| Domain | App Bot | User Bot |

|-----------|-------------------|----------|

| `message` | yes (DM only) | yes (DM + group + thread) |

| `group` | read-only | full |

| `thread` | **blocked** | full |

| `event` | yes | yes |

## 1. `message` — 4 commands

```bash

# Send a message. payload is a JSON object (not a flag) — pass it inside --data.

# payload.type is an INTEGER code (1=text); see the payload table below.

--data '{"payload":{"type":1,"content":"hello"}}' \

[--stream-no <n>] [--on-behalf-of <uid>]

# Edit by (message-id, channel-id, channel-type). content-edit is the new

# content, stored opaquely server-side — carry the new payload, same shape as send.

--channel-id <cid> --channel-type <t> \

--content-edit '{"type":1,"content":"updated"}'

# Pull history for a channel. Use --data for non-trivial filters.

# Mark messages read.

--message-ids m1 --message-ids m2

```

### `channel-type` values

`1` = direct (DM), `2` = group, `5` = thread.

### App Bot restrictions (enforced server-side)

- `send` accepts **only** `channel-type=1`; group/thread are rejected, and even for DM the bot must have a friend relationship with the recipient.

- `sync` explicitly blocks `channel-type=2`.

- `edit` and `read-receipt` work in DM; other scopes follow bot-kind rules.

### `payload` shape

`payload` is an object (never auto-promoted to a flag). Wrap it under the top-level `payload` key and pass the whole body via `--data '{"channel_id":"…","channel_type":1,"payload":{…}}'` (or `--data @file.json`, `--data @-`).

**`payload.type` is an integer code (NOT a string like `"text"`).** Authoritative source: `common.ContentType` in `octo-lib/common/msg.go` (the server reads it as an int).

Chat content types:

| type | meaning | common payload fields |

|------|-------------------|--------------------------------|

| 1 | Text | `content` |

| 2 | Image | `url, width, height` |

| 3 | GIF | `url, width, height` |

| 4 | Voice | `url, duration` |

| 5 | Video | `url, width, height, duration` |

| 6 | Location | `latitude, longitude` |

| 7 | Card | `uid, name` |

| 8 | File | `url, name, size` |

| 11 | MultipleForward | (merged-forward) |

| 12 | VectorSticker | (sticker) |

| 13 | EmojiSticker | (emoji sticker) |

| 14 | RichText | (rich text) |

| 16 | InviteJoinOrg | (org invite) |

(System/notification types — 1000+ for group events, 2000 Tip — are server-generated, not sent by bots.) Text example: `{"type":1,"content":"hello"}`.

`--on-behalf-of <uid>` makes `send`/`typing` act as a user persona (OBO) — requires an active OBO grant + channel scope, else the server returns `OBO not authorized`.

## 2. `group` — 9 commands (5 read + 4 write)

Read operations (both bot types):

```bash

```

Write operations (**User Bot only**):

```bash

```

App Bot attempting any of the four write operations gets `FORBIDDEN` with message `"app bot does not support group operations"`.

## 3. `thread` — 8 commands, **User Bot only**

Every thread operation calls `validateBotGroupAccess()` on the backend and rejects App Bot unconditionally. Don't attempt these with an `app_*` token.

```bash

```

The User Bot must be a member of the parent group.

## 4. `event` — polling for inbound events

```bash

```

### Important: `event list` is a **POST**

### Standard poll loop

```bash

cursor=0

while :; do

# response shape: {ok, data:{status, results:[{event_id, event_type, message{...}}]}}

echo "$batch" | jq -c '.data.results[]' | while read -r ev; do

id=$(jq -r '.event_id' <<<"$ev")

process "$ev"

cursor=$id

done

sleep 2

done

```

`--limit` defaults to 20, caps at 100.

## 5. Error recovery cheatsheet

| Symptom | Likely cause / fix |

|--------------------------------------------------------|----------------------------------------------------------------|

| `FORBIDDEN` + `app bot does not support group…` | Switch to a User Bot (`bf_*`) or fall back to DM. |

| `send` → `permission` on DM | No friend relationship; add the bot as a friend first. |

| `sync` rejected with `channel-type=2` | App Bot cannot sync groups — use User Bot. |

| `VALIDATION_ERROR` on `send` | `payload` must be an object, not a string. |

| `event list` returns `data.results: []` | No events since the cursor; keep the cursor and poll again. |

## 6. Schema lookup

```bash

```