Telegram 发消息 API(Python):先选文本、媒体、收件箱还是历史

发布于 2026年10月9日 · 更新于2026年10月16日

你要做的调不要误用成
给用户名、手机号或收藏夹发一句话send-message没有文件字段;收件箱和历史都不会替你发出去
图片、视频、语音或文档send-mediabase64 的 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,这张选择表没有可选的——回到登录手册。