获取当前登录账号的信息（用户名、ID、手机号等）。

修改自己的名字 / 姓氏 / 个人简介。留空的字段保持不变。

设置或清空自己的 @username（传空字符串表示清空）。

列出通讯录里的所有 Telegram 联系人。

按关键词搜索联系人、已加入的对话，以及公开的用户/群/频道。

把某人加进通讯录。

已经能看到的人：传 user（@username 或 ID）。 只有电话号码：传 phone + first_name，会用号码导入。

Args: user: 目标用户的 @username 或 ID。 first_name: 备注名（必填，会显示在通讯录里）。 last_name: 备注姓。 phone: 只知道号码时用，带国家码。 share_my_phone: 是否把自己的号码也分享给对方。

把某人从通讯录里删掉（不影响聊天记录）。

拉黑 / 取消拉黑一个用户或 bot。

列出黑名单里的用户。

新建一个群。

Args: title: 群名。 users: 初始成员（@username 或 ID）；超级群可以给空列表。 megagroup: True 建超级群（推荐，支持话题/管理日志等）；False 建旧式小群。 about: 群简介，仅超级群支持。

新建一个广播频道。

把若干人拉进群 / 频道。

把某人移出群（之后他还能再次加入）。

封禁 / 解封群成员（封禁 = 踢出且不能再加入）。

Args: chat: 群 / 频道。 user: 目标用户。 until: 封到什么时候，如 +7d；留空为永久。 unban: True 则解除封禁。

限制某个成员的权限（禁言等）。各布尔值为 True 表示"允许"。

Args: chat: 群。 user: 目标用户。 until: 限制到什么时候，如 +1d；留空为永久。 send_messages: 允许发消息（False 即禁言）。 send_media: 允许发媒体。 send_stickers: 允许发贴纸。 send_polls: 允许发起投票。 embed_links: 允许链接预览。 invite_users: 允许拉人。 pin_messages: 允许置顶。 change_info: 允许改群信息。

设置全群的默认权限（不传 user，作用于所有普通成员）。

把某人提升为管理员，或撤销其管理员身份（demote=True）。

Args: chat: 群 / 频道。 user: 目标用户。 title: 自定义头衔。 demote: True 则撤销全部管理员权限。 change_info: 改群信息。 delete_messages: 删他人消息。 ban_users: 封禁成员。 invite_users: 邀请成员。 pin_messages: 置顶消息。 add_admins: 能再任命管理员。 post_messages: 频道发帖权限。 edit_messages: 频道编辑他人帖子权限。 manage_call: 管理语音聊天。 anonymous: 匿名管理员。

修改群 / 频道的名字。

修改群 / 频道的简介。

把本地图片设为群 / 频道头像。

为群 / 频道生成一条邀请链接。

Args: chat: 群 / 频道。 title: 链接备注名。 expires_at: 过期时间，如 +7d / ISO8601；留空为不过期。 usage_limit: 最多可用多少次，0 为不限。 request_needed: True 则通过链接进来的人需要管理员批准。

读取群 / 频道的管理操作日志（需要管理员权限）。

在话题群里新建一个话题。

改话题的标题，或开关 / 隐藏一个话题。

设置超级群的慢速模式间隔（0 关闭；可选 10/30/60/300/900/3600 秒）。

删除自己创建的群 / 频道（对所有成员生效，不可恢复，必须 confirm=True）。

获取一个 bot 公开的 / 指令菜单和简介（对应聊天框里 / 触发的下拉）。

Args: bot: bot 的 @username 或用户 ID。

给一个 bot 发 /start（可带启动参数），并等它的第一条回复。

Args: bot: bot 的 @username 或 ID。 start_param: deep link 里的启动参数（t.me/xxx?start=PARAM 的 PARAM）。 wait_seconds: 等回复多少秒，0 表示不等。

点击某条消息附带的 inline 按钮（callback 类型）。

定位按钮的三种方式，至少提供一个：

• data: 按钮的 callback data（UTF-8 字符串，最常见，如 "confirm:42"）；

• data_hex: callback data 的十六进制字节串，用于二进制数据；

• text: 按钮显示的文字（同一消息里必须唯一）。

Args: chat: 消息所在对话。 message_id: 带 inline 按钮的消息 ID。 data: 按钮 callback data 的 UTF-8 文本。 data_hex: 按钮 callback data 的十六进制表示。 text: 按钮显示的文字。

Returns: bot 返回的响应：message(弹窗文字)、alert(True 为强制 alert)、 url(有则为跳转链接)、cache_time(客户端缓存秒数)。

按下"回复键盘"上的一个按钮 —— 本质是发送对应文字给对话。

Args: chat: 对话。 text: 按钮上的文字（也就是要发送的文本）。 reference_message_id: 可选。若提供，会先校验该消息附带的回复键盘里 确实存在这个按钮，避免误发。

