new_lottery_bot/docs/EMOJI_SYSTEM.md

Премиум-эмодзи в чате и рассылках

Поддержка добавлена для общего чата, личных диалогов, рассылок в личные сообщения, каналы и группы. Сохраняются ID выбранных премиум-эмодзи, оформление текста и подписи к медиа. Новые миграции и переменные окружения для этой функции не требуются.

Использование

1. Выберите премиум-эмодзи в панели Telegram и отправьте сообщение в режиме чата либо создания рассылки.
2. Для подписи к фото, видео или документу добавьте эмодзи прямо в подпись.
3. Бот сохраняет выбранный вариант эмодзи, включая случаи, когда у нескольких премиум-вариантов одинаковый обычный символ.

Имя отправителя добавляется с сохранением оформления сообщения. Если заголовок не помещается вместе с текстом или подписью в лимит Telegram, бот отправляет заголовок отдельно и копирует исходное сообщение целиком.

Условия Telegram: новые сообщения с custom emoji могут отправлять боты с дополнительным именем пользователя, приобретённым через Fragment. Также они разрешены в сообщениях бота в личных чатах, группах и супергруппах, если владелец бота имеет активную подписку Telegram Premium. Исключение по подписке владельца в документации не распространяется на каналы. Эти условия задаёт Telegram; флаг внутри приложения их не меняет. Официальная документация.

Отправка обычного Unicode-символа передаёт обычный эмодзи. Премиум-вариант определяется полем custom_emoji_id, которое Telegram присылает вместе с выбранным эмодзи. Предварительная регистрация в каталоге для чата и рассылки не требуется.

Каталог администратора

• /add_emoji — сохранить один премиум-эмодзи и описание для шаблонов.
• /my_emojis — показать свои записи.
• /all_emojis — показать общий каталог.
• /delete_emoji — удалить свою запись. Главный администратор также может удалять записи других сотрудников.

Команда добавления принимает настоящий custom_emoji из Telegram. Описание ограничено 255 символами. Связь записи с администратором хранится через внутренний ID пользователя в БД; интерфейс принимает Telegram ID. Повторная регистрация даёт понятный ответ без повреждения сессии БД.

Реализация

src/utils/telegram_messages.py содержит общий путь передачи сообщений:

• без заголовка используется copyMessage, сохраняющий исходное сообщение;
• при добавлении имени передаются исходные entities / caption_entities с поправкой позиции на длину заголовка в UTF-16;
• parse_mode=None предотвращает повторный разбор пользовательского текста;
• длинные сообщения копируются без обрезания текста или разрыва эмодзи.

Общий чат, P2P и оба вида рассылок используют этот путь. Ошибка оформления сообщения, включая недопустимый custom emoji, учитывается как ошибка доставки и не блокирует получателя для следующих рассылок.

Для программно создаваемого шаблона из обычного текста доступен HTML-рендер каталога:

from src.core.emoji_message_helper import get_emoji_aware_text

html = await get_emoji_aware_text(session, "🎲 Розыгрыш начался!")
await bot.send_message(chat_id, html, parse_mode="HTML")

Вход этого помощника — обычный текст. Он экранирует HTML и добавляет настоящие <tg-emoji emoji-id="...">...</tg-emoji>. Входящие пользовательские сообщения сохраняют собственные entities и не проходят через каталог замен.

Проверка

tests/test_premium_emoji.py проверяет ID и UTF-16-позиции нескольких эмодзи, вложенное оформление, подписи к шести типам медиа, предельную длину текста/подписей, P2P-доставку, копирование рассылок, ошибки Telegram и настоящий маршрут регистрации эмодзи. Ответы Telegram в тестах подменены; права конкретного рабочего бота и отображение в клиенте Telegram нужно проверить после установки релиза.

Итоговый прогон 13 сентября 2026: PostgreSQL — 61 тест прошёл; SQLite — 60 прошли, один тест миграций пропущен. Ruff, compileall и проверка отслеживаемых секретов прошли. Изменения подготовлены локально; установки этой версии на рабочий сервер в рамках проверки не было.