Telegram机器人发送文档完整实现指南

在Telegram机器人开发中，发送文档（如PDF、Word、Excel、图片等）是一项非常常见的需求。无论是自动生成报告、推送资料，还是实现文件管理功能，掌握文档发送的实现方法都至关重要。本文将从基础知识到实际编码，完整演示Telegram机器人发送文档的每一个步骤，帮助你快速集成这一功能。

Telegram机器人发送文档简介

Telegram Bot API提供了sendDocument方法，让机器人可以向指定聊天（用户或群组）发送文件。该方法支持两种数据源：本地文件（需上传）和在线文件URL。发送成功后，文件会以文档形式出现在聊天中，用户可以直接下载或查看。Telegram对文档的大小限制为50MB，满足绝大多数日常需求。

环境准备与机器人创建

在开始编码之前，需要做好两项准备：

1. 创建机器人并获取Token：在Telegram中与@BotFather对话，使用/newbot命令创建机器人，随后会得到一个API Token，格式如123456:ABC-DEF...。
2. 选择开发环境：本文示例使用Python，需安装Python 3.7+，并确保可以访问Telegram API（可能需要科学上网）。

使用HTTP API直接发送文档

最简单的实现方式是直接调用HTTP接口，不需要任何第三方库。使用curl命令示例：

curl -F "chat_id=123456789" -F "document=@/path/to/file.pdf" https://api.telegram.org/bot<YOUR_TOKEN>/sendDocument

如果使用Python，可以用requests库：

import requests

TOKEN = "YOUR_BOT_TOKEN"
CHAT_ID = "123456789"
FILE_PATH = "/path/to/file.pdf"

url = f"https://api.telegram.org/bot/sendDocument"
with open(FILE_PATH, "rb") as f:
    files = {"document": f}
    data = {"chat_id": CHAT_ID}
    response = requests.post(url, files=files, data=data)

print(response.json())

运行后，如果一切正常，你会收到包含message_id的JSON响应，表示文档已成功发送。

使用python-telegram-bot库发送文档

python-telegram-bot是一个流行的异步/同步库，封装了Bot API，让开发更高效。首先安装：

pip install python-telegram-bot

以下是一个完整的同步示例（v20.x版本）：

from telegram import Bot

bot = Bot(token="YOUR_BOT_TOKEN")
bot.send_document(chat_id="123456789", document=open("/path/to/file.pdf", "rb"))

如果需要处理命令，比如用户发送/send时触发，可以使用Application类：

from telegram.ext import Application, CommandHandler
from telegram import Update

async def send_doc(update: Update, context):
    with open("/path/to/file.pdf", "rb") as f:
        await context.bot.send_document(chat_id=update.effective_chat.id, document=f)

app = Application.builder().token("YOUR_BOT_TOKEN").build()
app.add_handler(CommandHandler("send", send_doc))
print("Bot started")
app.run_polling()

注意：v20+为异步库，使用async/await语法，且必须使用Application而不是旧的Updater。如果仍使用老版本，请参考旧文档。

发送在线文档URL

如果文件已经在公网可访问（例如托管在云存储上），可以直接传URL，无需上传本地文件：

import requests

TOKEN = "YOUR_BOT_TOKEN"
CHAT_ID = "123456789"
URL = "https://example.com/report.pdf"

url = f"https://api.telegram.org/bot/sendDocument"
data = {"chat_id": CHAT_ID, "document": URL}
response = requests.post(url, data=data)
print(response.json())

使用URL发送时，Telegram会主动从该地址下载文件，因此需要保证URL可访问且没有防盗链。这种方式适合服务器端已经存储文件的场景，可以减少上传流量。

错误处理与常见问题

在实际开发中，难免会遇到错误，以下是常见问题及解决方案：

• 文件超出50MB限制：Telegram API有硬限制，超过会返回400错误。解决方案是压缩文件，或使用Telegram提供的分片上传（仅针对大文件，但sendDocument不支持分片，只能通过文件流）。实际上对于50MB以上的文件，可以考虑先上传到Telegram服务器获取file_id，但发送时仍需遵循限制，所以唯一办法是压缩或拆分。
• 网络超时：上传大文件时可能超时，可以通过timeout参数增加等待时间。在requests中设置timeout=60，在库中设置read_timeout。
• 文件不存在或路径错误：当使用@上传时，如果本地文件不存在，会收到“文件不存在”错误。务必检查文件路径。
• 无效的文档参数：如果document既不是文件对象也不是URL，API会返回400。确保传递正确格式。

最佳实践与性能优化

为了让你的机器人更稳定、高效，建议遵循以下最佳实践：

1. 使用异步IO：对于高并发场景，使用异步框架（如python-telegram-bot的异步版本或aiohttp）可以大幅提升性能。
2. 缓存file_id：同一个文件重复发送时，可以先将文件上传一次，获取file_id，之后直接使用file_id发送，避免重复上传，节省流量和带宽。
3. 添加重试机制：由于网络波动，建议在发送失败时自动重试2-3次，并增加指数退避。
4. 设置日志：记录每次发送的详细信息，便于排查问题。

总结

本文详细介绍了Telegram机器人发送文档的完整实现方法，从HTTP API调用到使用Python库，以及常见错误与优化建议。无论你是初学者还是资深开发者，都可以快速集成文档发送功能。记住实践出真知，建议你立即创建一个测试机器人，亲手体验文档发送的乐趣。如果在开发过程中遇到其他问题，欢迎查阅Telegram官方文档或社区讨论。