向一个 bot 发 inline 查询（相当于在输入框打 @bot 关键词），可直接发送某个结果。

Args: bot: bot 的 @username 或 ID。 query: 查询词。 limit: 最多列出几条结果。 send_to: 给了就把选中的结果发到这个对话；留空只列出结果不发送。 result_index: 要发送第几条结果（从 0 开始）。 reply_to: 发送时回复某条消息。

把若干条消息转发给 @QuotLyBot，生成引用贴纸并返回结果。

注意：被转发的消息内容会发送到第三方 bot (QuotLyBot) 的服务器上渲染。

Args: chat: 源消息所在对话。 message_ids: 要做成贴纸的消息 ID（同一对话，可多条组成对话截图）。 download: True 则把生成的 .webp 下载到本地。 timeout_seconds: 等待 bot 回复的秒数。

列出最近的对话（聊天列表）。

Args: limit: 返回条数上限，最多 500。 archived: True 则读取归档文件夹。 kind: 只保留某一类对话。 unread_only: 只返回有未读消息的对话。 query: 按对话名字过滤（不区分大小写）。

获取某个对话的详细信息（简介、成员数、置顶消息 ID、权限等）。

列出群 / 频道成员（需要有查看成员的权限）。

Args: chat: 群组或频道。 limit: 上限，最多 500。 search: 按姓名/用户名过滤。 filter_by: 只看管理员 / bot / 被限制 / 被踢的人。

列出自己和某个用户共同所在的群 / 频道。

列出聊天文件夹（Telegram 的 Chat Folders / dialog filters）及其包含的对话。

把对话移入归档文件夹，或移出来。

把对话在聊天列表里置顶 / 取消置顶。

开启 / 关闭一个对话的免打扰。

Args: chat: 对话。 minutes: 静音多少分钟；0 表示永久静音（直到手动取消）。 unmute: True 则取消静音。

把对话标记成"未读"小圆点（或清掉这个标记）。

加入一个公开群/频道，或通过邀请链接(t.me/+xxxx)加入。

退出群 / 频道，或删除与某人的私聊对话。

Args: chat: 对话。 delete_history: 退出的同时清空本地这份历史（不为对方删除）。

发送本地文件（图片/视频/文档均可）。

Args: chat: 目标对话。 path: 本地文件绝对路径。 caption: 附带说明文字。 as_document: True 则强制作为文件发送，不压缩为图片/视频。 reply_to: 要回复的消息 ID。 as_voice: 作为语音消息发送（需要 ogg/opus 音频）。 as_video_note: 作为圆形视频消息发送（需要方形短视频）。 silent: 静默发送。 schedule_at: 定时发送，如 +30m / ISO8601 / Unix 时间戳。 parse_mode: caption 的解析方式（none / markdown / html）。

把多张图片 / 多个视频作为一个相册（media group）一次发出去。

Args: chat: 目标对话。 paths: 本地文件路径列表，最多 10 个。 caption: 相册说明（挂在第一个文件上）。 reply_to: 要回复的消息 ID。 as_document: 强制作为文件发送。 silent: 静默发送。

下载某条消息里的媒体到本地。

Args: chat: 消息所在对话。 message_id: 消息 ID。 save_dir: 保存目录，留空则使用 TELEGRAM_DOWNLOAD_DIR 或 ./downloads。

批量下载一个对话里最近的媒体文件。

Args: chat: 对话。 media_type: photo / video / document / voice / gif / music / any。 limit: 最多下载几个（1~50）。 save_dir: 保存目录，留空用默认下载目录。 max_size_mb: 跳过大于这个体积的文件。

列出某个用户/群/频道的历史头像（返回 photo_id 和日期）。

下载某个用户/群/频道当前的头像。

列出自己已添加的贴纸包。

看一个贴纸包里都有哪些贴纸（贴纸包链接 t.me/addstickers/xxx 里的 xxx 就是 short_name）。

从某个贴纸包里发一张贴纸。

Args: chat: 目标对话。 short_name: 贴纸包的 short_name（见 get_sticker_set）。 index: 贴纸在包里的下标（get_sticker_set 返回的 index）。 emoji: 也可以按 emoji 选，命中该 emoji 的第一张；给了 emoji 就忽略 index。 reply_to: 回复某条消息。

把消息转发到自己的收藏夹（Saved Messages），方便先存后用。

把本地图片设为自己的头像。

看一条消息里媒体的详细信息（文件名、大小、时长、分辨率等），不下载。

读取某个对话的历史消息，默认从最新往回取。

Args: chat: 对话（ID / @username / 'me'）。 limit: 条数上限，最多 200。 offset_id: 从该消息 ID 之前开始取（分页用）。 min_id: 只取 ID 大于它的消息。 max_id: 只取 ID 小于它的消息。 from_user: 只看某个发送者的消息。 reverse: True 则按时间正序（从旧到新）。 topic_id: 话题群里只看某个话题（用 get_forum_topics 拿 ID）。 before: 只取该时间点之前的消息，ISO8601 / Unix 时间戳 / 相对时间（如 +0s 表示现在）。

