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

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

Цель: слышать людей в Telegram-группах, которые ищут то, что предлагает ваш проект, собирать их сообщения как совпадения, настраивать радар и выходить на первый контакт: черновик, который вы одобряете, или автоматический outreach через вашего оракула.

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

Как это работает

Слова → смысл → контакт.

Шаги

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

POST /v0/my/campaigns
Idempotency-Key: radar-nails-la-1
{"title": "Nail masters LA", "project_nonce": "<Pro project>",
 "keyword_groups": [["manicure", "pedicure", "nails"], ["looking for", "need", "recommend"]],
 "not_groups": [["vacancy", "hiring"]],
 "tg_groups": ["<preset nonce>"]}
→ {"nonce": "470370000000000001", "card_type": "campaign", "kind": "mtproto_radar",
   "status": "Paused", "is_outreach_enabled": false, "is_auto_enabled": false,
   "keyword_groups": […], "not_groups": […], "telegram_groups_list": ["<preset nonce>"], …}

kind по умолчанию mtproto_radar. Ответ содержит и поля других видов (speed, reactions, batch_*); не обращайте на них внимания.

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

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

Первый запуск создаёт воркспейсы радара и открывает их вам: Matches (read), Canonical (read + write); затем GET /v0/my/campaigns/{nonce} показывает matches_workspace и canonical_matches_workspace (и evicted_matches_workspace после первого исключения). Типичные 400: project needs an active Pro membership to run campaigns, outreach requires oracles assigned, outreach requires an agenda assigned.

3. Читать совпадения, новые первыми.

GET /v0/my/workspaces/<matches_workspace>?contained_limit=200&contained_offset=0
→ {"contained": [{"card_type": "post", "nonce": "470370000000000101", "snippet": "…",
                  "source_url": "https://t.me/example_group/17552", "created_at": "…", …}],
   "contained_next_offset": 200, …}

Одно совпадение целиком (автор, группа): GET /v0/graph/posts/{nonce} → author_username, source_group, source_group_username, expires_at. Поиск внутри совпадений: POST /v0/search/graph/keyword {"query": "gel", "card_type": "post", "workspace": "<matches_workspace>"}.

4. Настроить.

5. Первый контакт (по желанию). Включите outreach: PATCH {"oracles": ["<oracle or team workspace>"], "agenda": "<swappable agenda>", "is_outreach_enabled": true}.

По одному совпадению (только владелец):

POST /v0/my/campaigns/{nonce}/matches/{post}/draft
{"instructions": "mention the free first consultation"}
→ {"text": "…", "target_username": "…", "oracle_nonce": "…", "model": "…"}

POST /v0/my/campaigns/{nonce}/matches/{post}/outreach
{"text": "<the text you approved>"}
→ {"ok": true}

Каждый вызов может занять до пары минут; если не прошёл, попробуйте снова. Типичные 400: outreach is not enabled on this radar, no oracle available: …, all candidates already outreached for this project, no human outreach candidate in post.

Автоматически: отметьте 5+ эталонными, затем PATCH {"is_auto_enabled": true}.

6. Следить за результатами. Разговоры — комнаты в вашем инбоксе: API-пайплайн: управлять разговорами ваших оракулов — выключать и включать слушателя, закрывать хендофф, задавать агенду комнаты, просить оракула продолжить. performance и sends считают посты в группах, поэтому у радара они остаются нулевыми.

7. Остановить, удалить, поделиться. POST …/stop ставит на паузу (настройки и совпадения сохраняются); перед DELETE остановите. Поделиться по ссылке (индекс, «Доступ по ссылкам»): r даёт принявшему читать настройки и статус; w — ещё и менять ключевые слова и запускать / останавливать. Matches, Canonical и Evicted — воркспейсы, которыми с вами делится Cabi.Chat: ваша ссылка до них не доходит.

8. Откуда приходят совпадения. Группы, в которых радар слышит совпадения, по рангу: сначала больше совпадений, затем больше разных авторов.

GET /v0/my/campaigns/{nonce}/source_groups?days=14&limit=50
→ {"campaign": "470370000000000001", "days": 14,
   "groups": [{"nonce": "…", "handle": "tgg.example_group", "title": "…", "members": 13934,
               "matches": 41, "authors": 29, "last_seen": "…"}, …]}

Правила

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

Эндпоинт Назначение FE ИИ / оракул
POST /v0/my/campaigns Создать радар да да
GET /v0/my/campaigns, GET /v0/my/campaigns/{nonce} Список; настройки, статус, воркспейсы да да
PATCH /v0/my/campaigns/{nonce} Ключевые слова, исключения, группы, оракулы, агенда, outreach, auto да да
POST /v0/my/campaigns/{nonce}/start, /stop Запустить / пауза да да
GET /v0/my/workspaces/{matches_workspace} Читать совпадения да да
GET /v0/graph/posts/{nonce} Детали совпадения: автор, группа да да
POST /v0/search/graph/keyword с workspace Поиск внутри совпадений да да
POST / DELETE /v0/my/workspaces/{canonical}/{post} Отметить / снять эталон да да
POST /v0/my/campaigns/{nonce}/matches/evict Исключить совпадения (отрицательные примеры) да (Исключить) да
POST /v0/my/campaigns/{nonce}/matches/sweep Исключить то, что теперь отсекают исключения да да
POST /v0/my/campaigns/{nonce}/matches/{post}/draft Оракул пишет черновик первого сообщения да (Черновик обращения) собственный ИИ пользователя
POST /v0/my/campaigns/{nonce}/matches/{post}/outreach Отправить одобренный текст да (Отправить) собственный ИИ пользователя
DELETE /v0/my/campaigns/{nonce} Удалить (сначала остановить) да редко
POST /v0/my/links, GET /v0/my/links/{link}/grants Поделиться радаром; у кого доступ да да
GET /v0/my/campaigns/{nonce}/source_groups Группы, откуда приходят совпадения, по рангу нет да
POST /v0/my/campaigns/{nonce}/source_groups/workspace Сохранить рейтинг как воркспейс нет ваш токен

Упомянуто