Telegram 发消息 API(Python):先选文本、媒体、收件箱还是历史
| 你要做的 | 调 | 不要误用成 |
|---|---|---|
| 给用户名、手机号或收藏夹发一句话 | send-message | 没有文件字段;收件箱和历史都不会替你发出去 |
| 图片、视频、语音或文档 | send-media | base64 的 data 加 type;文本接口带不走字节 |
| 本会话在线期间收到的新消息 | list-inbox | 滚动窗口最多 500 条、倒序、不含自己发出的,重启就清空 |
| 某个对象更早的消息,直接从 Telegram 取 | chat-history | 必须带 peer;不是实时流 |
| 确认对方解析得出来 | check-exists | 发到不存在的 handle 照样扣一次发送;这也不是免会话的号码检测 |
选错行比写错字段更常见。Telegram Messaging 里这五件事共用同一把已授权的平台 Key、同一个已登录个人会话,但请求形状完全不同:有的走 to+text,有的走 data,有的只读、连 body 都没有。先对上动作,再写 JSON。
登录后从控制台复制 Key。Python 读环境变量 OPENDATA_API_KEY,curl 示例里写成 YOUR_API_KEY。Key 和 sessionId 都挂在查询串上,整段 URL 不要进工单、截图、浏览器前端。打开本页、复制代码块本身不会发消息;真正执行命令才会,并且扣点数。只操作你拥有或已获授权的账号。
先选聊天动作再组 payload
统一前缀是 https://api.opendata-api.com/api/project/telegram-messaging/<operation>。读操作用 GET,其余查询字段直接拼在 URL 上;写操作用 POST / PUT,操作 JSON 必须先 json.dumps 成字符串,再放进外层的 body。漏掉这一层,网关会当参数校验失败,消息服务根本收不到 to。
这套目录没有 Bot Token。发件人是已经登录的个人号,身份凭证就是 sessionId。Bot API 那套 chat_id、parse_mode 原样塞进来没有对应字段。
本文也不负责把会话变成 CONNECTED。创建、轮询验证码、恢复、断开,走 Telegram 登录验证码手册。这里默认 get-session 已经是 CONNECTED;若还停在 WAITING_FOR_OTP、DISCONNECTED、FAILED,先别组 text。它也不是 WhatsApp 发送:项目 id、设备绑定、收件人规则都不一样。如果根本不打算发、只想问号码或用户名在不在,用免会话的 Telegram 号码检测,那边不吃 sessionId,也更便宜。
两层状态要分开看。缺 Key、Key 无效、点数不够、传输断开,表现为 HTTP 4xx/5xx,或网关信封里的 code 不是 200——这里面没有「这条消息发出去没有」的结论。平台 401 是凭证问题,403 是点数或账户未启用。消息服务经常仍回 HTTP 200,把拒绝写在内层的 code、title、detail。外层 200 不等于发出去了。
import json
import os
import requests
API_KEY = os.environ["OPENDATA_API_KEY"].strip()
SESSION_ID = os.environ["TELEGRAM_SESSION_ID"].strip()
BASE = "https://api.opendata-api.com/api/project/telegram-messaging"
OK = {200, 201, 202, 204}
def call(method, operation, payload=None, **params):
"""Return the innermost payload. POST JSON goes in a string `body` field."""
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} failed: HTTP {resp.status_code}")
body = resp.json()
# Peel {"code": 200, "data": {"code": 201, "data": ...}}; inner 200 is not enough
while isinstance(body, dict) and "code" in body:
if body["code"] not in OK:
raise RuntimeError(f"{operation} failed: inspect redacted diagnostics")
body = body.get("data")
return body
发之前想确认「现在连的到底是哪个号」,用 get-account。它只读数字 ID、手机号、用户名、姓名、是不是 Bot,不会发出任何消息。
文本是应该先跑通的发送
第一次不要发给真人。to 写成 me,消息进自己的收藏夹(Saved Messages),用来验证信封、查询串和内层 sent 是否对得上。下面的用户名和号码只是文档形态,不保证真实在网。
# Documented shape only — running it spends credits and requires a CONNECTED session.
curl -X POST 'https://api.opendata-api.com/api/project/telegram-messaging/send-message?key=YOUR_API_KEY&sessionId=YOUR_SESSION_ID' \
-H 'Content-Type: application/json' \
-d '{"body":"{\"to\":\"me\",\"text\":\"Hello from the API\"}"}'
to 接受三种常见写法:@用户名(也可以不带 @)、完整国际格式的 +手机号、以及 me。纯数字用户 ID 只有这个账号已经认识对方时才有效,冷启动不要用。内层成功会带回 to、text、sent——这只说明这一次调用被消息服务接受,不是幂等凭证。超时后再 POST 同一段文字,可能变成两条。
call(
"POST",
"send-message",
{"to": "@some_username", "text": "Your order has shipped."},
sessionId=SESSION_ID,
)
call(
"POST",
"send-message",
{"to": "+15551234567", "text": "Hi, this is Anna from support."},
sessionId=SESSION_ID,
)
handle 解析失败也会扣一次发送费。批量名单应先走 check-exists:命中带 exists 以及 ID、用户名、显示名;解析不到是 exists=false 加 reason。每个收件人校验一次、自己缓存。requests 会给加号做百分号编码;手拼 URL 时必须写成 %2B,否则 + 被当成空格,看起来像号码写错。
info = call("GET", "check-exists", sessionId=SESSION_ID, peer="+15551234567")
if not info.get("exists"):
raise RuntimeError("peer did not resolve; skip send")
发送抛错时,先 GET get-session。离线但登录还在,这次读取可能顺手重连;登录已经没了,是创建/恢复问题,改 payload 解决不了。
媒体、历史和收件箱是另一扇门
传文件不要去改 send-message。send-media 的 type 只能是 image、video、audio、voice、document 之一,文件本体放 data(base64)。caption、fileName、mimeType 可选。体积一大,请求体跟着涨,超时设太短常见的结果是传了一半、内层报错、点数却可能已经记上。to 的规则与文本相同。
import base64
with open("invoice.pdf", "rb") as fh:
encoded = base64.b64encode(fh.read()).decode("ascii")
call(
"POST",
"send-media",
{
"to": "@some_username",
"type": "document",
"data": encoded,
"fileName": "invoice.pdf",
"caption": "Invoice for October",
},
sessionId=SESSION_ID,
)
「刚收到的」和「以前聊过的」不是同一个接口。list-inbox 只覆盖本会话在线期间进来的消息:倒序、不含自己发出的、默认 limit 50、每个会话最多留 500 条,进程重启就清空。字段里有 id、chatJid、发送者、类型、文本、时间戳。正确用法是短间隔轮询、按 id 去重、要留的立刻写入自己的库。chatJid 形如 user:<id> / chat:<id> / channel:<id>,后面拉历史、标已读、管群都可以直接用。
chat-history 必须指定一个 peer,直接向 Telegram 要最近若干条,包括进程启动之前的,倒序,默认 limit 20。peer 可以是 @用户名、+手机号、me,也可以是收件箱或 list-chats 里拿到的带类型 id。list-chats 只反映会话连上之后观察到的对话,不是完整通讯录归档。
inbox = call("GET", "list-inbox", sessionId=SESSION_ID, limit=50) or []
history = call(
"GET",
"chat-history",
sessionId=SESSION_ID,
peer="@some_username",
limit=50,
)
改字、表情回应、撤回都要先从上面两扇门拿到数字 messageId。只能改自己发出的。revoke-message 是对所有人删除;react-message 的 emoji 传空字符串表示取消自己的回应。这些是后续写操作,不是第五种发送入口。
发送端仍然不该自动做的事
不要拿这套接口去换 Bot Token,也不要在发送失败时立刻再走一遍登录——先读 get-session。
send-message 和 send-media 没有幂等键。超时后先对该 peer 拉 chat-history,看有没有自己的文本或 fromMe,再决定要不要 POST 同一份内容。不要把 list-inbox 当数据库,也不要按历史接口的方式去翻页:五百条上限、仅本会话、重启即无。不要把手机号丢进 chat-history 却以为在盯实时收件箱;也不要因为文本接口「好像能带路径」就绕开 send-media 传文件。
不要给很多人发完全相同的文案,也不要给没预期会收到你消息的人发。未经许可的群发违反 Telegram 条款,账号可能被限制,各地隐私与反垃圾规则同样适用。手机号是个人信息。sessionId 等于这个号的操作权,放环境变量或密钥库,不要进仓库。disconnect-session 默认只断连接、保留已保存的登录;logout=true 会远程退出。
群、频道管理挂在同一会话上,但替不了表里那四行发送/读取。会话不是 CONNECTED,这张选择表没有可选的——回到登录手册。