Уведомления в Telegram

Компонент отправляет уведомления сайта в Telegram через вашего бота. Пользователи подключают Telegram в профиле и сами выбирают, какие уведомления получать. Администраторы и рабочие группы получают служебные события сайта с кнопками решений. Новые записи сайта публикуются в ваши каналы. Если хостинг не достаёт до Telegram, работает через ваш адрес API или прокси.

Что делает компонент

• Дублирует уведомления сайта в Telegram: комментарии, ответы, личные сообщения, подписки, оценки и уведомления других компонентов, которые используют штатную систему уведомлений InstantCMS.
• Присылает служебные события администраторам лично и в рабочие группы Telegram, в том числе в отдельную тему группы: новый пользователь, материал или комментарий на модерации, новый комментарий, заявка с формы, новый материал, удаление пользователя.
• Даёт решать прямо в Telegram: «Одобрить» материал или комментарий на модерации, «Удалить» комментарий. Решение принимается штатной модерацией сайта от имени того, кто нажал, — см. «Кнопки в сообщениях».
• Присылает заявки «Форм» тем, кому они нужны: у каждой формы свои получатели и своя рабочая группа, в сообщении все поля заявки — см. «Заявки „Форм“».
• Публикует новые записи в каналы Telegram: фото-обложка с подписью — заголовок, краткое описание и кнопка «Читать на сайте» — см. «Автопостинг в каналы».
• Бережёт тишину: в тихие часы сообщения приходят без звука, под каждым личным уведомлением — кнопки «Настроить» и «Отключить».
• Работает там, где Telegram ограничен: свой адрес API (например, Cloudflare Worker) или прокси — см. «Если Telegram недоступен».
• Не мешает работе сайта: сообщения уходят через штатную очередь, ядро CMS не изменяется, вся админка — на штатных таблицах InstantCMS.

Что понадобится

Бот и токен

1. Откройте в Telegram @BotFather и отправьте /newbot.
2. Задайте имя бота (его видят пользователи, например «Уведомления сайта») и адрес, оканчивающийся на bot.
3. BotFather пришлёт токен вида 123456789:AA… — скопируйте его.

Установка и обновление

1. Сделайте резервную копию файлов и базы данных сайта.
2. Откройте Дополнения → Установить пакет дополнения, выберите ZIP-архив и нажмите «Продолжить».
3. Для обновления используйте архив с пометкой update. Настройки, подключённые пользователи, каналы и журнал сохранятся.

При установке создаются шесть таблиц {префикс}tgnotify_* и две задачи планировщика. Ядро CMS не изменяется.

Настройка за 5 минут

Откройте Компоненты → Уведомления в Telegram. На странице «Состояние» есть список шагов, выполненные отмечаются галочкой.

1. Опции → Бот: вставьте токен в поле «Токен бота» и сохраните.
2. Состояние → «Проверить подключение». Должно появиться «Подключение работает: бот „…“». Если ошибка связи — см. «Если Telegram недоступен».
3. Состояние → «Подключить webhook». Должно появиться «Webhook подключён».
4. Подключите Telegram себе: Профиль → Настройки → Уведомления → «Подключить Telegram» → в чате с ботом нажмите «Запустить». Бот ответит «Аккаунт … подключён».
5. Состояние → «Отправить тест себе». В Telegram придёт тестовое сообщение.

Если Telegram недоступен с хостинга

С российских хостингов адрес api.telegram.org бывает недоступен или отвечает с перебоями: «Проверить подключение» в этом случае сама пробует запасные адреса серверов Telegram.

Запасной адрес — подбирается сам

Часто не отвечает только тот адрес, который хостинг получает из DNS, а другие серверы Telegram доступны. Нажмите Состояние → «Проверить подключение»: если основной адрес молчит, компонент по очереди пробует запасные и сохраняет тот, что ответил, в поле «IP-адрес api.telegram.org». Сообщение об этом появится вверху страницы. Если позже основной адрес снова заработает, проверка вернёт прямую связь сама.

Сайт по-прежнему обращается к api.telegram.org и проверяет его сертификат — меняется только сервер, к которому идёт соединение. Адрес можно вписать и вручную из официального списка сетей Telegram; поле действует, когда «Свой адрес API» пуст.

Если не ответил ни один адрес, хостинг закрыл Telegram целиком. На «Состоянии» появится красный блок «Нет связи с Telegram» с тремя выходами: посредник Cloudflare Worker, свой прокси или письмо в поддержку хостинга (готовый текст там же).

Свой адрес API

Посредник, который принимает запросы сайта и передаёт их в Telegram. Проще всего — бесплатный Cloudflare Worker:

1. Зарегистрируйтесь на cloudflare.com, откройте Workers & Pages → Create → Worker.
2. Замените код воркера на этот и нажмите Deploy:

   export default {
     async fetch(request) {
       const url = new URL(request.url);
       url.hostname = 'api.telegram.org';
       return fetch(new Request(url, request));
     }
   };

