Интеграция GREEN-API для Rocket.Chat#

Эта интеграция обеспечивает взаимодействие с WhatsApp в Rocket.Chat через платформу GREEN-API. Разработана на базе Universal Integration Platform от GREEN-API и состоит из двух частей:

Адаптер - приложение NestJS, обеспечивающее взаимодействие между Rocket.Chat и GREEN-API
Приложение Rocket.Chat - сопутствующее приложение, предоставляющее слэш-команды для управления интеграцией

Содержание#

Архитектура
- Адаптер
- Приложение Rocket.Chat
Установка
Развертывание в Docker
- Настройка Docker Compose
- Dockerfile
Важные примечания
Использование приложения
1. Зарегистрируйте ваше рабочее пространство в адаптере (требуется роль администратора)
2. Зарегистрируйте пользователей в вашем рабочем пространстве
3. Создайте инстанс GREEN-API
4. Ожидание настроек
5. Проверка соединения
6. Начало работы
7. Другие доступные команды
Лицензия

Архитектура#

Адаптер#

Приложение NestJS, которое:

Обрабатывает преобразование сообщений между Rocket.Chat и WhatsApp
Управляет инстансами GREEN-API
Обрабатывает аутентификацию пользователей и выполнение команд
Предоставляет конечные точки для вебхуков обеих платформ

Приложение Rocket.Chat#

Приложение Rocket.Chat, предоставляющее слэш-команды:

Для администраторов:

/greenapi.register-workspace - Регистрация рабочего пространства Rocket.Chat
/greenapi.list-instances - Просмотр всех инстансов в рабочем пространстве
/greenapi.list-users - Просмотр всех зарегистрированных пользователей
/greenapi.sync-app-url - Синхронизация URL-адресов вебхуков всех инстансов

Для агентов:

/greenapi.register-agent - Регистрация себя как агента
/greenapi.create-instance - Создание нового инстанса GREEN-API
/greenapi.update-token - Обновление токена аутентификации Rocket.Chat

Для обеих ролей:

/greenapi.remove-instance - Администраторы могут удалять любые инстансы, агенты только свои

Установка#

Минимальные требования#

База данных MySQL (5.7 или выше)
Node.js 20 или выше
Аккаунт и инстанс GREEN-API
Сервер Rocket.Chat (коробочная или облачная версия)

Настройка адаптера#

Склонируйте репозиторий:

git clone https://github.com/green-api/greenapi-integration-rocketchat.git
cd greenapi-integration-rocketchat

Установите зависимости:
```
npm install
```

Настройте переменные окружения в файле .env:

DATABASE_URL=mysql://user:password@localhost:3306/rocket_adapter
APP_URL=https://your-domain.com

Примените миграции:
```
npx prisma migrate deploy
```

Соберите и запустите адаптер:

# Сборка приложения
npm run build

# Запуск в production режиме
npm run start:prod

Установка приложения Rocket.Chat#

Перейдите в панель администрирования Rocket.Chat
Перейдите в раздел Apps -> Private Apps -> Upload Private App
Выберите файл greenapi_X.X.X.zip из папки проекта greenapi-integration-rocketchat-app/app и загрузите его
Настройте URL-адрес в настройках загруженного приложения, указав адрес вашего адаптера
Теперь вы можете использовать все вышеуказанные команды

Развертывание в Docker#

Адаптер может быть развернут с использованием Docker Compose. Конфигурационные файлы:

Настройка Docker Compose#

version: '3.8'

services:
  adapter:
    build: .
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=${DATABASE_URL}
      - APP_URL=${APP_URL}
    depends_on:
      - db

  db:
    image: mysql:8
    environment:
      - MYSQL_ROOT_PASSWORD=root_password
      - MYSQL_USER=user
      - MYSQL_PASSWORD=password
      - MYSQL_DATABASE=rocket_adapter
    volumes:
      - mysql_data:/var/lib/mysql

volumes:
  mysql_data:

Dockerfile#

FROM node:20-alpine
WORKDIR /app
RUN apk add --no-cache openssl
COPY package*.json ./
RUN npm ci
COPY . .
RUN npx prisma generate
RUN npm run build
EXPOSE 3000
CMD npx prisma migrate deploy && npm run start:prod

Для развертывания с помощью Docker Compose:

# Запуск всех сервисов
docker-compose up -d

# Просмотр логов
docker-compose logs -f

# Остановка всех сервисов
docker-compose down

Примечание: Данные файлы предоставлены в качестве примера и могут требовать корректировок в зависимости от ваших конкретных условий и требований развертывания.

Важные примечания#

Роли пользователей и разрешения#

Интеграция использует систему ролей Rocket.Chat:

Роль администратора
- Может регистрировать рабочие пространства
- Может просматривать все инстансы и пользователей
- Может удалять любой инстанс
- Может синхронизировать URL приложения
- Не требуется регистрация в качестве агента для использования админ-команд
Роль агента лайвчата
- Должен сначала зарегистрироваться используя /greenapi.register-agent
- Может создавать собственные инстансы
- Может обновлять свой токен аутентификации
- Может удалять только свои инстансы

Как получить учетные данные Rocket.Chat (токен и ID)#

Чтобы получить ваши rocket-chat-id и rocket-chat-token:

