API-пайплайн: публиковать ваши посты в группах в темпе, заданном их трафиком, и следить за отправленным и удалённым

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

Цель: ваши оракулы публикуют ваши посты в списке групп, каждую группу — в темпе её собственного трафика, а вы следите за тем, что отправлено, удалено и получило ответы. На ответы к вашим постам оракул отвечает по вашей агенде.

Шаги

1. Создать (Paused).

POST /v0/my/campaigns
Idempotency-Key: ann-villas-1
{"title": "Villa offers", "kind": "mtproto_announcements", "project_nonce": "<Pro project>",
 "posts": ["<post or posts workspace>"], "tg_groups": ["<preset nonce>"], "oracles": ["<oracle nonce>"],
 "agenda": "<swappable agenda>", "speed": "medium", "mode": "linear", "forward": false, "join_missing": false}
→ {"nonce": "470380000000000001", "kind": "mtproto_announcements", "status": "Paused", …}

• posts: ваши карточки-посты или их воркспейсы; у каждого должен быть текст.
• mode: linear (группы по очереди) или magnet (сначала самые большие группы).
• speed: x_slow | slow | medium | fast | x_fast: как скоро идёт следующий раунд; более медленные раунды ждут, пока будет готово больше групп.
• forward: true: пересылать исходные посты Telegram вместо отправки копий; переслать можно только посты, которые Cabi.Chat импортировал из Telegram; иначе start отвечает 400 и называет пост.
• join_missing: true (по умолчанию false): когда в группе очередь доходит до оракула, которого там ещё нет, он вступает в неё; ваш пост уходит в эту группу в одном из следующих раундов. Оракул остаётся в группе.

2. Запустить. POST /v0/my/campaigns/470380000000000001/start → {"success": true, "status": "Active", "is_active": true}.

3. Следить.

GET /v0/my/campaigns/470380000000000001/sends?page=1&limit=50
→ {"rows": [{"username": "example_group", "message_id": 17552, "post": "…", "oracle": "…",
             "sent_at": "…", "deleted_at": null, "replied_at": "…", "replies": 2}], "total": 56, "has_more": true, …}
GET /v0/my/campaigns/470380000000000001/performance
→ {"totals": {"sent": 56, "deleted": 33, "replied": 3, "groups": 39, "oracles": 2, …}, "timeline": […], "groups": […]}

Фактически отправленные посты также хранятся в sent_posts_workspace кампании.

4. Остановить. POST …/stop. Кампания работает, пока вы её не остановите.

За кадром

• Группа получает ваш следующий пост, когда с вашего прошлого там прошло достаточно новых сообщений: в оживлённые группы посты идут чаще, тихие ждут. Посты чередуются.
• Ваши кампании одного проекта держат эту дистанцию сообща: в группе считается последний пост любой из них. Каждый ваш оракул тоже её соблюдает, для какой бы кампании он ни писал: оракул, который писал в группе слишком недавно, там пропускается, и пробует следующий по порядку.
• Ваши оракулы работают в группе по очереди: у каждой группы свой порядок оракулов, поэтому разные группы начинают с разных. Если оракул сейчас не может там написать, в том же раунде пробует следующий по порядку; в группу уходит один пост за раунд.
• Кроме того, каждый ваш оракул публикует в группы в собственном ровном темпе, распределённом по суткам и общем для всех ваших кампаний; недавно подключённый оракул начинает медленнее. Оракул, которому по темпу ещё рано, пропускается, и пробует следующий по порядку; если рано всем, группа ждёт одного из следующих раундов.
• Оракул, которого Telegram попросил подождать, пропускает раунды, пока снова не сможет отправлять.
• Группа, которой больше нет, или где ваши оракулы забанены или не могут писать, выпадает из раундов. Без join_missing группа, где нет ни одного из ваших оракулов, пропускается.
• Группа, где админы удаляют большую часть ваших постов, автоматически ставится на паузу, а позже попытка повторяется.
• На ответы к вашим постам оракул отвечает по agenda; эти ответы — запуски ИИ; их стоимость видна в ваших расходах на ИИ: API-пайплайн: ваши расходы на ИИ. Цены: link

Правила

• Для запуска нужны Pro-проект, группы, оракулы, посты и агенда: 400 assign telegram groups before activating, assign oracles before activating, assign posts before activating, announcements require an agenda assigned: replies to your posts are answered under it.
• Соблюдайте правила каждой группы: посты, которые удалили её админы, видны как deleted_at.

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