Telegram机器人发送照片API调用详解：从基础到实战

Telegram机器人的核心能力之一就是主动向用户发送消息，而照片作为最直观的媒介，在通知、订阅、客服等场景中应用广泛。很多开发者拿到Token后，却卡在了“如何用API发送照片”这一步。今天，我们就从零开始，彻底搞懂Telegram机器人发送照片的API调用方法。

sendPhoto方法概览

Telegram Bot API提供了sendPhoto方法，用于向指定聊天发送照片。这是所有机器人发图的唯一官方接口。调用时需要向https://api.telegram.org/bot<token>/sendPhoto发送HTTP请求，支持GET或POST，但推荐使用POST，尤其当上传文件时必须用multipart/form-data。

sendPhoto的核心参数是chat_id和photo。前者表示目标聊天（用户ID、群组ID或频道用户名），后者则指定照片来源。另外，你还可以附加标题、解析模式、禁用通知等选项，实现更丰富的交互。

准备工作：获取Bot Token

在Telegram中搜索@BotFather，这是官方机器人管家。
发送/newbot命令，按提示设置机器人名称和用户名。
创建成功后，BotFather会返回一个Token，形如123456:ABC-DEF...，这就是机器人的唯一凭证。请妥善保管，不要泄露。

有了Token，就可以调用所有API方法了。注意，Token相当于机器人的密码，一旦泄露可能导致机器人被滥用，务必通过环境变量或配置文件妥善管理。

三种发送照片的方式

sendPhoto的photo参数支持三种值，对应不同的使用场景：

1. 使用文件ID

文件ID是Telegram服务器上已存在的照片的标识。只要文件已上传过，即使文件被删除，ID也可能有效。使用文件ID发送，请求体最简洁，速度最快，适合重复发送同一张图。获取文件ID的途径有：通过getUpdates获取用户发送的照片ID，或从其他API响应中提取。

{"chat_id": "123456", "photo": "AgACAgUAAxkBAA..."}

2. 使用URL

如果照片托管在公网HTTP/HTTPS地址，直接将URL传给photo参数。Telegram会自动拉取图片。这种方式适合与现有图床或CDN集成，但需要注意URL必须可公开访问，且图片格式要受支持。

{"chat_id": "@mychannel", "photo": "https://example.com/image.jpg"}

3. 直接上传文件

当照片在本地时，需要用multipart/form-data将文件作为表单字段上传。这是唯一支持上传新文件的方式，适用于生成图表、动态截图等场景。请求的photo字段必须为文件内容，而chat_id等参数作为表单数据一并提交。

POST https://api.telegram.org/bot<TOKEN>/sendPhoto
Content-Type: multipart/form-data

chat_id=123456
captcion=本地照片
photo=@/path/to/photo.jpg

常用参数配置

caption：照片的标题，最长1024字符，支持HTML或Markdown格式，需要配合parse_mode。
parse_mode：设置caption的解析格式，可选HTML或MarkdownV2，让标题支持粗体、链接等富文本。
disable_notification：设为true时，接收方不会收到通知，适合静默推送。
reply_to_message_id：回复某条消息，让照片与对话上下文关联。
reply_markup：添加内联键盘或自定义键盘，提升交互性。

Python实战：先用起来

下面以Python的requests库为例，演示如何通过三种方式发送照片。请先安装requests：pip install requests

示例1：通过文件ID发送

import requests

token = "123456:ABC-DEF"
chat_id = "123456789"
photo_id = "AgACAgUAAxkBAA..."

url = f"https://api.telegram.org/bot/sendPhoto"
payload = {"chat_id": chat_id, "photo": photo_id}
resp = requests.post(url, json=payload)
print(resp.json())

示例2：通过URL发送

import requests

token = "123456:ABC-DEF"
chat_id = "@mychannel"
photo_url = "https://example.com/photo.jpg"

url = f"https://api.telegram.org/bot/sendPhoto"
payload = {"chat_id": chat_id, "photo": photo_url}
resp = requests.post(url, json=payload)
print(resp.json())

示例3：直接上传本地文件

import requests

token = "123456:ABC-DEF"
chat_id = "123456789"
photo_path = "./screenshot.jpg"

url = f"https://api.telegram.org/bot/sendPhoto"
with open(photo_path, "rb") as photo:
    files = {"photo": photo}
    data = {"chat_id": chat_id, "caption": "看这张截图"}
    resp = requests.post(url, files=files, data=data)
print(resp.json())

运行后，如果返回的JSON中ok字段为true，说明发送成功。如果失败，没关系，看下一节排查。

常见错误与调试建议

400 Bad Request: photo file is too small/large

Telegram要求照片至少10KB，最大不超过10MB（PNG/JPEG）或200KB（GIF，但GIF需作为动画发送）。检查文件尺寸和格式。

400 Bad Request: wrong file identifier/HTTP URL specified

文件ID无效或URL无法访问。确认ID是否正确，URL是否允许Telegram服务器抓取（不能是隐私链接）。

403 Forbidden: bot was blocked by the user

用户主动屏蔽了机器人，无法主动发送。需要用户先发起对话。

429 Too Many Requests

发送频率过快，触发限流。Telegram要求同一聊天发消息间隔至少1秒，不同聊天可宽松。建议在代码中加入重试机制。

调试时，开启Webhook或使用getUpdates输出的错误信息，结合日志逐项排查。也可以先用Telegram桌面客户端手动输入Bot的API链接测试，快速定位问题。

总结

通过sendPhoto方法，你可以灵活选择文件ID、URL或上传文件三种方式实现照片发送。实际开发中，建议优先使用文件ID或URL，避免重复上传；动态内容则走上传接口。掌握参数配置和错误排查，能大幅提升开发效率。现在就去你的机器人上试试吧，让图片消息替你说“图”见不如“码”见。