Telegram Bot上传与管理贴纸包API详解：从创建到发布的完整指南

贴纸是Telegram聊天中最富表现力的元素之一，而通过Bot API，开发者可以完全自动化地创建和管理贴纸包。本文将深入解析Telegram Bot中与贴纸包相关的全部API接口，从文件上传到贴纸包发布，手把手带你构建一个功能完整的贴纸管理机器人。

贴纸包管理API概览

Telegram Bot API为贴纸包管理提供了一组完整的接口，涵盖上传、创建、添加、删除、排序、设置缩略图以及查询信息等操作。所有接口都需要通过Bot Token进行身份验证，并且要求Bot已被授予相应的权限（通过BotFather设置）。核心接口包括：

uploadStickerFile：上传贴纸文件，返回文件ID。
createNewStickerSet：创建全新的贴纸包。
addStickerToSet：向现有贴纸包添加贴纸。
setStickerPositionInSet：调整贴纸在包中的位置。
deleteStickerFromSet：删除贴纸包中的某个贴纸。
setStickerSetThumb：设置贴纸包缩略图。
getStickerSet：获取贴纸包的详细信息。

前置准备：获取密钥与权限

在开始调用API之前，你需要完成以下准备：

通过@BotFather创建一个新的Bot，并取得API Token。
向BotFather发送/setstickers命令，选择你的Bot，并启用贴纸管理权限（默认开启）。
确认贴纸包命名规则：name参数必须以_by_<botusername>结尾（例如my_stickers_by_MyBot），只能包含字母、数字和下划线，且总长度不超过64个字符。

上传贴纸文件（uploadStickerFile）

在创建或添加贴纸前，必须先将贴纸文件上传到Telegram服务器，以获得一个file_id。该接口要求提供用户ID（通常是创建者的Telegram用户ID）以及贴纸文件。支持三种格式：

静态贴纸：PNG或WEBP格式，尺寸建议512×512像素，文件大小不超过512KB。
动画贴纸：TGS格式（Lottie动画），尺寸512×512，文件大小不超过64KB。
视频贴纸：WEBM格式（带透明通道），尺寸512×512，文件大小不超过256KB。

示例代码：

import requests

def upload_sticker(token, user_id, sticker_path):
    url = f"https://api.telegram.org/bot/uploadStickerFile"
    files = {'sticker': open(sticker_path, 'rb')}
    params = {'user_id': user_id}
    resp = requests.post(url, params=params, files=files)
    return resp.json()['result']['file_id']

创建新贴纸包（createNewStickerSet）

使用createNewStickerSet可以创建全新的贴纸包。需要指定用户ID、贴纸包name、展示名称title、贴纸列表stickers（数组）以及贴纸格式sticker_format（可选，但推荐显式指定）。每个贴纸对象包含：sticker（文件ID）、emoji_list（关联表情列表）、mask_position（可选，用于蒙版贴纸）、keywords（可选，搜索关键词）。

def create_sticker_set(token, user_id, name, title, stickers):
    url = f"https://api.telegram.org/bot/createNewStickerSet"
    payload = {
        'user_id': user_id,
        'name': name,
        'title': title,
        'stickers': stickers  # list of dicts
    }
    resp = requests.post(url, json=payload)
    return resp.json()

注意：贴纸包名称一旦创建便不可修改。若需要使用自定义表情符号（Custom Emoji），还需通过BotFather额外配置。

向现有贴纸包添加贴纸（addStickerToSet）

如果想在已有的贴纸包中增加贴纸，使用addStickerToSet。该接口需要user_id（创建者ID）、贴纸包名称name，以及一个贴纸对象（格式与创建时相同）。一次只能添加一个贴纸。

def add_sticker(token, user_id, pack_name, sticker):
    url = f"https://api.telegram.org/bot/addStickerToSet"
    payload = {
        'user_id': user_id,
        'name': pack_name,
        'sticker': sticker
    }
    resp = requests.post(url, json=payload)
    return resp.json()

调整贴纸位置与删除

贴纸包内的顺序可以通过setStickerPositionInSet调整，参数包括sticker（文件ID）和position（从0开始的索引）。删除贴纸则使用deleteStickerFromSet，只需传递sticker文件ID。

