首页 安卓版 网页版 Blog 敏感限制 电报下载

TeleGram 机器人发送富文本消息的完整配置方法

TeleGram 机器人可以通过 Bot API 自动发送通知、菜单、订单状态和群组管理信息。与普通纯文本相比，Markdown 和 HTML 能够为消息加入粗体、斜体、链接、代码片段以及引用效果，让机器人输出更清晰，也更接近网页内容的排版方式。

富文本发送的关键并不只是把文字放进 sendMessage 请求，还包括选择正确的 parse_mode、处理特殊字符、检查链接格式，以及避免用户输入破坏消息结构。配置不当时，机器人可能发送失败，也可能把标记符号原样显示出来。

本文将围绕 Telegram 机器人富文本消息的实际使用流程展开，说明 Markdown 与 HTML 的区别、接口写法、转义规则、调试方法和安全注意事项。无论是使用 Python、Node.js，还是直接调用 HTTP 接口，都可以按照相同的思路完成配置。

富文本消息的工作方式

Telegram Bot API 通过 sendMessage 方法发送文字消息。最基础的请求通常只需要提供聊天编号和消息内容，例如：

https://api.telegram.org/bot机器人令牌/sendMessage

在请求参数中加入 parse_mode=MarkdownV2 或 parse_mode=HTML 后，Telegram 服务器会把消息中的特定标记解析为格式化内容。解析完成后，用户看到的是粗体、链接和代码样式，而不是原始的星号、下划线或标签。

Markdown 适合熟悉轻量标记语法的开发者，编写速度较快，也方便从已有的文本模板迁移。HTML 的标签结构更加直观，尤其适合需要同时使用多种嵌套格式、链接和代码块的通知系统。不过，Telegram 支持的是经过限制的 HTML 子集，并不是完整的网页 HTML，不能直接使用样式表、脚本或任意标签。

机器人发送时间、日期和定时提醒时，还要留意服务器时区与客户端显示时间是否一致。若通过安卓模拟器测试机器人消息，可以参考时区问题修正，先确认测试环境的系统时间、地区与夏令时设置，避免把富文本问题误判成时间格式错误。

Markdown 与 HTML 的写法差异

