API-пайплайн: создать, настроить, запустить, остановить, измерить и удалить Telegram-кампанию любого вида

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

Цель: создать, настроить, запустить, остановить, измерить и удалить Telegram-кампанию любого вида. Кампания — это карточка (card_type: "campaign"), которая выполняет одну задачу для проекта в Telegram, через ваших оракулов и в группах. Все виды используют одну карточку, один набор маршрутов и один жизненный цикл; kind выбирается при создании и не меняется.

Виды

Группы для любого вида: API-пайплайн: добавить свои Telegram-группы, найти группы по ключевому слову, месту или рубрике, проверить их и подключить к кампании

Шаги

1. Создать (всегда Paused).

POST /v0/my/campaigns
Idempotency-Key: camp-join-phuket-1
{"title": "Join Phuket chats", "kind": "mtproto_join_chats",
 "project_nonce": "<Pro project>", "tg_groups": ["<preset nonce>"], "oracles": ["<oracle nonce>"]}
→ {"nonce": "470360000000000001", "card_type": "campaign", "kind": "mtproto_join_chats",
   "status": "Paused", "is_active": false,
   "telegram_groups_list": ["<preset nonce>"], "oracles_list": ["<oracle nonce>"],
   "lists": {"telegram_groups": [{…tile…}], "oracles": [{…}], "posts": []}, …}

• title обязателен. project_nonce: проект, которым вы владеете или на который у вас есть x.
• Слоты tg_groups, oracles, posts принимают nonce карточек или воркспейсов строками (не @handles). Оракулам нужен x, группам и постам — r; чужая приватная карточка отклоняется. Они возвращаются как *_list (nonce) и lists.* (плитки).
• not_tg_groups: группы, которые кампания пропускает, — nonce групп или воркспейсов, по тем же правилам, что и tg_groups; воркспейс исключает все группы внутри себя. Группа, которая есть в обоих списках, пропускается; пустой список ничего не исключает. Возвращается как not_telegram_groups_list и lists.not_telegram_groups. Его соблюдают все виды; кампания реакций без групп ставит реакции во всех группах своих оракулов, кроме этих. Подробнее: API-пайплайн: добавить свои Telegram-группы, найти группы по ключевому слову, месту или рубрике, проверить их и подключить к кампании
• agenda: сменная агенда, которой вы владеете или которую можете выполнять (иначе 400).
• workspaces: ["<ws>"] помещает карточку в воркспейсы, куда вы можете писать.
• Фиксированные наборы: speed x_slow | slow | medium | fast | x_fast (по умолчанию medium); mode linear | magnet; batch_window 15m | 30m | 60m | 3h | 6h | 12h | 24h | 72h; batch_messages 50–2000; reactions 1–16 эмодзи.

2. Настроить. PATCH /v0/my/campaigns/{nonce} с любым полем создания; слот в теле заменяет весь список. Активный радар или ИИ-скаут подхватывает изменения ключевых слов, исключений, групп, проекта, auto и пачек на ходу.

3. Запустить.

POST /v0/my/campaigns/470360000000000001/start
→ {"success": true, "status": "Active", "is_active": true}

Каждая непройденная проверка — 400 с причиной: assign this campaign to a project before activating, assigned project not found, project needs an active Pro membership to run campaigns, assign telegram groups before activating, assign oracles before activating, assign posts before activating, announcements require an agenda assigned: …, assign at least one reaction before activating, ai scout requires an agenda assigned.

• Виды с оракулами (анонсы, вступление, выход, реакции): если кампания не может стартовать прямо сейчас, start отвечает 400 или {"success": false, "status": "Paused"}, и она остаётся Paused: попробуйте позже. Группы или оракулы, которые во время работы раскрываются в пустоту → Failed.
• Радар и ИИ-скаут: 200 с новым status; если вызов не прошёл, прочитайте кампанию через GET, прежде чем повторять.

4. Остановить. POST …/stop → Paused (радар сохраняет настройки и совпадения). 400 значит, что остановка не прошла: вызовите stop ещё раз.

5. Измерить.

GET /v0/my/campaigns/{nonce}/performance
→ {"totals": {"sent": 40, "deleted": 3, "replied": 5, "reacted": 0, "groups": 25, "oracles": 1,
              "joined": 0, "join_pending": 0, "already_member": 0, …, "first_at": "…", "last_at": "…"},
   "timeline": [{"day": "2026-10-08", "sent": 0, "joined": 31, "reacted": 40, …}],
   "groups": [{"username": "example_group", "sent": 3, "deleted": 2, "replied": 0, "join_status": "already_member", …}],
   "join": {"member": 30, "pending": 4, "skipped": 2, "remaining": 0, "oracles": [{…, "flooded_until": null}]}}

GET /v0/my/campaigns/{nonce}/sends?page=1&limit=50
→ {"rows": [{"username": "example_group", "message_id": 17552, "oracle": "…", "post": "…",
             "sent_at": "…", "deleted_at": null, "replied_at": "…", "replies": 2}], "total": 40, "has_more": true, …}

Результаты радара — это совпадения и комнаты в инбоксе, а не отправки. Визиты на лендинг по кампании: GET /v0/my/console/traffic/campaign?campaign=. Cabi.Chat Inbox — лиды

6. Удалить. Сначала остановите, затем DELETE /v0/my/campaigns/{nonce}.

Статусы: Active, Paused, Completed, Cancelled, Failed. Когда проект теряет Pro, его активные кампании ставятся на паузу.

Активность одного оракула

Что один оракул сделал во всех кампаниях (только владелец, иначе 404):

• GET /v0/my/oracles/{nonce}/performance: та же форма, что у статистики кампании, для этого оракула.
• GET /v0/my/oracles/{nonce}/campaigns → {"rows": [{"campaign": "…", "title": "…", "kind": "mtproto_announcements", "sent": 40, "replied": 5, "joined": 0, "join_pending": 0, "join_banned": 0, "join_dead": 0, "join_flood": 0, "already_member": 0, "left": 0, "reacted": 0, "groups": 25, "first_at": "…", "last_at": "…"}]}: строка на каждую кампанию, новые первыми, не больше 100.
• Его группы и отправленные посты: GET /v0/my/oracles/{nonce} → groups_workspace, sent_posts_workspace; читайте их через GET /v0/my/workspaces/{ws}?contained_limit=30.

Статусы членства в этих отчётах: joined, join_pending (заявка на вступление ждёт админов), join_banned, join_dead (группы больше нет), join_skipped, join_flood (Telegram попросил подождать), join_limit (аккаунт упёрся в лимит вступлений Telegram), already_member, left, leave_failed, not_member.

За кадром

• Радару и ИИ-скауту не нужен ваш оракул, чтобы читать группы; остальные виды действуют через ваших оракулов.
• Запуски ИИ (первые сообщения радара, пачки ИИ-скаута, ответы на реплаи к анонсам) — это расход ИИ; его стоимость видна в ваших расходах на ИИ: API-пайплайн: ваши расходы на ИИ. Цены: link

Правила (кто что может)

GET /v0/my/campaigns показывает только ваши кампании. Поделиться кампанией по ссылке (права, grant_ttl, кто может принять): индекс, «Доступ по ссылкам»; когда грант с w заканчивается, кампания ставится на паузу, если её не держит другой действующий грант с w. Граф Cabi.Chat — политики карточек

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