Telegram机器人发送PDF文档并自定义文件名的API完全指南

引言：为什么需要自定义文件名？

在开发Telegram机器人时，经常需要向用户发送PDF文档，如报告、电子书或发票。默认情况下，Telegram会根据上传文件的原始名称来命名下载文件，但这往往不能满足实际需求。例如，您可能希望将下载的文件名设置为用户ID或订单号，以便于管理和识别。幸运的是，Telegram Bot API提供了灵活的机制，让您可以在发送文档时自定义文件名。本文将深入解析sendDocument API，并给出Python和Node.js的完整实现。

sendDocument API概述

sendDocument是Telegram Bot API中用于发送文档（包括PDF、ZIP、DOCX等）的方法。它是一个POST请求，支持multipart/form-data格式。核心参数包括：

chat_id：接收文档的聊天ID（必填）
document：文件内容，可以是file_id、URL或multipart上传的文件（必填）
filename：自定义文件名（可选，但正是我们需要的）
caption：文档说明文字（可选）
disable_notification：静默发送（可选）等多个可选参数

其中，filename参数允许您覆盖原始文件名，该参数会作为HTTP请求中multipart数据的filename字段。如果通过file_id发送，Telegram会保留原始文件名，但可以通过显式指定filename来覆盖。

核心参数详解

要使用自定义文件名，您需要理解document字段的两种主要形式：

通过共享文件ID（file_id）：如果文档已上传到Telegram，您可以获得file_id，然后直接发送。此时，若不指定filename，则使用原始文件名；若指定，则使用新名称。
通过上传新文件：使用multipart/form-data上传文件时，可以在filename字段中设置自定义名称，Telegram会将其作为下载时的文件名。

此外，caption参数可以添加说明，支持基本的HTML或Markdown格式，但需要设置parse_mode。

如何自定义文件名

自定义文件名的关键是设置filename参数。无论使用哪种编程语言，都需要确保该参数被正确传递到HTTP请求中。以下是具体做法：

Python示例（使用requests库）

import requests

# 方法1：通过file_id发送，指定filename
api_token = 'YOUR_BOT_TOKEN'
url = f'https://api.telegram.org/bot/sendDocument'
params = {
    'chat_id': '@channel_or_user',
    'document': 'FILE_ID',  # 从之前上传中获取
    'filename': '自定义报告.pdf',
}
resp = requests.post(url, params=params)
print(resp.json())

# 方法2：上传本地文件，通过multipart指定filename
files = {'document': ('自定义报告.pdf', open('original.pdf', 'rb'))}
data = {'chat_id': '@channel_or_user'}
resp = requests.post(url, data=data, files=files)
print(resp.json())

在方法2中，files字典中的元组第一个元素就是自定义文件名。

Node.js示例（使用node-telegram-bot-api）

const TelegramBot = require('node-telegram-bot-api');
const bot = new TelegramBot('YOUR_BOT_TOKEN');

// 方法1：通过file_id发送，指定filename
bot.sendDocument('@channel_or_user', 'FILE_ID', {
    filename: '自定义报告.pdf',
    caption: '这是月度总结'
}).then(m => console.log(m.message_id));

// 方法2：上传本地文件，第二个参数是文件名
bot.sendDocument('@channel_or_user', './original.pdf', {
    filename: '自定义报告.pdf'
}).then(m => console.log(m.message_id));

在方法2中，node-telegram-bot-api会自动将文件路径作为multipart上传，您可以通过filename选项覆盖文件名。

最佳实践与注意事项

文件名规范：建议使用英文或拼音，避免特殊字符，部分客户端可能不支持非ASCII字符，但现代Telegram客户端大多支持Unicode。
缓存与更新：如果同一文件需要发送多次，建议先通过getFile获取file_id并缓存，避免重复上传，节省资源。
文件大小限制：Bot API上传文件最大50MB，下载最大20MB，注意控制。
错误处理：当请求失败时，检查description字段，例如“FILE_IS_TOO_BIG”或“CHAT_NOT_FOUND”。
Webhook场景：如果使用Webhook，同样可以调用sendDocument，不受影响。

FAQ

1. 发送PDF时，自定义文件名不生效怎么办？

检查是否在multipart上传时正确指定了filename。对于file_id发送，确保发送了filename参数，并且没有拼写错误。另外，某些第三方库可能有参数覆盖的Bug，建议直接查看发送的HTTP请求体。

2. 是否支持发送其他类型文档？

sendDocument支持所有Telegram允许的文档类型，包括PDF、ZIP、DOCX、XLSX等。自定义文件名的方法完全相同。

3. 如何通过URL发送远程PDF并自定义文件名？

可以直接将文件URL作为document参数值，但此时无法自定义文件名，因为URL本身带有文件名。如果必须自定义，需要先下载该文件，再作为multipart上传。

4. 是否可以在caption中使用HTML链接？

可以。在caption中使用HTML时，需要将parse_mode设置为'HTML'，例如：caption='点击<a href="http://example.com">这里</a>下载'。

总结

自定义文件名是Telegram Bot开发中的常用需求。通过sendDocument方法的filename参数，您可以轻松实现这一功能。本文提供的方法适用于Python和Node.js，其他语言（如Java、PHP）也可以参照同样的原理。掌握这些技巧，您的机器人将更加专业和用户友好。

希望本指南对您有所帮助。如果您有更多问题，欢迎在评论区讨论。