Нажмите на ваш аватар в Rocket.Chat
Перейдите в раздел "Personal Access Tokens" в настройках аккаунта
Введите имя для токена или оставьте поле пустым и нажмите "Add"
После подтверждения вам будут показаны User ID и Access Token
- Сохраните оба значения, так как токен будет показан только один раз
- User ID - это ваш rocket-chat-id
- Access Token - это ваш rocket-chat-token

Примечание: Для регистрации рабочего пространства (/greenapi.register-workspace) пользователь должен иметь роль администратора (admin). Для регистрации агента (/greenapi.register-agent) требуется роль агента (livechat-agent).

Самостоятельное развертывание#

Если вы разворачиваете адаптер на собственном сервере, для работы адаптера требуется публичный URL-адрес (APP_URL), доступный из интернета. Это необходимо для:

Получения вебхуков от GREEN-API
Обеспечения связи между Rocket.Chat и адаптером

При самостоятельном развертывании убедитесь, что вы:

Настроили сеть/файрвол для разрешения входящих соединений
Настроили доменное имя или статический IP-адрес
Настроили SSL/TLS для безопасного соединения
Установили переменную окружения APP_URL, указав ваш публичный URL-адрес

Чтобы агенты могли отправлять файлы в WhatsApp, необходимо включить публичный доступ к файлам в вашем рабочем пространстве Rocket.Chat. Для настройки:

Нажмите ⋮ (три вертикальные точки) в левом верхнем углу домашней страницы Rocket.Chat
Нажмите "Рабочее пространство"
Нажмите "Настройки" внизу боковой панели
Найдите "Загрузка файлов"
Отключите настройку "Защитить загруженные файлы"

Если эта настройка останется включенной, агенты не смогут отправлять файлы контактам WhatsApp.

Настройка агентов в Rocket.Chat#

Перед регистрацией в качестве агента в данной интеграции, пользователи должны быть настроены как агенты в Rocket.Chat:

Нажмите ⋮ (три вертикальные точки) в левом верхнем углу домашней страницы Rocket.Chat
Перейдите в раздел Omnichannel
Перейдите в раздел Agents
Найдите пользователя, которого хотите сделать агентом, по его юзернейму
Выберите пользователя и нажмите "Add agent"

Только после того, как пользователь настроен как агент в Rocket.Chat, он может зарегистрироваться как агент в данной интеграции с помощью команды /greenapi.register-agent. Агент будет получать входящие чаты только если он доступен. Если агент недоступен, чат будет направлен следующему доступному агенту. Если нет доступных агентов, чат будет иметь статус "Queued" и его нужно будет принять вручную.

Поведение при цитировании сообщений#

При использовании цитирования сообщений в Rocket.Chat:

Агенты могут цитировать сообщения клиентов из WhatsApp
Если агенты цитируют свои собственные сообщения, такие цитаты не будут видны в WhatsApp, только само сообщение.

Использование приложения#

1. Зарегистрируйте ваше рабочее пространство в адаптере (требуется роль администратора):#

/greenapi.register-workspace [rocket-chat-id] [rocket-chat-token]

rocket-chat-id: Ваш ID в Rocket.Chat
rocket-chat-token: Ваш персональный API токен Rocket.Chat

2. Зарегистрируйте пользователей в вашем рабочем пространстве:#

/greenapi.register-agent [rocket-chat-id] [rocket-chat-token]

rocket-chat-id: ID пользователя в Rocket.Chat
rocket-chat-token: Персональный API токен пользователя Rocket.Chat

Для выполнения этой команды требуется:

Предварительная регистрация рабочего пространства
Наличие роли агента лайвчата у пользователя

Для того, чтобы агент мог отвечать в WhatsApp чате, он должен быть предварительно зарегистрирован с помощью этой команды.

3. Создайте инстанс GREEN-API:#

/greenapi.create-instance [instance-id] [instance-token]

instance-id: ID вашего инстанса GREEN-API
instance-token: API токен вашего инстанса GREEN-API

4. Ожидание настроек:#

Подождите примерно 2 минуты, пока применятся настройки инстанса.

5. Проверка соединения:#

Для проверки соединения напишите сообщение на номер WhatsApp, подключенный к вашему инстансу GREEN-API - в Rocket.Chat появится новый чат с этим сообщением.

6. Начало работы:#

Теперь вы можете использовать WhatsApp в Rocket.Chat!

7. Другие доступные команды:#

Для агентов:

# Создание нового инстанса
/greenapi.create-instance [instance-id] [instance-token]

# Удаление своего инстанса
/greenapi.remove-instance [instance-id]

# Обновление токена аутентификации
/greenapi.update-token [rocket-chat-id] [new-rocket-chat-token]

Для администраторов:

# Просмотр всех инстансов в рабочем пространстве
/greenapi.list-instances

# Просмотр всех зарегистрированных агентов
/greenapi.list-users

# Удаление любого инстанса
/greenapi.remove-instance [instance-id]

# Синхронизация URL для всех инстансов
/greenapi.sync-app-url [new-app-url]

Команда sync-app-url особенно полезна, когда вы изменили URL-адрес вашего адаптера или перенесли его на другой домен. Она автоматически обновляет настройки URL-адресов вебхуков для всех ваших зарегистрированных инстансов GREEN-API. Примечание: Новый URL приложения должен заканчиваться на "api/webhook/rocket" для корректного маппинга вебхуков.