3. Скопируйте адрес воркера, например https://tg-proxy.ваше-имя.workers.dev, и вставьте его в поле «Свой адрес API» (без «/» в конце). Сохраните и нажмите «Проверить подключение».

Подойдёт и свой Bot API Server или любой обратный прокси к api.telegram.org.

Прокси

Если у вас есть прокси-сервер, укажите его в поле «Прокси»: socks5://логин:пароль@адрес:порт или http://адрес:порт. Через него пойдут запросы сайта к Telegram; проверка сертификата Telegram остаётся включённой. Пароль прокси скрыт в форме и не попадает в журналы.

Опции

Пользователи

• Разрешить пользователям подключать Telegram. Выключите, если Telegram нужен только администраторам.
• Группы, которым доступно подключение.
• Уведомления, включённые сразу после подключения. Если ничего не выбрано, включаются все. Пользователь потом меняет набор у себя в профиле.
• Срок действия ссылки подключения — по умолчанию 15 минут.

Администраторам

• Отмеченные события получает лично каждый администратор сайта, который подключил Telegram в своём профиле. Чтобы добавить других получателей, например группу «Модераторы», выберите её в поле «Дополнительные группы получателей».
• В рабочую группу события направляются отдельно, в её настройках: можно получать всё в группе и выключить личные сообщения.
• О собственных действиях администратор уведомление не получает.

Тихие часы

Блок Опции → Тихие часы: поля «Начало» и «Конец» задают один период, например начало 22:00 и конец 08:00. В это время сообщения приходят без звука — и подписчикам, и в рабочие группы; они не задерживаются, утром уже лежат в чате. Период может переходить через полночь и действует каждый день. Ниже — «Весь день без звука»: отмеченные дни недели, например суббота и воскресенье, проходят без звука круглые сутки. Время — по часам сервера сайта.

Формат и доставка

• Заголовок сообщения — первая строка каждого уведомления жирным, например название сайта.
• Отправлять через очередь — оставьте включённым: страницы сайта не ждут ответа Telegram.
• Хранить журнал — сколько дней хранить журнал доставки.

Автопостинг в каналы

• Кто видит галочку «Не публиковать в Telegram» в форме добавления записи. Администраторы видят её всегда.

Сайт без HTTPS, тестовый сайт или webhook не доходит

Telegram присылает события только на HTTPS-адрес с действующим сертификатом. Для тестового сайта и в случае, когда события Telegram не доходят до сайта, выберите Опции → Получение событий от Telegram → Опрос раз в минуту. Компонент сам забирает события через планировщик: подключение пользователя и нажатия кнопок срабатывают в течение минуты.

Что видит пользователь

Имя подключённого аккаунта берётся из Telegram. У старых перенесённых привязок компонент восстанавливает его автоматически через настроенное соединение с Telegram; до получения имени показывает ник пользователя сайта. Технический номер аккаунта вместо имени не выводится. Переподключать бота ради имени не нужно.

• Профиль → Настройки → Уведомления → блок «Уведомления в Telegram»: кнопка «Подключить Telegram», после подключения — галочки, какие уведомления присылать.
• В Telegram уведомление приходит в том же виде, что и на сайте, с кнопками «Открыть», «⚙ Настроить» и «🔕 Отключить».
• «🔕 Отключить» ставит уведомления на паузу, бот присылает кнопку «🔔 Включить уведомления». То же делают команды /stop и /start.
• Отключить Telegram совсем — ссылка «Отключить Telegram» в профиле. Если пользователь остановит бота, отправка ему прекратится автоматически.

Кнопки в сообщениях

После решения в тот же чат (и ту же тему) приходит итог: «✅ Материал одобрен: «…» — имя модератора». Повторное нажатие ответит «Уже решено на сайте».

Рабочие группы

«Дополнительные группы пользователей сайта» в опциях — группы учётных записей InstantCMS. Они определяют, кому присылать служебные сообщения лично, и не создают чат в Telegram. Рабочая группа Telegram — отдельный существующий чат, куда добавлен бот; события для него выбираются в «Каналы и чаты». Администраторы сайта получают служебные события лично автоматически, если подключили бота; галочки личных уведомлений в профиле не заменяют опции «Администраторам».

1. Создайте группу в Telegram (или откройте существующую) и добавьте в неё бота сайта.
2. Откройте Компоненты → Уведомления в Telegram → Каналы и чаты. Группа появится в списке сама. Администраторам, подключившим Telegram, бот пришлёт «Бот добавлен в группу».
3. Нажмите «Настроить» и в блоке «Служебные уведомления» отметьте, что присылать: новые пользователи, модерация, комментарии, заявки форм, новые материалы, удаления, события других дополнений.
4. По желанию нажмите «Тестовое сообщение» в строке группы.

Темы группы

