Подключение Telegram

Telegram — основной канал поддержки. Бот принимает входящие сообщения пользователей через вебхук и создаёт для каждого обращения отдельную тему (топик) в приватной Telegram-группе поддержки. Ответы менеджеров из этой темы доставляются пользователю обратно в Telegram.

Эндпоинт вебхука: POST /api/telegram/bot

Предварительные требования

Перед подключением убедитесь, что проект развёрнут по одной из инструкций:

• Установка через Docker Compose
• Установка на хостинг

Для локальной разработки вебхук можно поднять через Cloudflare Tunnel (macOS).

1. Создание бота в @BotFather

1. Откройте @BotFather в Telegram.
2. Отправьте команду /newbot.
3. Задайте имя и имя пользователя (username) для бота.
4. Скопируйте полученный токен — он понадобится для TELEGRAM_BOT_TOKEN.

2. Создание группы поддержки

1. Создайте новую приватную Telegram-группу.
2. Добавьте в неё бота и назначьте его администратором.
3. В настройках группы включите возможность создавать темы (топики) — именно в виде тем будут отображаться обращения пользователей.

3. Получение ID группы

Чтобы узнать ID группы, временно добавьте в неё бота @getMyId или аналогичный. Бот пришлёт числовой идентификатор вида -1001234567890 — это значение для TELEGRAM_GROUP_ID. После получения ID удалите вспомогательный бот из группы.

4. Настройка переменных окружения

Откройте .env на сервере и добавьте:

TELEGRAM_BOT_TOKEN="токен_бота_из_BotFather"
TELEGRAM_SECRET_KEY="придумайте_произвольный_секретный_ключ"
TELEGRAM_GROUP_ID="-1001234567890"

Переменная	Описание
TELEGRAM_BOT_TOKEN	Токен основного Telegram-бота, полученный от @BotFather
TELEGRAM_SECRET_KEY	Произвольная строка для верификации запросов от Telegram (параметр secret_token)
TELEGRAM_GROUP_ID	ID приватной группы с топиками, куда пересылаются обращения

TELEGRAM_SECRET_KEY — произвольная строка. Telegram будет передавать её в заголовке X-Telegram-Bot-Api-Secret-Token при каждом вебхук-запросе, а приложение проверяет совпадение со значением из .env.

AI-помощник

Если ответы отправляет AI-помощник, понадобится отдельный бот — задайте его токен в TELEGRAM_AI_BOT_TOKEN. Подробнее: Подключение AI-помощника.

Перезапустите контейнер, чтобы конфиг применился:

docker compose restart app

5. Регистрация вебхука

Telegram не имеет веб-интерфейса для регистрации вебхука — она выполняется через API. Откройте в браузере следующий URL, подставив свои данные:

https://api.telegram.org/bot{ТОКЕН}/setWebhook?url=https://{ДОМЕН}/api/telegram/bot&max_connections=45&drop_pending_updates=true&secret_token={СЕКРЕТНЫЙ_КЛЮЧ}

Замените:

• {ТОКЕН} — токен бота из @BotFather;
• {ДОМЕН} — ваше доменное имя;
• {СЕКРЕТНЫЙ_КЛЮЧ} — значение TELEGRAM_SECRET_KEY из файла .env.

При успешной привязке Telegram API вернёт ответ:

{
    "ok": true,
    "result": true,
    "description": "Webhook was set"
}

Привязка к IP-адресу

Если Telegram периодически сбрасывает вебхук, добавьте в URL параметр &ip_address={IP_СЕРВЕРА} — это закрепляет вебхук за конкретным адресом. Подробнее: Типичные ошибки.

6. Проверка регистрации вебхука

Откройте в браузере или выполните в терминале:

curl "https://api.telegram.org/bot{ТОКЕН}/getWebhookInfo"

В ответе поле url должно содержать https://{ДОМЕН}/api/telegram/bot, а pending_update_count — быть близким к нулю.

7. Полный чек-лист подключения

• [ ] Бот создан в @BotFather, токен получен
• [ ] Создана приватная группа, бот добавлен администратором
• [ ] В настройках группы включены темы (топики)
• [ ] ID группы получен через @getMyId
• [ ] TELEGRAM_BOT_TOKEN задан в .env
• [ ] TELEGRAM_SECRET_KEY задан в .env
• [ ] TELEGRAM_GROUP_ID задан в .env
• [ ] Контейнер перезапущен (docker compose restart app)
• [ ] Вебхук зарегистрирован через API (шаг 5)
• [ ] Регистрация вебхука подтверждена (шаг 6)
• [ ] Тестовое сообщение от пользователя создаёт тему в группе поддержки
• [ ] Ответ менеджера из темы доставляется пользователю в Telegram

8. Диагностика проблем

8.1. Вебхук не регистрируется

• Убедитесь, что домен доступен извне и работает по HTTPS.
• Проверьте корректность токена в URL.
• Telegram принимает вебхуки только на портах 80, 88, 443 и 8443.

8.2. Эндпоинт возвращает 403

• Убедитесь, что TELEGRAM_SECRET_KEY в .env совпадает со значением secret_token, указанным при регистрации вебхука.

8.3. Сообщение не появляется в группе поддержки

• Убедитесь, что бот добавлен в группу и назначен администратором.
• Проверьте, что в группе включены темы и задан корректный TELEGRAM_GROUP_ID.
• Проверьте логи приложения:

docker exec -it pet tail -f storage/logs/laravel.log

Убедитесь, что очередь работает:

docker exec -it pet php artisan queue:work

8.4. Вебхук периодически сбрасывается

Telegram может сбрасывать вебхук при блокировке IP. Удалите и зарегистрируйте вебхук заново, добавив параметр ip_address. Подробнее: Типичные ошибки.

8.5. Удаление вебхука

curl "https://api.telegram.org/bot{ТОКЕН}/deleteWebhook?drop_pending_updates=true"

После сброса повторно зарегистрируйте вебхук (шаг 5).

Ссылки

• Telegram Bot API — документация для разработчиков
• @BotFather