def set_position(token, sticker_id, position):
    url = f"https://api.telegram.org/bot/setStickerPositionInSet"
    payload = {'sticker': sticker_id, 'position': position}
    return requests.post(url, json=payload).json()

def delete_sticker(token, sticker_id):
    url = f"https://api.telegram.org/bot/deleteStickerFromSet"
    payload = {'sticker': sticker_id}
    return requests.post(url, json=payload).json()

设置贴纸包缩略图（setStickerSetThumb）

贴纸包可以设置一个独立的缩略图，显示在聊天面板中。该接口需要user_id、贴纸包name和thumb（PNG、WEBP或TGS/Lottie格式的文件ID）。如果不设置，系统将使用贴纸包中的第一张贴纸作为缩略图。

def set_thumb(token, user_id, pack_name, thumb_id):
    url = f"https://api.telegram.org/bot/setStickerSetThumb"
    payload = {
        'user_id': user_id,
        'name': pack_name,
        'thumb': thumb_id
    }
    return requests.post(url, json=payload).json()

查询贴纸包信息（getStickerSet）

通过getStickerSet可以获取贴纸包的完整信息，包括名称、标题、贴纸列表、缩略图等。返回的贴纸对象中包含file_id，可用于后续操作。

def get_stickerset(token, pack_name):
    url = f"https://api.telegram.org/bot/getStickerSet"
    params = {'name': pack_name}
    return requests.get(url, params=params).json()

实战：用Python一键创建贴纸包

下面我们整合上述接口，实现一个完整的流程：上传两张贴纸，创建新贴纸包，并添加第三张贴纸。本示例使用requests库，请确保已安装。

import requests

TOKEN = '你的Bot Token'
USER_ID = 123456789  # 你的Telegram用户ID

def api(method, payload=None, files=None):
    url = f"https://api.telegram.org/bot/"
    return requests.post(url, params=payload, files=files, timeout=10).json()

# 1. 上传贴纸
file1 = api('uploadStickerFile', {'user_id': USER_ID}, {'sticker': open('sticker1.png', 'rb')})
file2 = api('uploadStickerFile', {'user_id': USER_ID}, {'sticker': open('sticker2.webp', 'rb')})
file3 = api('uploadStickerFile', {'user_id': USER_ID}, {'sticker': open('sticker3.png', 'rb')})

# 2. 创建贴纸包（第一张和第二张）
stickers = [
    {'sticker': file1['result']['file_id'], 'emoji_list': ['😀']},
    {'sticker': file2['result']['file_id'], 'emoji_list': ['😎']}
]
result = api('createNewStickerSet', {
    'user_id': USER_ID,
    'name': 'my_pack_by_yourbot',
    'title': 'My Pack',
    'stickers': stickers
})
print('创建结果:', result)

# 3. 添加第三张贴纸
third_sticker = {'sticker': file3['result']['file_id'], 'emoji_list': ['🤖']}
result = api('addStickerToSet', {'user_id': USER_ID, 'name': 'my_pack_by_yourbot', 'sticker': third_sticker})
print('添加结果:', result)

# 4. 查询贴纸包信息
info = api('getStickerSet', {'name': 'my_pack_by_yourbot'})
print('贴纸包名称:', info['result']['title'])
print('贴纸数量:', len(info['result']['stickers']))

常见错误与注意事项

400 Bad Request: STICKERSET_NAME_INVALID：贴纸包名称不符合_by_<botusername>的命名规则。
400 Bad Request: STICKER_PNG_DIMENSIONS：静态贴纸尺寸不是512×512，或PNG/WEBP含有错误通道。
400 Bad Request: STICKER_TGS_NOT_VALID：动画贴纸TGS文件校验失败，请使用官方工具导出。
403 Forbidden: BOT_MISSING_RIGHTS：Bot未在BotFather中启用贴纸权限。
429 Too Many Requests：请求过于频繁，触发速率限制，请按Retry-After头等待。

总结

通过上述API，开发者可以完全自动化地管理贴纸包，无论是创建个人收藏还是运营品牌贴纸包，都能高效实现。建议进一步阅读Telegram官方文档中关于贴纸格式的详细规范，并使用Lottie编辑器制作动态贴纸，为用户带来更丰富的聊天体验。