Всем привет! Вы просили - я сделал! Я выпустил релиз №3 для бота технической поддержки на GitHub.
Прошло уже несколько месяцев с последнего обновления, и бот за это время получил вдвое больше звёзд на GitHub, что очень мотивирует продолжать развитие и поддержку проекта.
За последний месяц ко мне поступило несколько запросов расширить функционал бота за счёт подключения новых источников трафика. Изначально я думал добавить интеграции с популярными мессенджерами, такими как WhatsApp или Viber. Но в итоге решил, что в первую очередь стоит реализовать API, чтобы вы сами могли подключать любые свои источники.
В этой статье расскажу о новом API для подключения внешних источников — живых чатов, CRM и других систем, а также о других важных обновлениях и планах на будущее.
О проекте
Для тех, кто не знаком с проектом: TG Support Bot — это бот на Laravel, который объединяет клиентов и менеджеров через Telegram и ВКонтакте, скрывая личные аккаунты и маршрутизируя общение через темы в Telegram-группе.
https://github.com/prog-time/tg-support-bot
Пользователь пишет боту, сообщение автоматически пересылается в выделенную тему для менеджеров, а их ответы возвращаются обратно от имени бота — так сохраняется приватность и удобство общения.
Буду благодарен, если вы поддержите мой проект ⭐ на GitHub!
Обратная связь
Для улучшения коммуникации с пользователями, я создал группу в Telegram, в которой вы можете задавать свои вопросы и писать предложения по расширению функционала.
Также сюда будут публиковаться новости по выпуску обновлений.
Руководство по установки
Я записал видео-инструкцию для установки данного решения на VPS с предустановленным Docker Compose.
Youtube — https://youtu.be/yNiNtFWOF2w
Rutube — https://rutube.ru/video/bdd0cc5ab4e13530fd7e0c2413931211/
ВК Видео — https://vkvideo.ru/video-141526561_456239132
API — не альтернатива мессенджерам, а универсальный инструмент
Хочу сразу уточнить: разработка API не заменяет расширение списка поддерживаемых мессенджеров и соцсетей. Я продолжаю работать над интеграциями с ними и буду добавлять новые источники трафика.
Однако API необходим для подключения кастомных источников — живых чатов, CRM-систем, форм на сайте и других нестандартных каналов.
Что входит в первую версию API?
В API реализованы базовые маршруты для работы с сообщениями:
GET api/external/messages — получение списка сообщений с возможностью фильтрации
GET api/external/messages/{id_message} — получение конкретного сообщения по ID
POST api/external/messages — отправка нового сообщения
PUT api/external/messages — изменение существующего сообщения
DELETE api/external/messages — удаление сообщения
Для работы с API необходимо создать пользователя и сгенерировать для него API-токен. Рекомендую создавать отдельного пользователя под каждый источник.
Создать пользователя и токен можно командой:
php artisan app:generate-token {название_источника}
Также нужно прикрепить к источнику ресурс, куда будут поступать сообщения от обработчика.
Как это работает?
Процесс довольно простой:
На вашей стороне генерируется уникальный ID пользователя — это может быть хэш ключ или любой уникальный идентификатор.
При отправке сообщения в тело запроса передаются: ID пользователя, код источника, текст сообщения и, при необходимости, файлы.
Система идентифицирует пользователя или создаёт новую запись, если это первое сообщение от него.
Сообщение из вашего источника направляется в Telegram-группу поддержки.
Менеджеры в группе, как и раньше, могут отвечать любыми типами сообщений. Текст отправляется как текст, остальные — конвертируются в файлы. В названии темы указывается ID клиента и источник сообщения.
Таким образом, вы легко сможете подключить практически любой внешний источник к вашему боту.
Подробная инструкция по работе с API уже есть в разделе wiki на GitHub.
Добавлены новые консольные команды
Я добавил несколько полезных консольных команд.
php artisan telegram:set-webhook
Artisan команда, которая производит подключения хука бота к вашему проекту. Ранее это делалось через отправку запроса в telegram или по специальной ссылке, а теперь это можно сделать запустив команду в консоле.
php artisan app:generate-token
Команда, которая генерирует токен для подключения к API вашего бота. Вы можете подключить неограниченное количество источников графика и для каждого создать уникальный токен.
Swagger для API
Для API был разработан генератор swagger документа.
Ранее я хотел использовать готовое решение для генерации swagger документации, но большинство решений очень сильно нагромождают код. Поэтому я решил написать собственный генератор, который собирает документацию.
Принцип прост! Вы описываете документацию по частям в resources/swagger. Важно граматно подходить к именованию файлов и компонентов.
После создания структуры, вы запускаете artisan команду и документация собирается в единый документ.
php artisan swagger:generate
На выходе вы получаете 2 версии документации
В формате json, которую можно использовать для нейросетей или программ
В формате Swagger-ui для просмотра в браузере
Мелкие доработки
Улучшено логирование ошибок — все логи теперь доступны в Grafana;
Исправил баги, о которых вы писали в Issues;
Добавил контейнер redisinsight для просмотра Redis данных через WEB интерфейс;
Переписал инструкции для подключения и настройки бота;
Спасибо всем за поддержку и обратную связь! Продолжаю работать над улучшениями и буду рад новым предложениям и вопросам.
Если нужно, могу помочь с примерами использования API или подсказать, как правильно настроить интеграцию.