Прошло уже несколько месяцев с последнего обновления, и бот за это время получил вдвое больше звёзд на GitHub, что очень мотивирует продолжать развитие и поддержку проекта.

За последний месяц ко мне поступило несколько запросов расширить функционал бота за счёт подключения новых источников трафика. Изначально я думал добавить интеграции с популярными мессенджерами, такими как WhatsApp или Viber. Но в итоге решил, что в первую очередь стоит реализовать API, чтобы вы сами могли подключать любые свои источники.

В этой статье расскажу о новом API для подключения внешних источников — живых чатов, CRM и других систем, а также о других важных обновлениях и планах на будущее.

Предисловие

Для тех, кто не знаком с проектом: TG Support Bot — это бот на Laravel, который объединяет клиентов и менеджеров через Telegram и ВКонтакте, скрывая личные аккаунты и маршрутизируя общение через темы в Telegram-группе.

https://github.com/prog-time/tg-support-bot

Пользователь пишет боту, сообщение автоматически пересылается в выделенную тему для менеджеров, а их ответы возвращаются обратно от имени бота — так сохраняется приватность и удобство общения.

Буду благодарен, если вы поддержите мой проект ⭐ на GitHub!

Руководство по установки

Я записал видео-инструкцию для установки данного решения на VPS с предустановленным Docker Compose.

Youtube - https://youtu.be/yNiNtFWOF2w

Rutube - https://rutube.ru/video/bdd0cc5ab4e13530fd7e0c2413931211/

ВК Видео - https://vkvideo.ru/video-141526561_456239132

Обратная связь

Для улучшения коммуникации с пользователями, я создал группу в Telegram, в которой вы можете задавать свои вопросы и писать предложения по расширению функционала.

https://t.me/pt_tg_support

Также сюда будут публиковаться новости по выпуску обновлений.

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-токен. Рекомендую создавать отдельного пользователя под каждый источник.

Создать пользователя и токен можно командой:

Также нужно прикрепить к источнику ресурс, куда будут поступать сообщения от обработчика.

Как это работает?

Процесс довольно простой:

1. На вашей стороне генерируется уникальный ID пользователя — это может быть хэш ключ или любой уникальный идентификатор.

2. При отправке сообщения в тело запроса передаются: ID пользователя, код источника, текст сообщения и, при необходимости, файлы.

3. Система идентифицирует пользователя или создаёт новую запись, если это первое сообщение от него.

4. Сообщение из вашего источника направляется в 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 команду и документация собирается в единый документ.

На выходе вы получаете 2 версии документации

1. В формате json, которую можно использовать для нейросетей или программ

2. В формате Swagger-ui для просмотра в браузере

Мелкие доработки

• Улучшено логирование ошибок — все логи теперь доступны в Grafana;

• Исправил баги, о которых вы писали в Issues;

• Добавил контейнер redisinsight для просмотра Redis данных через WEB интерфейс;

• Переписал инструкции для подключения и настройки бота;

Спасибо всем за поддержку и обратную связь! Продолжаю работать над улучшениями и буду рад новым предложениям и вопросам.

Если нужно, могу помочь с примерами использования API или подсказать, как правильно настроить интеграцию.

Я должен подарить свое творение миру, чтобы каждый о нем узнал и затрепетал.

Что для этого необходимо сделать? Правильно, приложение должно быть доступно через интернет, чтобы каждый владелец приложения telegram мог спокойно запустить его в любой точке мира и наслаждаться общением. Есть два варианта решения:

• Обеспечить доступ к приложению на моем компьютере из внешней сети (есть несколько интересных способов решения данной задачи, если будет интересно, напишу и о них);

• Арендовать VPS (Virtual Private Server ака виртуальный приватный сервер) у любого хостинг провайдера.

Я выбрал второй вариант. Что такое VPS? Если совсем кратко это просто тупо компьютер, доступный из интернета и обеспечением которого занимается хостинг провайдер. Управление VPS у меня реализовано через консоль и выглядит следующим образом.

Вы видите все составные части моего приложения:

• В папке backend находятся все данные и файлы, связанные с «основным» бэкендом;

• Файл docker-compose.yml отвечает за обеспечение взаимодействия между докер контейнерами, о которых я расскажу далее;

• В папке frontend находятся все данные и файлы, связанные с фронтендом;

• В папке nginx находятся все данные и файлы, связанные с инструментом nginx, который реализует веб-сервер и почтовый прокси-сервер;

• В папке tgbot находятся все данные и файлы, реализующие функционал взаимодействия с ботом в тг.

  
  

  Как эти папки с файлами оказались на VPS? Есть три способа, о которых я знаю:

• Через консоль по SFTP (это транспортный протокол такой) просто тупо копировать все данные;

• Через инструмент FileZilla, который реализует SFTP, но с удобным графическим интерфейсом;

• Через git – когда вы заливаете весь ваш код на github или gitlab и уже оттуда скачиваете все на VPS.

Я использую 2 и 3 варианты, так как уже не могу жить без git (это как Ватсон, который без трубки заснуть уже не мог) и некоторые файлы с паролями/секретами, docker-compose, dockerfile копирую через FileZilla.

