چطور در ربات تلگرام ایموجی پرمیوم (Custom Emoji) ارسال کنیم؟ (با کد telebot)

ایموجی های پرمیوم همون ایموجی های متحرک و رنگی تلگرام هستن. ربات میتونه اون ها رو تو پیام، کپشن و دکمه ها نشون بده. تو این راهنما یاد میگیری شرایطش چیه، آیدی ایموجی رو از کجا بیاری و چطور با telebot بفرستی.

ایموجی پرمیوم چیه؟

ایموجی های سفارشی (Custom Emoji) ایموجی های ویژه ای هستن که ظاهر متحرک و طراحی اختصاصی دارن. ارسالشون تو چت معمولی فقط برای کاربران پرمیوم ممکنه. ربات ها هم با شرایطی که پایین توضیح میدم میتونن بفرستنشون.

پیش نیازها

• یه ربات تلگرام با توکن (از BotFather)
• کتابخانه telebot (پکیج pyTelegramBotAPI) که آپدیت باشه
• custom_emoji_id ایموجی موردنظر (بخش بعدی)

1. یکی از این دو شرط برای مجوز استفاده از ایموجی سفارشی:ربات یوزرنیم اضافه از Fragment خریده باشه. با این شرط تو همه جا کار میکنه.
2. صاحب ربات تلگرام پرمیوم داشته باشه. این شرط از Bot API 9.4 (فوریه ۲۰۲۶) اضافه شده و فقط برای پیام هایی کار می‌کنه که مستقیما توسط ربات تو چت خصوصی، گروه یا سوپرگروه فرستاده میشن. برای کانال و حالت اینلاین کافی نیست.

اگه هیچ کدوم از این شرط ها برقرار نباشه، تلگرام ایموجی سفارشی رو نادیده میگیره و فقط ایموجی معمولیِ داخل تگ نمایش داده میشه.

چطور custom_emoji_id رو پیدا کنم؟

هر ایموجی پرمیوم یه آیدی عددی یکتا داره (مثلاً 5368324170671202286).

روش ۱: خوندن از پیام. یه ایموجی پرمیوم رو برای رباتت بفرست. آیدی تو entityهای پیام هست:

import telebot

bot = telebot.TeleBot("YOUR_BOT_TOKEN")

@bot.message_handler(content_types=['text'])
def get_emoji_id(message):
    for e in message.entities or []:
        if e.type == 'custom_emoji':
            bot.reply_to(message, f"ID: {e.custom_emoji_id}")

bot.infinity_polling()

روش ۲: از روی پک ایموجی. اگه اسم پک ایموجی سفارشی رو داری:

sticker_set = bot.get_sticker_set("PACK_NAME")
for s in sticker_set.stickers:
    print(s.custom_emoji_id, s.emoji)

متد getCustomEmojiStickers برعکس کار میکنه: آیدی میگیره و اطلاعات استیکر برمیگردونه. پس برای پیدا کردن آیدی به درد نمیخوره، ولی برای چک کردن معتبر بودن یه آیدی خوبه.

روش ۱: ارسال با HTML (پیشنهادی)

import telebot

BOT_TOKEN = "YOUR_BOT_TOKEN"
bot = telebot.TeleBot(BOT_TOKEN)

EMOJI_ID = "5368324170671202286"

@bot.message_handler(commands=['start'])
def send_premium_emoji(message):
    text = (
        'سلام! این یه ایموجی پرمیومه: '
        f'<tg-emoji emoji-id="{EMOJI_ID}">🔥</tg-emoji>'
    )
    bot.send_message(message.chat.id, text, parse_mode='HTML')

bot.infinity_polling()

• تگ <tg-emoji> فقط با parse_mode='HTML' کار می‌کنه.
• داخل تگ باید دقیقا یک ایموجی معمولی بذاری. اگه ربات مجوز نداشته باشه یا کاربر نتونه ایموجی سفارشی رو ببینه، همین نمایش داده میشه.

روش ۲: ارسال با MarkdownV2

سینتکس: ![ایموجی_جایگزین](tg://emoji?id=ID)

تو MarkdownV2 کاراکترهای _ * [ ] ( ) ~ > # + - = | { } . ! باید با \ escape بشن. مثال زیر با رعایت این قانون نوشته شده:

text = (
    'سلام\\! این یه ایموجی پرمیومه: '
    f'![🔥](tg://emoji?id={EMOJI_ID})'
)

bot.send_message(message.chat.id, text, parse_mode='MarkdownV2')

برای متن‌های پویا از telebot.formatting.escape_markdown استفاده کن. اگه می‌خوای راحت تر باشی، HTML ساده‌تره.

ایموجی پرمیوم روی دکمه شیشه ای

متن دکمه ها HTML یا Markdown پردازش نمیکنه، پس نمیشه تگ <tg-emoji> رو تو متن دکمه گذاشت. از Bot API 9.4 فیلد مخصوص icon_custom_emoji_id اضافه شده که ایموجی رو قبل از متن دکمه نشون میده:

from telebot.types import InlineKeyboardMarkup, InlineKeyboardButton

keyboard = InlineKeyboardMarkup()
button = InlineKeyboardButton(
    text="دکمه",
    callback_data="test",
    icon_custom_emoji_id=EMOJI_ID
)
keyboard.add(button)

bot.send_message(
    message.chat.id,
    "یه دکمه با ایموجی پرمیوم:",
    reply_markup=keyboard
)

• ربات برای ارسال پیام باید مجوز استفاده از ایموجی سفارشی داشته باشه (همون دو شرط بالا).
• نسخه telebot باید این پارامتر رو پشتیبانی کنه. اگه خطای unexpected keyword argument گرفتی، کتابخانه رو آپدیت کن (pip install -U pyTelegramBotAPI). اگه هنوز پشتیبانی نشده بود، باید reply_markup رو به‌صورت JSON خام بفرستی.

ایموجی پرمیوم در کپشن مدیا

caption = f'این عکس با ایموجی پرمیومه: <tg-emoji emoji-id="{EMOJI_ID}">🔥</tg-emoji>'

bot.send_photo(
    message.chat.id,
    photo="https://example.com/image.jpg",
    caption=caption,
    parse_mode='HTML'
)

خطاهای رایج

Bad Request: can't parse entities

• علت: تگ <tg-emoji> درست بسته نشده، parse_mode تنظیم نشده، یا تو MarkdownV2 کاراکتر خاصی (مثل ! یا .) escape نشده.
• راه حل: parse_mode رو چک کن، تگ رو کامل ببند و در MarkdownV2 همه کاراکترهای خاص رو escape کن.

فقط ایموجی ساده نمایش داده میشه

• علت: ربات مجوز استفاده از ایموجی سفارشی نداره. مثلا صاحب ربات پرمیوم نیست، ربات یوزرنیم Fragment نخریده، یا پیام تو کانال/اینلاین فرستاده شده. آیدی اشتباه هم میتونه علت باشه.
• راه حل: شرایط بخش «پیش نیازها» رو چک کن و آیدی رو با getCustomEmojiStickers یا خوندن از entityها تایید کن.

تگ <tg-emoji ...> به‌صورت متن خام تو دکمه دیده میشه

• علت: ایموجی رو تو text دکمه گذاشتی.
• راه حل: از icon_custom_emoji_id استفاده کن.

unexpected keyword argument 'icon_custom_emoji_id'

• علت: نسخه telebot قدیمیه.
• راه حل: کتابخانه رو آپدیت کن