Если в группе включены темы (форум), уведомления можно направить в отдельную тему: откройте нужную тему и отправьте в ней команду /topic. Бот ответит «Готово: уведомления сайта будут приходить в эту тему». Команда в общей теме возвращает уведомления туда. Выбрать тему может только администратор сайта, подключивший Telegram. Номер темы виден и меняется в настройках группы на сайте — поле «Тема группы».

Чтобы заявки и модерация шли в разные темы, удобнее две группы: например, «Заявки» и «Модерация».

Заявки «Форм»

Получателей выбирают отдельно у каждой формы: личные аккаунты и, при необходимости, рабочие группы. Адреса в поле получателей служат для поиска пользователей сайта; письмо этот блок не отправляет. Если человек одновременно выбран штатным получателем формы и получателем Telegram, ему приходит одна заявка с полями формы. При ошибке обязательного поля заявка не рассылается.

У каждой формы компонента «Формы» в настройках (Компоненты → Формы → форма → Изменить) появляется вкладка «Уведомления в Telegram»:

• Получатели заявок в Telegram — пользователи сайта (поиск по имени или e-mail). Заявка придёт тем из них, кто подключил Telegram.
• Рабочие группы Telegram — группы из «Каналы и чаты».

Получатели заявки в Telegram — выбранные во вкладке и те, кому форма штатно отправляет «Уведомление на сайте» или «Автору записи» (её Опции → Куда отправлять форму). Каждый из них получает одно сообщение с данными заявки — вместо копии штатного уведомления.

Если у формы нет ни тех, ни других получателей, заявки уходят по опциям компонента: администраторам лично и в рабочие группы, где отмечены заявки форм.

В сообщении — название формы, заполненные поля «Поле: значение», ссылки на приложенные файлы и кто отправил (имя или «Гость», IP). Под сообщением — кнопка «Страница с формой». Почтовый шаблон формы не меняется.

Автопостинг в каналы Telegram

Обложка из каталога загрузок сайта отправляется файлом; если Telegram её не принимает, причина доставки без обложки видна в журнале публикаций.

Новые записи сайта публикуются постами в ваши каналы через того же бота. С обложкой пост — фото с подписью: заголовок жирным, краткое описание и кнопка «Читать на сайте»; без обложки — текст с кнопкой. Всё настраивается во вкладке Каналы и чаты.

Подключить канал

1. Откройте канал в Telegram → «Управление каналом» → «Администраторы» → добавьте бота сайта и оставьте право «Публикация сообщений».
2. Откройте Каналы и чаты. Канал появится в списке сам. Администраторам бот пришлёт «Бот добавлен в канал».
3. Нажмите «Проверить права» — в колонке «Состояние» должно быть «Бот на месте».
4. Нажмите «Настроить», включите «Публиковать новые записи сайта» и выберите типы контента.

Настройки канала

Какие записи публикуются

• Публикуются новые записи выбранных типов, как только они появились на сайте: сразу, после одобрения модератором (в том числе кнопкой в Telegram), после публикации черновика или в дату отложенной публикации.
• Не публикуются правки, записи на модерации и в черновиках, скрытые и доступные не всем. Одна запись попадает в канал один раз.
• Галочка «Не публиковать в Telegram» в форме добавления записи не даёт записи уйти в каналы.

Публикации

Вкладка Публикации — все записи, ушедшие в каналы: дата, запись, канал, состояние («В очереди», «Опубликовано», «Ошибка», «Пропущено») и ссылка «Пост ↗». Действие «Опубликовать» у ошибки или пропуска отправляет запись ещё раз.

Админка компонента

Все списки — штатные таблицы InstantCMS. На главной панели управления есть блок «Уведомления в Telegram».

Лицензия

Ключ вводить не нужно. После установки компонент сам получает пробную лицензию на 72 часа, автор подтверждает покупку, и лицензия становится бессрочной для домена сайта.

• Состояние — на вкладке Лицензия. Чтобы ускорить подтверждение, укажите там ник на OCMarket или номер заказа.
• Если сайт не может связаться с сервером лицензий, автор пришлёт готовую строку лицензии — вставьте её на той же вкладке.
• Без подтверждения выключаются только уведомления и автопостинг в Telegram. Сайт работает как обычно, данные сохраняются.
• Стенды и адреса разработки (localhost, *.local, *.test, адрес по IP) работают без лицензии.
• Серверу лицензий передаются только домен сайта, случайный идентификатор установки, версии компонента, InstantCMS и PHP и ваша пометка.

Вместе с «Уведомлениями в MAX»

Компонент работает на одном сайте с «Уведомлениями в MAX» того же автора: у пользователя в профиле два блока, и он выбирает, куда получать уведомления — в Telegram, в MAX или в оба. Настройки, группы и журналы у компонентов свои.

Если что-то не так

Удаление

Сначала нажмите «Отключить webhook», затем Компоненты → Уведомления в Telegram → Удалить. Таблицы с подписчиками, каналами, журналом и лицензией остаются в базе, чтобы после повторной установки пользователям не пришлось подключаться заново. Папку docs/_shared удалять не нужно: это общее оформление руководств других дополнений автора.