Теперь все необходимые файлы находятся на VPS и нам необходимо все это вместе запустить. Настало время рассказать про докер, великий и ужасный.

Не буду сильно углубляться в особенности докер и docker-compose, потому как на ютубе полно видео, в которых достаточно доходчиво объясняется что это и для чего это. Я лишь расскажу вам о том, какие проблемы позволил мне решить докер.

• Установка базы данных в пару строчек в docker-compose.yml;

• Установка nginx в пару строчек в dockerfile и docker-compose.yml;

• Запуск программ и поддержка их в запущенном состоянии. Если руками через консоль запускать программы, то при закрытии консоли, они (программы) тоже закроются (не все).

После правильной сборки и запуска всех контейнеров, через docker-compose.yml, вы можете увидеть такую картинку и обрадоваться, что ничего не отвалилось и все контейнеры запущены и работают. Если совсем тезисно, то каждая строчка это контейнер, в котором запущена всего лишь одна составная часть приложения (nginx для фронтенда, основной бэкенд, база данных и бэкенд для бота).

Теперь ваше приложение доступно по ip адресу в браузере, который получил VPS. И тут у вас может возникнуть справедливый вопрос «А где здесь telegram, если приложение запускается в браузере?». Абсолютно верное замечание и ответ достаточно прост - telegram мини-приложение это сайт, который просто открывается в отдельном окне самого telegram и никакой магии. О том, как реализуется эта процедура и о дальнейших настройках доменного имени и ssl, без чего не возможен запуск именно мини-приложения, я расскажу в последующих частях.

А, ну и конечно, как я уже ранее писал, мини-приложение уже готово и ждет своих пользователей, как говорится welcome t.me/Socionyx_Bot/socionyx.

Буду премного благодарен за обратную связь и замечания по работе текущего мини-приложения.

P.S. я не забыл про твой вопрос мой дорогой nikita17cm и об особенностях «микросерверности», и о разделе бота и основного бэкенда, я обязательно расскажу в следующей части.

Поэтому я решил попробовать другое решение:

• Арендовал облачный сервер

• Настроил всю среду разработки прямо там

• Теперь подключаюсь к нему по SSH через VS Code (на самом деле Cursor, но суть та же)

В итоге вся работа идёт на сервере, независимо от мощности моего устройства. Я ожидал лагов и сетевых тормозов, но всё работает удивительно плавно. Теперь мне не важно, с какого устройства заходить — главное, чтобы был интернет и возможность запустить VS Code или Cursor.

Закинул RSA ключ и работаешь как на локальной машине.

Еще одна классная фича конкретно VS Code - подобных редакторов: они могут пробросить порты на локальный хост. Поэтому можно поднять базу данных на сервере на порту 5432, а подключаться к нему через клиент под Windows по адресу 127.0.0.1:5432.

Получается, что даже слабый ноутбук теперь может быть удобным инструментом для разработки. Если Docker на Windows вас тоже достал, возможно, вам зайдет такой подход

4. Проект одинаково себя ведёт везде. Это упрощает воспроизведение проблемы и сокращает время на багфикс.

5. Нет проблем с конфликтом зависимостей-библиотек. Вы можете на одной машине запустить проекты с условным django 3 и django 4, они никак друг другу не помешают.

6. Легко поднимать зависимости-компоненты. Для любой базы данных берётся готовый докер-образ, меняется конфиг и в одну команду запускается. С выходом на docker compose можно одной командой поднимать сборную солянку из backend, frontend, базы данных, nginx и Let's Encrypt.

7. Просто откатываться к старой версии. Версионирование докер-образов позволяет запустить новую версию, и, если что-то пошло не так, откатиться назад за десятки секунд.

8. Понятные внешние эффекты проекта. В команде docker run указаны проброшенные в контейнер каталоги и порты. Всё остальное изолированно.

В общем, со всех сторон одна польза. Минусы? Требуется изучить новый инструмент и best practices. Кажется, на этом всё. Даже дополнительных накладных расходов на виртуализацию нет. И помните – если docker вам мешает, скорее всего, вы что-то делаете неправильно.

Для запуска нескольких связанных контейнеров пользуйтесь compose, гайд тут. Если ещё нужно управлять множеством серверов, то посмотрите на kubernetes.

4. Добавьте Docker-репозиторий

Добавьте Docker-репозиторий в список источников:

5. Установите Docker

Обновите список пакетов и установите Docker Engine.

Проверьте установку Docker:

6. Убедитесь, что Docker работает

Запустите Docker и добавьте текущего пользователя в группу Docker для выполнения команд без sudo.

Для применения изменений перезагрузите сессию или выполните:

7. Установите Docker Compose

Загрузите последнюю версию Docker Compose с официального сайта.

7.1 Узнайте последнюю версию Docker Compose:

Например, это может быть v2.26.0.

7.2 Замените <version> на полученную версию и выполните установку:

7.3 Сделайте файл исполняемым:

7.4 Проверьте установку:

8. (Опционально) Настройте автозапуск Docker

Если требуется, чтобы Docker автоматически запускался при старте системы:

Теперь Docker и Docker Compose успешно установлены и готовы к использованию.