使用 MarkdownV2 时，常见格式包括 *粗体*、_斜体_、~删除线~、`行内代码` 和链接语法 [文字](https://example.com)。如果需要多行代码，可以使用三个反引号包裹内容。MarkdownV2 的功能较丰富，但转义要求严格，很多普通标点在特定语境下也必须加反斜杠。

下面是一条适合通知机器人的 MarkdownV2 示例：

*订单已完成*

编号：`A1024`
状态：*已支付*
[查看详情](https://example.com)

如果内容通过 JSON 发送，换行通常写成 \n，反斜杠则需要根据所使用的编程语言再次转义。开发者经常遇到的错误，是在字符串中直接使用未处理的括号、句号、加号或连字符，导致 Telegram 返回实体解析错误。模板固定时，可以手工检查；内容动态变化时，最好使用专门的转义函数。

HTML 模式的写法更接近标签语言，例如 <b>粗体</b>、<i>斜体</i>、<u>下划线</u>、<s>删除线</s>、<code>代码</code> 和 <a href="https://example.com">查看详情</a>。HTML 中的 <、> 和 & 具有特殊含义，普通文本里出现这些字符时，需要分别转换成 &lt;、&gt; 和 &amp;。

通过接口和代码发送格式化内容

最直接的方式是使用 HTTP POST 请求，把 chat_id、text 和 parse_mode 一起提交。以 HTML 消息为例，请求数据可以写成：

{
  "chat_id": "123456789",
  "text": "<b>系统通知</b>\n订单已经进入处理队列。",
  "parse_mode": "HTML"
}

如果使用 Python，可以借助 requests 发送：

import requests

url = "https://api.telegram.org/botTOKEN/sendMessage"
data = {
    "chat_id": 123456789,
    "text": "<b>系统通知</b>\n订单已经进入处理队列。",
    "parse_mode": "HTML"
}

response = requests.post(url, data=data)
print(response.json())

Node.js、PHP 或其他语言的实现方式基本相同，区别主要在于 HTTP 客户端和字符串处理方法。建议把机器人令牌放进环境变量，不要直接写入公开代码仓库，也不要把带令牌的完整请求地址复制到论坛、日志或截图中。

使用场景 推荐模式 主要优势 需要注意的问题
固定格式通知 HTML 标签清晰，模板易读 必须正确处理特殊字符
快速编写短消息 MarkdownV2 语法简洁，编辑方便 转义规则较严格
包含用户输入的内容 HTML 或安全转义后的 MarkdownV2 便于控制动态字段 不能直接拼接未经处理的输入
代码和命令展示 MarkdownV2 或 HTML 支持行内代码和代码块 反引号、尖括号需要检查
多层链接与强调格式 HTML 标签结构更直观 只支持 Telegram 允许的标签

发送后不要只看 HTTP 状态码，还要检查返回 JSON 中的 ok 字段。ok 为 false 时，description 通常会提示错误位置，例如实体未闭合、实体偏移量无效或消息格式不正确。开发阶段可以先发送极短文本，再逐步增加链接、代码块和动态字段，这比一次性提交复杂模板更容易定位问题。

动态内容的转义与安全处理

机器人消息中的标题、用户名、商品名称和用户评论，往往来自数据库或外部请求。若直接把这些内容拼接进 Markdown 或 HTML 模板，特殊字符就可能改变原有结构。例如用户名中包含 < 或 &，HTML 解析器可能将它误认为标签；Markdown 文本中的下划线和方括号，也可能被识别成格式标记。

HTML 模式下，可以先对动态字段进行实体转义，再放入标签中。Python 示例可以使用标准库：

from html import escape

user_name = escape(user_name, quote=True)
message = f"<b>欢迎，{user_name}</b>"

如果动态字段要放进链接地址，还需要验证网址协议，通常只允许 https 或可信的 http 地址。不要让用户输入直接决定完整的 href 值，否则可能产生钓鱼链接、恶意跳转或消息内容欺骗。对于 MarkdownV2，则应根据字段所在位置处理 _ * [ ] ( ) ~ > # + - = | { } . !` 等特殊字符。

消息长度也需要纳入设计。Telegram 对单条文字消息有长度限制，复杂的代码块、长链接和多语言字符可能使消息超过上限。可以在发送前计算长度，必要时分段发送，并在分段之间保留标题或序号。分段时不能简单地从任意字符位置截断 Markdown 或 HTML，否则可能把标签、链接或代码块切成不完整结构。

调试失败消息与提升可靠性

常见的富文本故障包括标记原样显示、消息完全发送失败、链接无法点击、换行异常和部分内容消失。标记原样显示通常代表没有传递 parse_mode，或者使用了 Telegram 不支持的标签。发送失败则多半与未转义字符、未闭合标签、错误的 JSON 字符串或超出长度限制有关。

排查时，可以先关闭富文本模式发送同一段文字，确认机器人令牌、聊天编号和网络请求本身没有问题。随后只启用一种格式，例如单独测试粗体，再测试链接、代码块和动态字段。不要同时混用 MarkdownV2 标记与 HTML 标签，否则解析器会把另一种语法当成普通字符，甚至造成结构冲突。

如果机器人部署在受限网络环境中，接口超时或连接失败也可能被误认为是消息格式问题。此时应分别测试 DNS、HTTPS 请求、代理设置和 Telegram API 响应。需要检查代理或节点状态时，可参考MTProto代理检测，但要注意代理连接正常并不代表 Bot API 参数一定正确，两类问题应分开记录和验证。

上线前后的检查重点

在正式启用自动通知前，建议先用测试机器人和私人聊天验证模板，确认不同客户端上的显示效果基本一致。安卓、iOS、桌面版和网页版可能在字体间距、代码块宽度以及链接预览方面存在细微差别，因此不要只依赖单一设备截图。

发送前可以重点检查以下项目：

上线后还应保留必要的错误日志，但不要记录机器人令牌、完整用户隐私内容或包含敏感参数的请求地址。对于批量通知，可以记录聊天编号的脱敏值、错误类型、重试次数和时间戳，方便定位失败范围。

维护阶段可定期复查这些内容：

当消息模板需要频繁变化时，建议把正文、动态字段和格式规则分离保存。固定模板可以放在版本控制中，动态数据通过安全函数注入；高风险内容则先经过白名单校验。对于重要通知，还可以在发送失败后进入队列，按指数退避策略重试，避免网络短暂波动造成消息永久丢失。

富文本的价值在于让信息层次更清楚，而不是把每条消息都装饰得复杂。日常通知通常使用标题、状态、一个操作链接就足够；只有在命令说明、账单摘要或多步骤指引中，才需要加入代码块、引用和多级排版。选定一种主要格式并建立可复用模板，往往比在 Markdown 和 HTML 之间频繁切换更稳定。

现在即可创建一个测试机器人，准备一条包含粗体、链接和动态字段的短消息，并分别用 MarkdownV2 与 HTML 发送验证。完成转义、错误处理和日志脱敏后，再把模板接入实际的通知流程，让机器人消息在清晰度、可维护性与安全性之间保持平衡。