API-пайплайн: подключить Telegram-аккаунт как оракула (телефон → код → 2FA), запускать и останавливать его, входить заново, когда просит Telegram

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

Цель: ваш Telegram-аккаунт работает как оракул: отвечает людям по своей агенде и ведёт ваши кампании. Вы один раз входите в него (телефон → код → 2FA), запускаете и останавливаете его и входите заново, когда Telegram завершает сессию.

Шаги

1. Запросите код входа. Выберите session_key (любая уникальная строка, например UUID) и используйте её в шагах 1–4. api_id и api_hash берутся на my.telegram.org.

POST /v0/my/oracles/register
{"step": "start", "session_key": "3f6c…", "phone": "+15550000000",
 "api_id": "12345678", "api_hash": "0123abcd…"}
→ {"session_key": "3f6c…", "state": "awaiting_code"}

2. Отправьте код, который Telegram прислал на аккаунт.

POST /v0/my/oracles/register
{"step": "code", "session_key": "3f6c…", "code": "12345"}
→ {"session_key": "3f6c…", "state": "awaiting_password"}   2FA is on: step 3
→ {"session_key": "3f6c…", "state": "authorized"}          no 2FA: step 4

awaiting_password: включена 2FA, шаг 3; authorized: 2FA нет, шаг 4.

3. Облачный пароль 2FA (только если просят).

POST /v0/my/oracles/register
{"step": "password", "session_key": "3f6c…", "password": "…"}
→ {"session_key": "3f6c…", "state": "authorized"}

Любой шаг может ответить {"state": "failed", "error": "…"}: начните заново с новым session_key.

4. Создайте оракула с тем же session_key сразу после последнего шага.

POST /v0/my/oracles
Idempotency-Key: oracle-anna-1
{"kind": "mtproto_account", "title": "Anna", "session_key": "3f6c…",
 "project": "<your Pro project>", "agenda": "<agenda nonce>"}
→ {"nonce": "470000000000000001", "card_type": "oracle", "kind": "mtproto_account",
   "status": "STOPPED", "phone_masked": "+15•••••••00", …}

• project: проект, которым вы владеете или на который у вас есть x; для запуска он должен быть Pro: API-пайплайн: подключить Pro для проекта
• agenda: по чему отвечает аккаунт; агенда, которой вы владеете или которую можете выполнять: API-пайплайн: написать агенду для своих оракулов
• Настраивается позже через PATCH /v0/my/oracles/{nonce}: listen_dm (true: отвечать на личные сообщения, false: игнорировать их), gender (male | female | "", чтобы ИИ правильно согласовывал род, говоря от имени аккаунта), agenda, project, title.

5. Запуск и остановка.

POST /v0/my/oracles/470000000000000001/start
→ {"success": true, "status": "STARTING"}

Опрашивайте GET /v0/my/oracles/{nonce} раз в несколько секунд: ACTIVE (работает, обычно в течение минуты), FAILED (session_note объясняет почему), REAUTH_REQUIRED или PENDING (шаг 6). POST …/stop → {"success": true, "status": "STOPPED"}.

6. Войти заново, когда статус REAUTH_REQUIRED (Telegram завершил сессию) или PENDING (вход не был завершён).

POST /v0/my/oracles/{nonce}/reauth/start      {}
→ {"session_key": "9a1b…", "state": "awaiting_code", "phone_masked": "+15•••••••00", "status": "REAUTH_REQUIRED"}
POST /v0/my/oracles/{nonce}/reauth/code       {"session_key": "9a1b…", "code": "12345"}
→ {"state": "awaiting_password", …}  or  {"state": "complete", …}
POST /v0/my/oracles/{nonce}/reauth/password   {"session_key": "9a1b…", "password": "…"}
→ {"state": "complete", "status": "…"}

• complete: аккаунт перезапускается с новой сессией.
• confirm_required: аккаунту сейчас это не нужно; повторите с {"confirm": true}, чтобы всё равно войти (он перезапустится).
• phone_required: телефон неизвестен; повторите с {"phone": "+15550000000"} (цифры, международный формат).
• busy, flood_wait, rate_limited: повторите через retry_after секунд.
• Неверный код: awaiting_code с error: "invalid_code" (новый код не отправляется); неверный пароль: awaiting_password с invalid_password.
• Сессия повторного входа короткая; когда она закончится: 400 re-auth session expired — start over.

За кадром

• Cabi.Chat хранит то, что нужно для повторного входа в аккаунт; удаление оракула это удаляет.
• В статусе ACTIVE аккаунт отвечает людям по своей агенде и обслуживает назначенные ему кампании; каждый ответ — запуск ИИ; его стоимость видна в ваших расходах на ИИ: API-пайплайн: ваши расходы на ИИ. Цены: link
• Его разговоры — комнаты в вашем инбоксе: API-пайплайн: управлять разговорами ваших оракулов — выключать и включать слушателя, закрывать хендофф, задавать агенду комнаты, просить оракула продолжить
• Что он сделал (группы, посты, кампании, статусы членства): API-пайплайн: создать, настроить, запустить, остановить, измерить и удалить Telegram-кампанию любого вида, раздел «Активность одного оракула».
• Telegram может ограничить аккаунт за спам: тогда на карточке видны restricted и restricted_until.
• Когда проект теряет Pro, аккаунт останавливается.

Правила

• Оракулы на Telegram-аккаунтах работают только под Pro-проектом, которым вы владеете или на который у вас есть x: иначе запуск (и повторный вход) → 400 Telegram account oracles need a Pro project.
• Статус REAUTH_REQUIRED → запуск отвечает 400 re-auth required: …; сначала сделайте шаг 6.
• Нет session_key при создании → 400 session_key is required for a telegram account; незавершённый или истёкший вход → 400 с причиной.
• Создание требует Idempotency-Key; повтор с тем же ключом отклоняется, а не воспроизводится.
• start / stop требуют w на оракула (иначе 404); register, повторный вход и удаление — для владельца.
• DELETE /v0/my/oracles/{nonce} останавливает аккаунт и удаляет его сохранённые ключи.

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