动画贴纸是Telegram聊天中最具表现力的元素之一，而通过Bot发送动画贴纸可以为用户带来更生动的交互体验。但动画贴纸的编码要求与普通图片或视频完全不同，稍有不慎就会导致发送失败。本文将聚焦Telegram Bot发送动画贴纸的编码要求，从TGS格式规范到sendSticker API的每个细节，帮助你彻底掌握这一技能。
一、动画贴纸的TGS格式规范
Telegram动画贴纸使用TGS格式，它是基于Lottie的矢量动画文件。与传统的GIF或WebP不同，TGS文件实际上是一个经过压缩的JSON文件，其中包含矢量图形、动画曲线和关键帧数据。因此，编码要求首先体现在文件结构上。
- 文件扩展名：必须为
.tgs，但发送时无需显式指定扩展名，系统根据文件内容识别。 - 文件大小：单个TGS文件最大为64KB，超过此限制的贴纸无法被Telegram接受。
- 画布尺寸：固定为512×512像素，但实际可视内容应居中并预留安全边距。
- 帧率：建议为60fps，但Telegram会将其转换为30fps播放，编码时无需强制60fps。
- 颜色模式：支持RGBA，透明背景是必须的，因为贴纸需要与聊天背景融合。
- Lottie JSON限制：顶部必须是
{"v":"5.x.x","fr":...,"ip":...,"op":...}结构，且不支持的表达式和复杂特效会被拒绝。
值得注意的是，TGS文件不能直接由Bot上传作为贴纸包使用，但Bot可以发送已存在于Telegram服务器上的动画贴纸（通过file_id）或通过URL发送符合上述规范的TGS文件。
二、sendSticker API的编码要求
Telegram Bot API的sendSticker方法负责发送贴纸，其核心参数是sticker。该参数接受两种编码形式：
- file_id：一个字符串，表示Telegram服务器上已存在的贴纸文件。使用file_id发送时无需处理编码，只需确保该贴纸属于你的Bot或已被Bot使用过。file_id具有唯一性，但可能因Bot不同而失效。
- URL：一个HTTP/HTTPS链接，指向公开可访问的TGS文件。使用URL发送时，Telegram服务器会尝试下载并验证文件是否符合规则，如果不符合，请求会报错。
另外，sendSticker还支持emoji参数，表示贴纸对应的表情符号，但这只是元数据，不影响编码验证。对于动画贴纸，sticker_type属性在发送时通常自动推断，但确保文件为动画类型至关重要。
三、通过file_id发送动画贴纸
最稳定可靠的方式是使用file_id。当你的Bot第一次收到用户发送的动画贴纸时，可以通过getUpdates或getMessage获取到该贴纸的file_id。之后，编辑即用即可：
POST https://api.telegram.org/bot<TOKEN>/sendSticker
{
"chat_id": 123456789,
"sticker": "CAACAgIAAxkBAAEYqV5nM6..."
}注意：不同Bot之间的file_id不通用，且如果贴纸被删除，file_id会失效。因此，建议在发送前先调用getFile验证file_id的有效性。
四、通过URL发送动画贴纸
如果你有自建贴纸或临时生成的TGS文件，可以将其托管到可公开访问的URL，然后通过URL发送。编码要求在此刻显得尤为重要：
- URL必须直接指向
.tgs文件，不能是包含贴纸的网页。 - 服务器响应需返回
Content-Type: application/octet-stream或application/x-tgs，但Telegram主要校验文件内容。 - 文件必须完整且不超过64KB，否则会返回
STICKER_TGS_NOT_VALID错误。 - 确保URL支持HTTPS，且不要求认证或包含重定向（Telegram会跟随少量重定向，但建议避免）。
示例代码（Python + requests）：
import requests
url = "https://example.com/sticker.tgs"
response = requests.post(
f"https://api.telegram.org/bot/sendSticker",
data={
"chat_id": chat_id,
"sticker": url
}
)
print(response.json())五、常见错误与故障排查
发送动画贴纸时，最常见的错误包括：
- 400 Bad Request: STICKER_TGS_NOT_VALID：TGS文件不符合规范，请检查文件大小、JSON结构、尺寸和帧率。
- 400 Bad Request: STICKER_EMOJI_INVALID：emoji参数包含无效字符，仅支持标准Unicode表情。
- 404 Not Found：file_id不存在或已被删除，需重新获取。
- 网络超时：URL无法访问或下载速度过慢，建议使用CDN或压缩文件。
调试时，可以先手动下载TGS文件并检查其JSON内容。使用Lottie官方预览工具验证动画是否正常。同时，建议在Bot代码中加入异常处理，捕获API响应中的错误码。
总结
Telegram Bot发送动画贴纸并不复杂，但严格遵循编码要求是成功的关键。从TGS格式的50KB限制到512×512尺寸，再到file_id与URL的选择，每个细节都影响最终的体验。建议开发者优先使用file_id，确保稳定性和速度；若使用URL，务必验证文件的有效性。希望本文能帮助你避免踩坑，让你的Bot动画贴纸功能完美落地。