Pipeline de API: conectar una cuenta de Telegram como oráculo (teléfono → código → 2FA), iniciarla y detenerla, y volver a iniciar sesión cuando Telegram lo pida

Índice: Pipelines de API — índice

Objetivo: una cuenta de Telegram tuya trabaja como oráculo: responde a las personas según su agenda y lleva tus campañas. Inicias sesión una vez (teléfono → código → 2FA), la inicias y la detienes, y vuelves a iniciar sesión cuando Telegram cierra su sesión.

Pasos

1. Pide el código de acceso. Elige un session_key (cualquier cadena única, p. ej. un UUID) y reutilízalo en los pasos 1–4. api_id y api_hash se obtienen en 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. Envía el código que Telegram mandó a la cuenta.

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: la 2FA está activada, paso 3; authorized: sin 2FA, paso 4.

3. Contraseña en la nube de 2FA (solo si se pide).

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

Cualquier paso puede responder {"state": "failed", "error": "…"}: empieza de nuevo con otro session_key.

4. Crea el oráculo con el mismo session_key, justo después del último paso.

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", …}

5. Iniciar y detener.

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

Consulta GET /v0/my/oracles/{nonce} cada pocos segundos: ACTIVE (en marcha, normalmente en menos de un minuto), FAILED (session_note dice por qué), REAUTH_REQUIRED o PENDING (paso 6). POST …/stop → {"success": true, "status": "STOPPED"}.

6. Volver a iniciar sesión cuando el estado es REAUTH_REQUIRED (Telegram cerró la sesión) o PENDING (el inicio de sesión no terminó).

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": "…"}

En segundo plano

Reglas

Superficie de la API

Endpoint Para qué FE IA / oráculo
POST /v0/my/oracles/register Pasos de inicio de sesión: start, code, password sí la IA propia del usuario, con la persona presente
POST /v0/my/oracles Crear el oráculo tras un inicio de sesión completo sí sí
GET /v0/my/oracles, GET /v0/my/oracles/{nonce} Lista; estado, session_note, restricción sí sí
PATCH /v0/my/oracles/{nonce} Agenda, proyecto, listen_dm, gender, texto sí sí
POST /v0/my/oracles/{nonce}/start, /stop Iniciar / detener sí sí
POST /v0/my/oracles/{nonce}/reauth/start, /code, /password Volver a iniciar sesión sí la IA propia del usuario, con la persona presente
DELETE /v0/my/oracles/{nonce} Detener y eliminar sí rara vez

Mentioned