ATelegram中文官网ARTICLE JOURNAL
开发者资源2026-08-12 09:52:14更新于 2026-08-12 09:52:14

Telegram Bot发送文档文件的完整代码示例：从入门到实战

本文提供Telegram Bot发送文档文件的完整代码示例，涵盖Python、Node.js等主流语言，并详解API参数、常见错误及优化技巧，帮助开发者快速实现文件发送功能。

阅读提示建议先浏览小标题，再根据需要深入阅读具体段落。

在Telegram Bot开发中，发送文档文件是极为常见的需求——无论是自动报告、媒体推送，还是用户请求的附件传输，掌握sendDocument方法的正确用法都至关重要。本文将从API基础讲起，提供可直接运行的完整代码示例，并深入解析参数细节与常见陷阱，帮助你快速实现稳定可靠的文件发送功能。

一、Telegram Bot发送文档的基础概念

Telegram Bot API提供了sendDocument方法，用于向指定聊天发送文件。与sendPhoto、sendVideo不同，sendDocument适用于任意格式的文件（PDF、ZIP、DOCX等），且Telegram会将其作为“文档”处理，用户可直接下载或转发。

调用sendDocument时，你需要通过chat_id指定接收方，并通过document参数传递文件。文件来源可以是本地文件（使用multipart/form-data上传）、文件ID（已上传过的文件可直接复用），或文件URL（Telegram会自行下载）。以下各节将分别演示。

二、准备工作：获取Bot Token与聊天ID

在编写代码前，请确保你已经：

  1. 在Telegram中通过@BotFather创建了机器人，并获取到API Token（形如123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11）。
  2. 确定了接收文件的chat_id（用户ID、群组ID或频道ID）。对于私人对话，可直接使用自己的用户ID；对于群组，通常以-100开头。

获取用户ID的快速方法：将@userinfobot加入对话，或向你的Bot发送消息后通过API查看getUpdates响应。

三、Python完整代码示例（使用python-telegram-bot库）

推荐使用官方维护的python-telegram-bot库。首先安装：

pip install python-telegram-bot

示例1：发送本地文件

from telegram import Bot

# 将Token填入此处
bot = Bot(token="YOUR_BOT_TOKEN")
CHAT_ID = "YOUR_CHAT_ID"  # 例如 "123456789" 或 "-1001234567890"

# 发送本地文件（支持相对路径或绝对路径）
with open("report.pdf", "rb") as f:
    message = bot.send_document(chat_id=CHAT_ID, document=f, filename="月度报告.pdf", caption="这是月度报告")

print("发送成功，消息ID:", message.message_id)

示例2：通过URL发送远程文件

from telegram import Bot

bot = Bot(token="YOUR_BOT_TOKEN")
CHAT_ID = "YOUR_CHAT_ID"

url = "https://example.com/files/spec.pdf"
# 注意：Telegram需要能够直接访问该URL，否则会报错
message = bot.send_document(chat_id=CHAT_ID, document=url, caption="远程文档")
print(message)

示例3：使用file_id发送已上传文件

# 获取file_id的典型方式：接收用户发送的文档后，从update中提取
# file_id = update.message.document.file_id
# 之后可直接反复使用，无需重新上传
bot.send_document(chat_id=CHAT_ID, document="BQACAgQAAxkBAAIB..." )

四、Node.js完整代码示例（使用node-telegram-bot-api）

对于JavaScript开发者，可安装node-telegram-bot-api：

npm install node-telegram-bot-api
const TelegramBot = require('node-telegram-bot-api');

const token = 'YOUR_BOT_TOKEN';
const chatId = 'YOUR_CHAT_ID';

const bot = new TelegramBot(token, { polling: true });

// 发送本地文件
bot.sendDocument(chatId, 'report.pdf', { caption: '节点示例' })
  .then(msg => console.log('发送成功', msg.message_id))
  .catch(err => console.error('错误', err));

// 发送远程文件
bot.sendDocument(chatId, 'https://example.com/spec.pdf')
  .then(() => console.log('远程已发送'));

// 发送Buffer或流
const fs = require('fs');
bot.sendDocument(chatId, fs.createReadStream('report.pdf'));

五、使用HTTP API直接调用（curl示例）

若不依赖任何SDK，可通过原生HTTP请求实现。以下为使用curl发送本地文件的示例：

curl -F "chat_id=YOUR_CHAT_ID" \
     -F "document=@/path/to/file.pdf" \
     -F "caption=来自curl的文档" \
     https://api.telegram.org/bot<YOUR_BOT_TOKEN>/sendDocument

注意：document参数需使用@前缀指定本地文件路径。若发送URL，则直接传入字符串，但需保证URL可公开访问。

六、常用参数详解与自定义

