README

Драйвер Telegram для skeeks/cms-communication: клиенты пишут боту или в группу, где состоит бот, переписка приходит в CRM, менеджер отвечает из CRM. Всё общее (приём, порядок, переписки, собеседники, файлы, права, отправка) — в cms-communication (README, раздел «Боты мессенджеров»); здесь только протокол Telegram Bot API (https://core.telegram.org/bots/api, сверено с версией 10.3 от 24.08.2026).

Установка

composer require skeeks/cms-communication-telegram

Пакет сам регистрирует драйвер telegram (components.communication.drivers).

Как создать бота

В Telegram открыть @BotFather → /newbot, задать название и имя бота (оканчивается на bot). BotFather выдаст токен 123456789:AA….
В CRM: «Коммуникации» → «Боты» → «Добавить», драйвер Telegram, вставить токен. Токен хранится зашифрованным; в форме, журналах и ошибках его не видно. «Проверить бота» вызывает getMe и запоминает id и имя бота.
Режим «Вебхук» — для сайта с HTTPS: CRM сама ставит setWebhook на https://<сайт>/~comm-bot/<id подключения> со своим секретом (secret_token, заголовок X-Telegram-Bot-Api-Secret-Token) и раз в час сверяет подписку (getWebhookInfo; свежая ошибка доставки видна в карточке бота). Режим «Опрос» — для сайта без HTTPS (getUpdates со сдвигом offset; с вебхуком опрос невозможен, и наоборот).

Группы и режим приватности

По умолчанию бот в группе работает в режиме приватности: видит только команды ему (/task@имя_бота …), ответы на свои сообщения и служебные события (вход и выход участников, смена названия). Всю переписку группы бот видит, если:

сделать его администратором группы, или
выключить режим в @BotFather (/setprivacy → бот → Disable) и добавить бота в группу заново — без этого изменение не действует.

Что бот видит, показывает карточка бота («Сообщения в группах», по can_read_all_group_messages из getMe). Сообщения других ботов Telegram не передаёт ни в каком режиме. Список участников группы ботам не дают: известны администраторы (getChatAdministrators) и те, кто писал, вошёл или вышел; вход и выход видны и бота-администратора (chat_member).

Когда группа становится супергруппой, у неё новый id: прежний чат в CRM отмечается «бота нет в чате», переписка продолжается в новом чате.

Что умеет

Приём: сообщения, правки, посты каналов, нажатия кнопок, бот добавлен, стал администратором, удалён или заблокирован (my_chat_member), участники. Ключ события — update_id: повтор того же события не записывается второй раз.
Разбор: ответ на сообщение, пересылка (автор текстом), скрытые ссылки дописываются после слов, фото (самый крупный размер), документы, видео, голосовые, аудио, видеосообщения; стикер, место, опрос — текстом. Сообщение от имени группы или канала — автор группа. /start <ключ> в личке — запуск бота с ключом привязки (до 64 знаков A-Za-z0-9_-, ссылка https://t.me/<бот>?start=<ключ>). Контакт засчитывается своим, только если он прислан в личке и contact.user_id — сам отправитель.
Реакции: кто и какие emoji поставил на сообщение (message_reaction, приходят, только если бот — администратор группы; реакции других ботов и анонимные счётчики каналов не приходят). Из CRM бот ставит одну реакцию (setMessageReaction) из TelegramDriver::REACTIONS. Подписка вебхука, оформленная до 1.1.0, обновляется сама (webhookOutdated()).
Файлы: скачиваются через getFile (до 20 МБ — ограничение Bot API; больше — отказ с причиной в сообщении).
Фото группы и собеседника — getChat; фото администраторов группы — getUserProfilePhotos.
Отправка: текст до 4096 знаков (длиннее — частями), оформление HTML Telegram (b, i, u, s, a, code, pre, blockquote; абзацы — переносы строк), ответ с цитатой (если исходное удалено — без неё), кнопки-ссылки и кнопки-действия, «Поделиться номером» (клавиатура с запросом контакта, только в личке), картинки JPEG/PNG до 10 МБ — фото, остальное — файлом.
Частота: не чаще 1 сообщения в секунду в чат и 20 в минуту в группу (core.telegram.org/bots/faq). Ответ 429 — сообщение ждёт в очереди retry_after секунд и досылает оставшиеся части; 403 — бот заблокирован или удалён из чата; другие отказы — причина в сообщении; 5xx и сеть — исход неизвестен, повторно не отправляется.

Доступ к Telegram из России

С серверов в России api.telegram.org может быть недоступен. У бота есть настройки «Прокси для запросов к API» (http://логин:пароль@узел:порт, socks5://…; хранится зашифрованным) и «Адрес API» (свой сервер Bot API). Токен стоит в адресе каждого запроса Telegram, поэтому прокси нужен с туннелем (CONNECT), чтобы запросы шли по HTTPS насквозь. Вебхук Telegram доставляет на сайт напрямую: для приёма прокси не нужен.

Как включить: в карточке бота → «Редактировать» → «Прокси для запросов к API» ввести http://логин:пароль@узел:порт (или socks5h://…; спецсимволы пароля — в виде %40 и т. п.) и сохранить; «Проверить бота» вызовет getMe через прокси. Через прокси идут все запросы драйвера: отправка, опрос, установка вебхука и скачивание файлов. Если не отвечает сам прокси, ошибка так и говорит («Прокси не отвечает…»); пароль прокси и токен в ошибки не попадают. Пустое поле — запросы идут напрямую, как раньше.

Тесты

php tests/telegram.php — разбор и запросы на записанном транспорте, без сети и базы.
TG_LIVE=1 TG_CONNECTION_ID=… php tests/telegram-live-poll.php на локальном сайте с communication.botReceive = false — опрос нового тестового бота в течение TG_SECONDS секунд, события сохраняются как у задачи опроса и применяются обработчиком сайта. Бот с вебхуком (рабочий) отвергается; скрипт ничего не отправляет.

skeeks / cms-communication-telegram

Package info

Security

Statistics