取某条消息前后各若干条，用来看上下文。返回按时间正序排列。

Args: chat: 对话。 message_id: 中心消息 ID。 before: 往前取几条（最多 50）。 after: 往后取几条（最多 50）。

搜索消息。不传 chat 时进行全局搜索（搜索所有对话）。

Args: query: 关键词；配合 media_type 时可以留空字符串只按类型筛。 chat: 限定某个对话；留空为全局搜索。 limit: 条数上限，最多 200。 from_user: 限定发送者（仅在指定 chat 时有效）。 media_type: 只搜某种媒体类型的消息。

按媒体类型筛选某个对话中的消息（图片 / 视频 / 文件 / 语音 / 链接 / GIF）。

获取某个对话中的置顶消息。

概览所有有未读消息的对话，以及每个对话的未读条数。

看一条消息的表情回应明细：谁点了什么。

Args: chat: 对话。 message_id: 消息 ID。 limit: 返回多少条，最多 100。 emoji: 只看某一种表情，留空为全部。

读取一条消息的回复串 —— 频道帖子下的评论区，或话题群里某条消息的回复。

Args: chat: 帖子所在的频道 / 群。 message_id: 帖子（或话题起始消息）的 ID。 limit: 取多少条评论，最多 200。

列出话题群（forum）里的话题。拿到 id 后可用 get_messages(topic_id=...) 读该话题。

Args: chat: 开了话题功能的超级群。 limit: 上限，最多 100。 query: 按标题过滤。

列出某个对话里自己设置的定时消息（还没发出去的）。

生成一条消息的 t.me 链接（私聊没有公开链接，link 会是 null）。

把一条 t.me 消息链接解析出来并读取该消息。

支持 t.me/name/123、t.me/c/1234567890/123，以及带话题的 t.me/name/12/345（第一个数字是话题 ID）。

向某个对话发送文本消息。

Args: chat: 目标对话（ID / @username / 'me' 表示收藏夹）。 text: 消息内容。 reply_to: 要回复的消息 ID；话题群里传话题 ID 即发到该话题。 parse_mode: 文本解析方式。 silent: 静默发送（不推送通知）。 link_preview: 是否展示链接预览。 schedule_at: 定时发送时间，如 +30m / 2026-01-01T09:00 / Unix 时间戳。 comment_to: 作为某条频道帖子的评论发送（传帖子 ID）。

编辑自己发送过的某条消息（也可用来改媒体消息的说明文字）。

删除消息。revoke=True 表示同时为对方删除（不可恢复，请先向用户确认）。

把一个对话里的若干消息转发到另一个对话。

Args: from_chat: 源对话。 to_chat: 目标对话。 message_ids: 要转发的消息 ID。 silent: 静默发送。 as_copy: True 则不显示"转发自"抬头（相当于复制一份）。 drop_captions: 复制时丢掉媒体的说明文字。

把某个对话标记为已读（max_id 为 0 表示全部已读）。

置顶或取消置顶一条消息。

给一条消息加/取消表情回应。

在对话里显示"正在输入…"之类的状态，持续若干秒。

发起一个投票或测验。

Args: chat: 目标对话。 question: 问题。 options: 选项文字，2~10 个。 multiple_choice: 允许多选。 quiz: 测验模式（只有一个正确答案，必须给 correct_option）。 correct_option: 正确选项的下标（从 0 开始），仅测验模式使用。 solution: 测验模式下答错时显示的解析。 public_voters: 公开谁投了什么。 close_in_seconds: 多少秒后自动关闭，0 为不自动关闭。 reply_to: 回复某条消息。

给一个投票投票。options 是选项下标（从 0 开始），单选传一个。

关闭自己发起的投票（关闭后不能再投，且不可撤销）。

发送一个地理位置；给了 title 就作为"地点"卡片发送。

以联系人卡片的形式发送一个电话号码。

发送一个随机数动画（骰子/飞镖/篮球等），结果由服务端决定，见返回的 media.value。

把还在排队的定时消息立刻发出去。

取消（删除）尚未发出的定时消息。

等待某个对话出现新消息（轮询），常用于发指令给 bot 后等它回复。

Args: chat: 要盯的对话。 after_message_id: 只认 ID 大于它的消息；0 表示以调用时的最新消息为界。 timeout_seconds: 最多等多少秒（1~300）。 from_user: 只等某个发送者的消息。 incoming_only: 只算别人发来的消息，忽略自己发的。 contains: 消息文本必须包含这个子串才算命中。

清空一个对话的历史记录（不可恢复，必须传 confirm=True）。

Args: chat: 对话。 confirm: 必须显式传 True 才会执行。 revoke_for_everyone: 私聊时同时为对方删除。 max_id: 只清空 ID 小于等于它的消息，0 表示全部。