API pipeline: Connect a Telegram account as an oracle (phone → code → 2FA), start and stop it, sign it in again when Telegram asks

Index: API pipelines — index

Goal: a Telegram account of yours works as an oracle: it answers people under its agenda and runs your campaigns. You sign it in once (phone → code → 2FA), start and stop it, and sign it in again when Telegram ends its session.

Steps

1. Request the login code. Choose a session_key (any unique string, e.g. a UUID) and reuse it in steps 1–4. api_id and api_hash come from 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. Send the code Telegram delivered to the account.

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

3. 2FA cloud password (only when asked).

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

Any step may answer {"state": "failed", "error": "…"}: start over with a new session_key.

4. Create the oracle with the same session_key, right after the last step.

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: a project you own or hold x on; it must be Pro to start: API pipeline: Make a project Pro
• agenda: what the account answers under; an agenda you own or may execute: API pipeline: Write an agenda for your oracles
• Tune later with PATCH /v0/my/oracles/{nonce}: listen_dm (true: answer direct messages, false: ignore them), gender (male | female | "", keeps grammatical gender right when the AI speaks as the account), agenda, project, title.

5. Start and stop.

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

Poll GET /v0/my/oracles/{nonce} every few seconds: ACTIVE (running, usually within a minute), FAILED (session_note says why), REAUTH_REQUIRED or PENDING (step 6). POST …/stop → {"success": true, "status": "STOPPED"}.

6. Sign in again when the status is REAUTH_REQUIRED (Telegram ended the session) or PENDING (sign-in never finished).

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: the account restarts with the new session.
• confirm_required: the account does not need it now; resend {"confirm": true} to sign in anyway (it restarts).
• phone_required: the phone is unknown; resend {"phone": "+15550000000"} (digits, international format).
• busy, flood_wait, rate_limited: retry after retry_after seconds.
• Wrong code: awaiting_code with error: "invalid_code" (no new code is sent); wrong password: awaiting_password with invalid_password.
• The re-auth session is short; once it ends: 400 re-auth session expired — start over.

Behind

• Cabi.Chat keeps what it needs to sign the account in again; deleting the oracle removes it.
• Once ACTIVE, the account answers people under its agenda and serves the campaigns it is assigned to; each answer is an AI run; its cost shows in your AI spend: API pipeline: See your AI spend. Prices: link
• Its conversations are rooms in your inbox: API pipeline: Supervise conversations your oracles hold: turn the listener off/on, clear a handoff, set a room's agenda, ask the oracle to continue
• What it did (groups, posts, campaigns, membership states): API pipeline: Create, configure, start, stop, measure and delete a Telegram campaign of any kind, section «One oracle's activity».
• Telegram may restrict an account for spam: the card then shows restricted and restricted_until.
• When its project loses Pro, the account stops.

Rules

• Telegram account oracles run only under a Pro project you own or hold x on: else start (and re-auth) → 400 Telegram account oracles need a Pro project.
• Status REAUTH_REQUIRED → start is 400 re-auth required: …; do step 6 first.
• session_key missing at create → 400 session_key is required for a telegram account; an unfinished or expired sign-in → 400 with the reason.
• Create needs Idempotency-Key; a repeat with the same key is refused, not replayed.
• start / stop need w on the oracle (404 otherwise); register, re-auth and delete are for the owner.
• DELETE /v0/my/oracles/{nonce} stops the account and removes its stored keys.

API surface