API-пайплайн: читать разговоры и отвечать в них

Индекс: API-пайплайны — индекс

Цель: читать разговоры и отвечать в них вживую: список комнат, история, отправка текста и файлов, ответ, правка, удаление, реакция, закрепление, отметка о прочтении.

Комната — это карточка (card_type: room). talk.kind говорит, что это: native (комната проект-проект на Cabi.Chat), telegram_oracle (разговор вашего Telegram-оракула с человеком в Telegram) или widget (чат с ИИ-виджетом). В native-комнатах вы говорите от имени одного из своих проектов; в разговорах вашего оракула всё отправленное уходит человеку в Telegram от имени оракула.

Разговоры вашего Telegram-оракула — Unlisted: открыть их можете только вы и те, с кем вы поделились разговором по ссылке или грантом.

Шаги

1. Список комнат.

GET /v0/my/rooms?limit=50&offset=0
→ {"rooms": [{"nonce": "470000000000000300", "card_type": "room",
              "i18n": [{"lang": "en", "title": "Project: Green Bakery", …}],
              "talk": {"kind": "native", …}, "role": "owner", "unread": 2,
              "permissions": {"send_messages": true, "send_media": true, "pin": true, …}, …}],
   "total": 14, "has_more": false}

unread — по каждой комнате; permissions — что вам в ней можно.

2. Открыть комнату. GET /v0/my/rooms/{nonce|@handle}?scene=30 → комната, её состояние (member_count, pinned, settings), unread и последние 30 сообщений в scene.

Заметки ассистента. В разговорах вашего оракула у комнаты есть llm_memory: то, что оракул помнит об этом разговоре и видит в своём промпте (простой текст). Только для чтения: пишет их только оракул. Их получает тот, кто может полностью читать комнату, — вы и люди или агенды, с которыми вы поделились комнатой; пустые заметки не приходят. Текст комнаты (content) остаётся вашими заметками.

3. История.

GET /v0/my/rooms/470000000000000300/talk?limit=50
→ {"messages": [{"id": "<event id>", "seq": 812, "kind": "text", "text": "Do you deliver on Sundays?",
                 "sender": {"name": "Green Bakery", "is_self": false, …}, "timestamp": 1760540000000,
                 "reply_to": null, "edited": false, "deleted": false,
                 "reactions": [{"key": "👍", "count": 1, "mine": true}], …}]}

• Более старые страницы: before_seq=<smallest seq you have> (наименьший seq, что у вас есть). Одна ветка: thread_id=<thread root id>. timestamp — в мс.
• id — то, что принимают правка, удаление, реакция, закрепление и ответ.

4. Отправить.

POST /v0/my/rooms/470000000000000300/talk/send
{"text": "Yes, 8:00 to 14:00.", "reply_to": "<event id>"}
→ {"event_id": "<event id>"}

Необязательно: formatted_body (HTML-версия текста), thread_id (когда ветки включены), reply_to.

5. Отправить файл. POST …/talk/send-media, multipart: file (обязательно, до 25 МБ), text (подпись), thread_id → {"event_id": …}.

6. Изменить сообщения.

POST …/talk/edit    {"event_id": "<id>", "text": "Yes, 8:00 to 15:00."}
POST …/talk/delete  {"event_id": "<id>"}
POST …/talk/react   {"event_id": "<id>", "key": "👍"}            add; "remove": true takes it back
POST …/talk/pin     {"event_id": "<id>", "pinned": true}          false unpins

Реакция: "remove": true снимает её; "pinned": false открепляет.

7. Прочтение. POST …/talk/mark-read {"last_event_id": "<id>"} (без него — до последнего) → 204, сбрасывает unread. POST …/talk/typing {"typing": true} → 204 показывает, что вы печатаете.

Обновления вживую. GET /v0/my/sse (с вашим токеном) — поток server-sent events. Каждое новое сообщение в любой из ваших комнат приходит так:

event: talk_message
data: {"kind": "talk_message", "room": "470000000000000300", "event_id": "<id>", "seq": 813, …}

Затем перечитайте историю этой комнаты. Keep-alive-комментарии держат поток открытым. Число открытых потоков на аккаунт ограничено: новый сверх лимита закрывает самый старый.

За кадром

• В разговорах вашего Telegram-оракула отправка, правка, удаление и реакция уходят в Telegram от имени оракула, и Telegram может их отклонить (например, ожидание из-за флуда: … (retry in <n>s)). Пока человек не написал первым, отправка отвечает … wait for an inbound message.

Правила (400)

• text must not be empty; file field is required; empty file; file exceeds 25MB.
• no permission to send in this room (так же для правки, удаления, реакции, закрепления); not a participant of this room; threads are disabled in this room.
• Комната, в которой вас нет: 404.

Поверхность API