Telegram 用户号消息 API

创建授权用户账号会话，并取得其他接口所需的 sessionId。手机号模式提交 mode=phone 与完整国际号码 phoneNumber，随后轮询状态并提交 Telegram 应用内登录码；启用两步验证的账号还需提交云密码。二维码模式提交 mode=qr，打开 qrPageUrl 或查看 qrImage，在 Telegram 设置 → 设备 → 连接桌面设备中扫码。恢复模式提交 mode=restore 与已有 sessionId。登录完成后保留返回的稳定 sessionId。可通过 proxy 指定 SOCKS5 连接地址。

查询 CREATED、WAITING_FOR_SCAN、WAITING_FOR_OTP、CONNECTING、CONNECTED、DISCONNECTED、LOGGED_OUT 或 FAILED 等会话状态。登录期间可返回 qrImage 和 twoFactorRequired；保存过登录状态的离线会话可在查询时重新连接。创建会话后持续轮询，直到 CONNECTED 再调用消息接口。

默认仅断开会话连接，保留登录状态供以后恢复。传入 logout=true 会同时退出 Telegram 登录并删除保存的登录状态，之后必须重新扫码或提交登录码。

仅在 WAITING_FOR_OTP 状态下使用。通过 JSON 请求体的 code 提交 Telegram 应用内收到的登录码（不是短信码）。请求受理后轮询会话状态；若 twoFactorRequired=true，继续调用提交两步验证密码接口。

仅在 twoFactorRequired=true 时使用，通过 JSON 请求体的 password 提交 Telegram 云密码。适用于手机号验证码验证之后或二维码扫描之后。请求受理后继续轮询，直到状态为 CONNECTED。

从已登录会话发送文本，JSON 请求体包含 to 与 text。to 支持 @username、普通用户名、带 + 的完整国际手机号，或 me（自己的收藏夹）。未带 + 的号码可作为后备格式；纯数字用户 ID 仅适用于账号已识别的对象。发送前确保会话为 CONNECTED。

JSON 请求体包含 to、type 与文件的 base64 内容 data。type 支持 image、video、audio、voice、document；可选 fileName、caption 与 mimeType。收件人格式与文本消息相同，需使用已连接会话。

返回会话连接期间收到的消息，按最新优先排序，不包含账号自己发送的消息。每项含 id、chatJid、sender、type、text、timestamp。仅保留最近 500 条，服务重启后可能不可用；使用 limit 限制返回数量，不应把此接口当作永久归档。

通过 JSON 请求体传入 peer 和可选 maxId。peer 支持 @username、+phone、me，或响应中的 user:<id>、chat:<id>、channel:<id>。提供 maxId 可标记到指定消息；省略时标记到最新消息。

JSON 请求体包含 peer、目标消息的数字 messageId 与 emoji。messageId 可来自聊天记录或收件箱；发送空字符串 emoji 可清除自己的已有回应。

JSON 请求体包含 peer、已发送消息的数字 messageId 与新的 text。只能编辑当前会话账号自己发送的消息。

通过 peer 与数字 messageId 删除目标消息。可撤回当前账号发送的消息，或在具备权限时用于群组管理。删除会影响其他参与者，请确认目标后调用。

返回会话连接以来观察到的聊天，按最近活动排序。每项包含 jid（user:<id>、chat:<id> 或 channel:<id>）、已知名称与最后活动时间。该列表不是永久记录，重启后可能不可用；可用于发现其他接口需要的 peer 标识。

查询指定 peer 的最近消息，按最新优先返回。peer 支持 @username、+phone、me 或带类型的对象标识。每条包含数字 id、chatJid、sender、fromMe、type、text 与 timestamp。limit 默认 20，可调整返回数量。

提供 sessionId、peer 与聊天记录中的数字 messageId，下载目标消息的图片或文档附件。响应包含 base64 文件内容与 MIME 类型。

返回会话关联账号的数字用户 ID、手机号、用户名、姓名与是否为 bot。发送前可用此接口核对实际登录的账号。

JSON 请求体支持 firstName、lastName、about，至少提供一项；只修改传入字段。变化会反映到其他人可见的 Telegram 资料。

返回账号已保存的联系人，每项包含数字 id、username、姓名与 phone。用于授权联系人管理或收件人选择，遵守用户隐私与 Telegram 使用规则。

解析 peer 并返回 exists。peer 可为 @username、+phone 或 user:<id>、chat:<id>、channel:<id>。成功时可返回 id、username 与名称；无法解析时返回 exists=false 及原因。可在发送前检查收件人，但解析失败不应视为绝对不存在。

传入 peer（@username 或 +phone），通过已连接会话查询用户 About 简介。用户未设置简介或隐私权限不允许时结果为空。

通过已连接会话查询 peer（@username 或 +phone）的头像，返回 base64 文件内容与 MIME 类型。无可用头像时返回 exists=false，结果受对象隐私设置影响。

JSON 请求体包含 name 与 participants（可解析为用户的 peer 字符串数组，如 @username 或完整国际号码）。创建基础群组并返回群组标识，用于后续管理。仅添加获得授权或同意的成员。

返回已连接账号所属的基础群组、超级群组与频道。每项包含 jid、name、type，基础群组还可包含成员数量。基础群组使用 chat:<id>，超级群组与频道使用 channel:<id>。

JSON 请求体的 link 支持完整邀请链接（https://t.me/+… 或 https://t.me/joinchat/…）或邀请码。成功后返回已加入对象的 peer。仅加入账号获准访问的群组或频道。

通过 sessionId 与 peer 查询 name、about、type 和成员数量。peer 可来自群组列表中的 chat:<id> 或 channel:<id>，也可使用可解析的 @username。

JSON 请求体包含 name 和/或 topic（简介），至少提供一项。只修改传入字段；账号必须具备相应群组或频道管理权限。

JSON 请求体的 participants 是可解析为用户的 peer 字符串数组。将一个或多个已同意加入的用户添加到群组或频道，并返回添加数量。需要相应管理权限。

JSON 请求体的 participants 指定待移除用户数组，返回移除数量。账号需具备群组或频道的相应管理权限。调用会影响用户访问，请确认目标。

仅适用于超级群组与频道（channel:<id>）。JSON 请求体包含 participants 与 action（promote 或 demote）。返回执行动作与更新数量；账号需要相应管理权限。

提供 sessionId 与 peer，导出新的 t.me 邀请链接。账号需要相应群组或频道管理权限；谨慎分发链接以控制访问范围。

提供 sessionId 与 peer，通过无需请求体的 POST 让当前账号退出群组或频道。响应确认已退出的对象。调用前确认账号不再需要该社区访问权限。