Telegram Bot发送消息API示例：从构造请求到消息类型全解析

Telegram Bot API为开发者提供了强大的消息发送能力，其中sendMessage方法是最常用、最核心的接口。本文将以完整的代码示例为线索，手把手教你如何构造请求、调试参数，并实现从纯文本到富媒体的各种消息推送。无论你是新手还是资深开发者，都能从中获得可直接落地的实用技巧。

一、调用前准备：令牌与接口地址

在调用sendMessage之前，你需要先获取Bot令牌（Token）。令牌是标识机器人身份的唯一密钥，格式通常为123456789:AAF...。请务必妥善保管，任何拥有令牌的人都能完全控制你的Bot。

Telegram Bot API的基础URL为：

https://api.telegram.org/bot<token>/sendMessage

其中<token>需要替换为你的实际令牌。所有请求都支持GET和POST两种方式，但为了避免URL长度限制和特殊字符问题，建议使用POST请求，并将参数放入请求体。

二、最简发送示例：纯文本消息

我们先从一个最基础的Python示例开始，使用requests库发送文本消息：

import requests

TOKEN = "123456789:AAF..."
CHAT_ID = "@your_channel"  # 可以是用户ID、群组ID或频道用户名

url = f"https://api.telegram.org/bot/sendMessage"
params = {
    "chat_id": CHAT_ID,
    "text": "Hello, Telegram!"
}

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

运行这段代码，你的机器人就会向指定会话发送“Hello, Telegram!”。chat_id是必需的，它可以是数字ID（例如123456789），也可以是频道/群组的公开用户名（以@开头）。发送成功后，API会返回包含已发送消息详情的JSON对象。

三、sendMessage核心参数详解

除了chat_id和text，sendMessage还支持一系列可选参数，用于控制消息的格式、行为和附加功能：

message_thread_id：发送到指定主题的话题ID（用于论坛群组）。
parse_mode：设置HTML或MarkdownV2格式，让消息支持富文本。
disable_web_page_preview：设为true时，不显示链接的网页预览。
disable_notification：设为true时，接收方不会收到通知（静默发送）。
reply_to_message_id：回复指定的消息。
reply_markup：内联键盘或自定义键盘，用于交互式按钮。

合理利用这些参数，可以极大提升Bot的可用性。例如，使用parse_mode发送带格式的消息：

params = {
    "chat_id": CHAT_ID,
    "text": "*加粗* 和 _斜体_ 以及 `代码`",
    "parse_mode": "MarkdownV2"
}

四、发送富媒体消息：不只是文本

Telegram Bot API还提供了发送照片、音频、文档、视频等富媒体消息的接口。以sendPhoto为例，注意它使用multipart/form-data上传文件：

import requests

url = f"https://api.telegram.org/bot/sendPhoto"
files = {"photo": open("image.jpg", "rb")}
data = {"chat_id": CHAT_ID, "caption": "这是一张示例图片"}
response = requests.post(url, files=files, data=data)

如果你已经有一个图片的URL，也可以直接传URL，而不需要上传文件：

data = {"chat_id": CHAT_ID, "photo": "https://example.com/image.jpg"}

其他媒体接口如sendDocument、sendVideo、sendAudio等，参数结构类似，只需将photo字段替换为相应的字段名（如document、video）。

五、使用reply_markup添加交互按钮

通过reply_markup参数，你可以为消息附加内联键盘（InlineKeyboardMarkup）或自定义键盘（ReplyKeyboardMarkup）。例如，添加一个点击后弹出数字的按钮：

import json

keyboard = {
    "inline_keyboard": [[
        {"text": "点击我", "callback_data": "click_1"}
    ]]
}
params = {
    "chat_id": CHAT_ID,
    "text": "试试点击下面的按钮：",
    "reply_markup": json.dumps(keyboard)
}
response = requests.post(url, data=params)

内联键盘的回调数据（callback_data）会通过CallbackQuery触发，你需要在getUpdates或Webhook中处理这些回调。

六、错误处理与状态码检查

API调用并非总能成功，因此必须检查HTTP状态码和响应中的ok字段。常见的错误包括：

401 Unauthorized：令牌无效，请重新获取。
400 Bad Request：参数错误或消息格式不正确。
429 Too Many Requests：请求过于频繁，触发限流，需要等待后重试。
403 Forbidden：Bot被用户或群组封禁。

下面是一个带错误处理的健壮示例：

import time

response = requests.post(url, data=params)
if response.status_code == 200 and response.json().get("ok"):
    print("发送成功")
else:
    error = response.json().get("description", "未知错误")
    print(f"发送失败: ")
    # 根据错误类型决定是否重试，注意429时建议指数退避

七、完整实战：自动推送报告消息

综合以上知识点，我们实现一个自动推送格式化工况报告的函数：

def send_report(content):
    text = f"系统报告\n"
    params = {
        "chat_id": CHAT_ID,
        "text": text,
        "parse_mode": "HTML",
        "disable_web_page_preview": True
    }
    r = requests.post(url, data=params, timeout=10)
    return r.json().get("ok")

这个函数可以方便地集成到定时任务或监控脚本中。

总结

通过本文的示例，你已经掌握了Telegram Bot发送消息API的核心用法：构造请求、处理参数、发送富媒体、添加交互按钮以及错误处理。合理利用sendMessage及其同族API，你可以构建出功能强大的自动化机器人。建议在实际项目中，将令牌存放在环境变量中，并使用官方库（如python-telegram-bot）来简化开发。现在，快去试试让你的Bot开始发送第一条消息吧！

Telegram Bot发送消息API示例：从构造请求到消息类型全解析

一、调用前准备：令牌与接口地址

二、最简发送示例：纯文本消息

三、sendMessage核心参数详解

四、发送富媒体消息：不只是文本

五、使用reply_markup添加交互按钮

六、错误处理与状态码检查

七、完整实战：自动推送报告消息

总结

Telegram 中文版下载

多平台客户端选择

常见问题

延伸阅读