Telegram机器人发送文件完整指南：从文档、图片到视频的API实战

Telegram机器人的核心能力之一是收发消息，而发送文件则是高频应用场景。无论是发送产品手册、图片素材，还是推送音频、视频，掌握文件发送API都能让你的机器人更加强大。本文将带你从零实践，深入剖析Telegram机器人发送文件的每一个环节，并提供可直接运行的代码示例。

一、基础概念：发送文件涉及的Bot API接口

Telegram Bot API为开发者提供了多组发送文件的接口，每一种媒体类型都有对应的方法：

• sendDocument：发送通用文件（PDF、ZIP等）
• sendPhoto：发送图片
• sendVideo：发送视频
• sendAudio：发送音频（通常为音乐）
• sendVoice：发送语音消息
• sendAnimation：发送GIF或动画
• sendSticker：发送贴纸
• sendVideoNote：发送视频笔记（圆形视频）

所有接口都通过HTTP POST请求调用，地址格式为：https://api.telegram.org/bot<token>/方法名。上传文件时，需要将文件内容以multipart/form-data格式附加到请求中；如果发送的是已存在于Telegram服务器上的文件，则只需传递对应的file_id字符串。

二、发送前的准备：获取Bot Token

要使用这些接口，你需要一个Bot Token。在Telegram中找到@BotFather，发送/newbot命令，按提示设置机器人的名称和用户名，即可获得一串形如123456789:ABCdefGhIJK...-...-...-的Token。请务必保密Token，它相当于机器人的密码。

接下来，我们以Python语言为例，使用requests库编写代码。安装依赖：

pip install requests

三、Python实战：发送本地文件

以下代码演示如何发送一个本地文件（如PDF）：

import requests

BOT_TOKEN = 'YOUR_BOT_TOKEN'
CHAT_ID = '@your_channel_or_user_id'

url = f'https://api.telegram.org/bot/sendDocument'
files = {'document': open('guide.pdf', 'rb')}
data = {'chat_id': CHAT_ID}
response = requests.post(url, data=data, files=files)
print(response.json())

关键点：files参数中键名必须为document（对应sendDocument），值为以二进制模式打开的文件对象。成功发送后，API会返回包含message的JSON对象，其中包含document.file_id，此ID可用于后续直接发送相同文件，而无需再次上传。

四、发送网络图片或视频：使用URL

有时文件存放在其他服务器上，我们只需提供URL，Telegram会自行下载并发送。以sendPhoto为例：

url = f'https://api.telegram.org/bot/sendPhoto'
data = {
    'chat_id': CHAT_ID,
    'photo': 'https://example.com/image.jpg'
}
response = requests.post(url, data=data)
print(response.json())

注意：使用URL方式时，文件大小上限为50MB；而通过multipart上传本地文件时，上限为20MB。对于超过50MB的文件，Bot API暂不支持直接推送。

五、参数详解：caption与更多控制项

所有发送文件的方法都支持一组通用参数，让你更灵活地控制消息：

• caption：添加说明文字，最长1024个字符（sendDocument等）或200个字符（sendPhoto等），支持HTML或Markdown格式。
• disable_notification：设为true可静默发送，为true时用户不会收到通知。
• reply_to_message_id：回复某条消息时传入该消息的ID。
• parse_mode：设置HTML或MarkdownV2来解析caption。

例如，给图片添加可点击的超链接caption：

data = {
    'chat_id': CHAT_ID,
    'photo': 'https://example.com/banner.png',
    'caption': '点击访问 官网',
    'parse_mode': 'HTML'
}

六、发送缩略图与特殊类型

对于视频和音频，你可以通过thumb参数指定缩略图（JPEG格式，大小不超过200KB）。缩略图可以是一个file_id或URL。以发送视频为例：

data = {
    'chat_id': CHAT_ID,
    'video': 'https://example.com/video.mp4',
    'thumb': 'https://example.com/thumb.jpg',
    'caption': '精彩视频'
}
url = f'https://api.telegram.org/bot/sendVideo'
requests.post(url, data=data)

发送音频时，还可以传performer和title字段，展示歌手和歌曲名。

七、文件大小限制与性能优化

Telegram Bot API对文件大小有明确限制，务必在开发中规避：

• 通过multipart上传：最大20MB
• 通过URL发送：最大50MB
• 缩略图：最大200KB

当文件较大或频繁发送时，建议先将文件上传至Telegram并获取file_id，后续直接使用file_id发送，可以避免重复上传，降低延迟。此外，利用disable_notification可减少对用户的打扰，提升体验。

八、常见错误与排错指南

在调用API时，你可能遇到以下错误码：

• 400 Bad Request：参数错误，如文件格式不支持、caption过长等。请检查请求参数。
• 401 Unauthorized：Token错误或已失效。
• 403 Forbidden：机器人被限制，或目标聊天不允许发送文件。
• 404 Not Found：方法名拼写错误或API地址不正确。

建议每次请求都打印响应JSON，利用description字段定位问题根源。

总结

通过本文，你已经掌握了Telegram机器人发送文件的完整方法，包括使用sendDocument、sendPhoto等接口，以及本地文件、URL、file_id三种方式的区别。记住文件大小限制，合理设计文件推送策略，你的机器人将能胜任更复杂的任务。现在，立即尝试在你的机器人上实现文件发送吧！