Telegram

Отправляйте сообщения контактам в Telegram через бота вашего приложения — личное сообщение тому, кто открыл бота, — или рассылайте в группу или канал, где бот состоит. Один канал умеет и то, и другое.

41-ФЗ. Банки, операторы связи, НФО, маркетплейсы и платформы с аудиторией больше 500 000 не вправе информировать клиентов через Telegram; такое приложение включает профиль 41-ФЗ в настройках и использует MAX — см. Соответствие закону.

Шаг 1 — Создайте бота

1. Откройте Telegram и найдите @BotFather
2. Отправьте команду /newbot
3. Введите отображаемое имя (например, My App Notifications)
4. Введите имя пользователя, оканчивающееся на bot (например, myapp_notify_bot)
5. BotFather ответит вашим токеном бота:

1234567890:AAF-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Держите этот токен в секрете — он даёт полный контроль над вашим ботом.

Шаг 2 — Добавьте канал

Каналы → Новый канал → Telegram, вставьте токен, нажмите «Проверить связь» и сохраните. При сохранении PushData проверяет токен (getMe), запоминает имя бота и направляет вебхук бота в PushData (setWebhook с секретом, который бот присылает в X-Telegram-Bot-Api-Secret-Token). ID чата необязателен: оставьте поле пустым, если канал нужен только для личных сообщений.

Шаг 3 — Подключите контакты

У каждого контакта есть ссылка Telegram (Контакты → контакт → «Ссылка Telegram»; telegramLink в GraphQL API):

https://t.me/myapp_notify_bot?start=<подписанный payload контакта>

Отправьте её человеку любым способом — письмом, внутри приложения, QR-кодом. Открыв бота и нажав «Start», он привязывает свой личный чат к контакту: вебхук бота получает /start <payload> и записывает в контакт telegramChatId (telegram_chat_id в REST). Payload подписан, поэтому нельзя привязать чужой контакт к своему чату. Telegram разрешает боту писать только тем, кто его запустил, — поэтому вход именно через ссылку.

Тот, кто просто найдёт бота и напишет ему, становится контактом telegram:<id чата> — ему тоже можно писать. Когда человек блокирует бота, telegramChatId контакта очищается — отправки ему прекращаются без ошибок доставки (чат запоминается в metadata контакта как telegram_blocked_chat_id); разблокировка бота привязывает чат обратно к тому же контакту.

Шаг 4 — Отправляйте

Уведомление с типом канала Telegram и target (all, user_ids, contact_ids) уходит всем выбранным контактам с telegramChatId; без target — в чат, указанный в канале (группу или канал); запрос без target и без ID чата отклоняется с 400. В дашборде шаг «Получатели» предлагает тот же выбор: «Чат Telegram», «Все, кто подключил бота», «Выбрать контакты». SEND-шаг воркфлоу пишет контакту запуска, если тот подключил бота, иначе — в чат канала.

Текст: заголовок жирным, тело, затем данные блоком кода; лимит Telegram — 4096 символов. message_id, который возвращает Telegram, виден в журнале доставки.

Необязательно — группа или канал для рассылки

1. Добавьте бота в группу участником (или администратором канала)
2. Узнайте ID чата: у групп он отрицательный, у каналов начинается с -100 (например, -1001234567890). Пока канал не сохранён, https://api.telegram.org/bot<TOKEN>/getUpdates показывает его как "chat":{"id": …} после любого сообщения в группе; после регистрации вебхука getUpdates отвечает 409, поэтому узнайте ID заранее или временно снимите вебхук (deleteWebhook) и после этого заново проверьте канал
3. Впишите ID в поле ID чата канала

Справочник по полям

Ошибки

Вебхук PushData принимает обновления только с секретом канала; всё остальное получает 401 и отбрасывается. Новые контакты telegram:<id чата> создаются в пределах лимита контактов тарифа: на лимите бот по-прежнему отвечает, но контакт не создаётся.