Telegram 会话登录 API:验证码、两步验证、扫码与恢复
值班群里这条工单写的是「verify-otp 失败」。访问日志并不是。POST https://api.opendata-api.com/api/project/telegram-messaging/verify-otp 返回了 HTTP 200,网关信封 code 也是 200,消息服务把请求收下了。get-session 的 status 仍是 WAITING_FOR_OTP。交上去的数字来自运营商短信,下一脚 send-message 才爆,因为会话从来没到 CONNECTED。这不是「先去控制台领一把 Key」能修好的故障:Telegram 登录里的验证码、两步验证和扫码都是等待态,要轮询,不能把「受理成功」当成「已经连通」。
打开本页或复制示例不会发起登录。你真正跑起来的请求才会,并且扣点数。登录后从控制台复制 Key,服务端用 OPENDATA_API_KEY 读;curl 里的占位符是 YOUR_API_KEY。Key 走查询参数,整段 URL 不要贴进工单。登录验证码、云密码和 sessionId 只向账号持有人收集,且只操作你拥有或已获授权的账号,不要写进日志。
会话停在 waiting_code
先读再写。群里说的 waiting_code,对应接口里的 WAITING_FOR_OTP。你会看到的状态还有 CREATED、WAITING_FOR_SCAN、CONNECTING、CONNECTED、DISCONNECTED、LOGGED_OUT、FAILED。
HTTP 状态和业务状态不在同一层。缺 Key、Key 无效、参数校验失败、传输失败,表现为 HTTP 4xx/5xx,或网关 code 不是 200——这类信封里没有登录结论,该补凭证或重试传输。消息服务常常仍回 HTTP 200,失败写在自己的 code、title、detail 里。两层都拆开再判断。verify-otp / submit-password 的 200 只表示受理。验证码和密码是异步处理的,真正的裁决是下一跳 status,或者 twoFactorRequired。
诊断用读接口,不要再交一次码:
curl --get 'https://api.opendata-api.com/api/project/telegram-messaging/get-session' \
--data-urlencode 'key=YOUR_API_KEY' \
--data-urlencode 'sessionId=YOUR_SESSION_ID'
按读到的字段分叉:不是 WAITING_FOR_OTP,verify-otp 完不成登录,多半还在创建,或根本不是手机号模式。twoFactorRequired 为 true,说明验证码已经过了,账号在等云密码,再交一遍码没有用。FAILED / LOGGED_OUT 就停,别对着一个死会话空转;要么新建,要么用已保存的登录恢复。账号已保存但当前离线时,get-session 可能顺手重连,这不是新的验证码流程。验证码在该账号的 Telegram 应用内,不在短信箱——已在别的设备登录过的账号尤其如此,短信箱空着并不代表流程卡住。同一号码在第一个会话还停在 WAITING_FOR_OTP 时再 create-session,会留下两个等待态、一份验证码,值班会把码交到错误的 sessionId 上。
先用手机号建会话
手机号模式从 create-session 起。业务 JSON 要先序列化,再作为字符串放进 body。phoneNumber 是带国家区号、以 + 开头的完整号码。deviceName 会出现在该账号的设备列表里,写成值班能认出来的名字。
curl -X POST 'https://api.opendata-api.com/api/project/telegram-messaging/create-session?key=YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"body":"{\"mode\":\"phone\",\"phoneNumber\":\"+15551234567\",\"deviceName\":\"My Bot\"}"}'
新会话的标识是最内层的 id,原始 JSON 里是 data.data.id。后面每次调用都把它当查询参数 sessionId,不要跟请求体里恢复模式用的字段名混用。+15551234567 只是文档里的形态示例,不保证对应真实账号。号码缺 +、少国家区号,看起来像业务失败,其实是入参没过校验——先改号码再谈等待态。
状态到 WAITING_FOR_OTP 之前,不要向任何人要验证码。生产里用一个拆两层信封的辅助函数就够:网关和内层把 200、201、202、204 当成功,其余带着完整响应体失败;FAILED / LOGGED_OUT 立刻停,不要睡到 HTTP 超时。
import json
import os
import time
import requests
API_KEY = os.environ["OPENDATA_API_KEY"].strip()
BASE = "https://api.opendata-api.com/api/project/telegram-messaging"
OK = {200, 201, 202, 204}
def call(method, operation, payload=None, **params):
params["key"] = API_KEY
kwargs = {"params": params, "timeout": 60}
if payload is not None:
kwargs["json"] = {"body": json.dumps(payload)}
resp = requests.request(method, f"{BASE}/{operation}", **kwargs)
if not resp.ok:
raise RuntimeError(f"{operation} HTTP {resp.status_code} {resp.text}")
body = resp.json()
while isinstance(body, dict) and "code" in body:
if body["code"] not in OK:
raise RuntimeError(f"{operation} failed: {body}")
body = body.get("data")
return body
def wait_for(session_id, wanted, timeout=120, stop_on_2fa=False):
deadline = time.time() + timeout
while time.time() < deadline:
state = call("GET", "get-session", sessionId=session_id)
status = state.get("status")
if status in wanted or (stop_on_2fa and state.get("twoFactorRequired")):
return state
if status in ("FAILED", "LOGGED_OUT"):
raise RuntimeError(f"login ended with status {status}")
time.sleep(2)
raise TimeoutError("session did not reach the expected status")
get-session 还会带回登录方式和手机号;等待期间可能带 qrImage 或 twoFactorRequired。
提交验证码,必要时再交 2FA
verify-otp 只在 WAITING_FOR_OTP 时有效。把应用里的登录码交上去。立刻返回的响应不是连通,验证码也不要落盘。
然后再轮询:要么 CONNECTED,要么 twoFactorRequired=true 且状态仍是 WAITING_FOR_OTP。后者对开了云密码的账号是正常路径,不是传输故障。
submit-password 只在 twoFactorRequired 为 true 时有效:手机号模式出现在验证码之后,扫码模式出现在扫码之后。同样先受理、再轮询到 CONNECTED。
import getpass
session = call("POST", "create-session",
{"mode": "phone", "phoneNumber": "+15551234567", "deviceName": "My Bot"})
session_id = (session or {}).get("id")
if not session_id:
raise RuntimeError(f"no session id: {session}")
wait_for(session_id, {"WAITING_FOR_OTP"})
code = input("Login code from the Telegram app: ").strip()
call("POST", "verify-otp", {"code": code}, sessionId=session_id)
state = wait_for(session_id, {"CONNECTED"}, stop_on_2fa=True)
if state.get("status") != "CONNECTED":
password = getpass.getpass("Telegram cloud password: ")
call("POST", "submit-password", {"password": password}, sessionId=session_id)
state = wait_for(session_id, {"CONNECTED"}, timeout=60)
print("status:", state.get("status"))
print("store this id for restore:", state.get("id", session_id))
产品里在自己的 HTTPS 界面收验证码和密码,转发一次就丢掉,不要写进访问日志或工单附件。到 CONNECTED 之后,用 get-account 核对连上的究竟是哪个账号,避免把客户会话接到值班自己的号上。这时 get-session 返回的 id 会变成按账号派生的稳定值,原来的 id 和稳定 id 都还能用,把稳定 id 存进密钥库,后面恢复靠它。
扫码、恢复和退出,别留下孤儿会话
不方便收验证码时改用 qr 模式创建,带上 deviceName。创建响应里有 qrPageUrl;要在自己的界面画码,就轮询 get-session 的 qrImage(base64 数据 URI)。等待时状态是 WAITING_FOR_SCAN,这时去打 verify-otp 会失败,因为扫码模式根本不走手机验证码。持有人在手机上打开 Telegram → 设置 → 设备 → 链接桌面设备,扫码即可。有云密码的,扫完同样走 submit-password,不要把扫码后的等待当成二维码过期。
curl -X POST 'https://api.opendata-api.com/api/project/telegram-messaging/create-session?key=YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"body":"{\"mode\":\"qr\",\"deviceName\":\"My Bot\"}"}'
进程重启不必再要一次验证码。create-session 的 restore 模式在 JSON 字段 sessionId 里传入上次的 id,用已保存的登录重连。恢复成功也会清空收件箱和会话列表的缓存,别把缓存空当成登录丢了;登录还在,只是本地观察窗口被清过。
curl -X POST 'https://api.opendata-api.com/api/project/telegram-messaging/create-session?key=YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"body":"{\"mode\":\"restore\",\"sessionId\":\"PREVIOUS_SESSION_ID\"}"}'
disconnect-session 是 DELETE。默认 logout=false 只断开实时连接、保留已保存的登录,之后还能恢复。logout=true 会远程退出 Telegram 并删掉已保存的登录,下次必须重新验证码或扫码。孤儿会话就是:已经 CONNECTED 却没把 id 存下来,或者本想断开却带了 logout=true。
curl -X DELETE 'https://api.opendata-api.com/api/project/telegram-messaging/disconnect-session?key=YOUR_API_KEY&sessionId=YOUR_SESSION_ID&logout=false'
连通之后的收发,看用 Python 发送和读取 Telegram 消息。只查号码或用户名在不在,用不需要建会话的 Telegram 号码检测。接口页:create-session、verify-otp、submit-password、get-session、disconnect-session。产品页:Telegram Messaging。费用见定价。
会把会话一直卡住的失误:拿短信当登录码;在 CREATED / CONNECTING 时打 verify-otp;把异步 200 当成 CONNECTED;看见 twoFactorRequired 却还在重交验证码;把验证码、云密码、sessionId 打进日志;把带 Key 的查询 URL 贴进工单;对还要恢复的会话下 logout=true;同一号码并行开两个手机号会话。只操作已授权账号,并遵守 Telegram 服务条款。