sendDocument支持以下常用参数，合理使用可增强交互性：

  • caption：文件标题，最长1024字符，支持HTML或Markdown格式。
  • parse_mode：设置caption的格式（HTML或MarkdownV2），需与实体配合。
  • filename：覆盖Telegram显示的文件名。
  • thumbnail：缩略图（仅限JPEG或PNG，且小于200KB），提升视觉体验。
  • disable_notification：静默发送，不打扰用户。
  • reply_to_message_id：回复某条消息，便于上下文关联。
  • reply_markup：附加内联键盘或自定义键盘。

示例：带缩略图和内联按钮

from telegram import Bot, InlineKeyboardButton, InlineKeyboardMarkup

bot = Bot(token="YOUR_BOT_TOKEN")
keyboard = InlineKeyboardMarkup([
    [InlineKeyboardButton("下载文件", url="https://example.com/dl")]
])

with open("guide.pdf", "rb") as f:
    bot.send_document(
        chat_id=CHAT_ID,
        document=f,
        filename="使用指南.pdf",
        caption="PDF指南",
        parse_mode="HTML",
        thumbnail=open("thumb.jpg", "rb"),
        reply_markup=keyboard
    )

七、常见错误与解决方案

  • 文件过大：Telegram Bot API限制上传文件最大50MB（通过Bot发送），下载则可达20MB。超过需使用本地Bot或分割文件。
  • chat_id无效：确保用户或群组未屏蔽机器人，且ID格式正确。群组ID通常为负数。
  • 文件格式不支持：某些MIME类型可能被拒，建议使用通用格式（如PDF、ZIP）。
  • URL无法访问：Telegram服务器无法解析你的URL时，会返回Bad Request: wrong URL，请使用公网可访问的HTTPS地址。
  • 429请求过多：触发限流时，需等待retry_after秒后重试。

八、完整实战：实现一个自动发送日报的Bot

下面是一个综合示例，脚本每日生成日志文件，并自动发送到指定群组：

import logging
from datetime import datetime
from telegram import Bot

logger = logging.getLogger(__name__)

TOKEN = "YOUR_TOKEN"
CHAT_ID = "YOUR_CHAT_ID"

# 生成当日报告文件
def generate_report():
    filename = f"daily_report_{datetime.now().strftime('%Y%m%d')}.txt"
    with open(filename, "w", encoding="utf-8") as f:
        f.write(f"日期: {datetime.now().date()}\n")
        f.write("项目状态: 完成\n")
    return filename

# 发送文件
def send_report():
    bot = Bot(token=TOKEN)
    file_path = generate_report()
    try:
        with open(file_path, "rb") as f:
            bot.send_document(chat_id=CHAT_ID, document=f, caption="每日报告自动推送")
        logger.info("发送成功")
    except Exception as e:
        logger.error(f"发送失败: ")
    finally:
        import os
        os.remove(file_path)  # 清理临时文件

if __name__ == "__main__":
    send_report()

将此脚本部署为定时任务（cron或系统计划程序），即可实现无人值守的日报推送。

九、性能与安全建议

  • 复用file_id：对于频繁发送的相同文件，先上传一次获取file_id，后续直接使用可大幅提升速度并减少资源消耗。
  • 使用HTTPS：确保你的服务器支持HTTPS，避免中间人攻击。
  • 限制文件类型：对于不可信来源，在服务端校验MIME类型和大小，防止恶意文件传播。
  • 日志监控：记录发送结果，便于排查问题。

总结

本文提供了Telegram Bot发送文档文件的多种完整代码示例，涵盖Python、Node.js和原生HTTP调用方式。从本地文件、远程URL到file_id复用，你可以根据实际场景灵活选择。关键在于理解sendDocument的参数细节和潜在错误，并遵循最佳实践。掌握了这些，你就能轻松构建自动化文件分发、报告推送等实用Bot。更多高级玩法，不妨查阅官方API文档并动手实践。

TOPICS

Telegram 中文版下载

相关标签#Bot开发#API调用#代码示例
FAQ

多平台客户端选择

常见问题

Telegram Bot发送文档的大小限制是多少？

通过Bot API发送文档，最大支持50MB；通过机器人下载文件，最大支持20MB。如果文件超过限制，可以考虑拆分文件或使用Telegram的本地Bot（无API限制但需自建环境）。

如何获取发送文档后的file_id？

在Bot收到用户发送的文档时，从update消息中的document.file_id字段获取。对于自己发送的文档，发送成功后返回的Message对象中同样包含file_id，建议存储起来以便后续复用。

sendDocument支持哪些文件格式？

Telegram对发送文档的类型没有严格限制，常见格式如PDF、TXT、ZIP、DOCX等均可。但如果是语音或图片，建议使用对应的sendAudio、sendPhoto等方法，以获得更好的客户端体验。

为什么有时发送URL文件会失败？

可能原因包括：URL不是公网可访问（如局域网/本地地址）、Telegram服务器无法连接、内容被审查或拦截、URL缺少文件扩展名。建议使用HTTPS协议，并确保URL直接指向可下载的资源。

RELATED READING

延伸阅读