Интеграция WhatsApp в Bitrix24 с помощью GREEN-API#

Данная интеграция обеспечивает взаимодействие с WhatsApp в Bitrix24 через платформу GREEN-API. Разработана на базе Universal Integration Platform от GREEN-API и предоставляет бесшовный WhatsApp коннектор для Контакт-центра Bitrix24.

Содержание#

• Обзор
• Архитектура
• Минимальные требования
• Шаг 1: Настройка приложения Bitrix24
• Шаг 2: Настройка адаптера
• Шаг 3: Развертывание
• Шаг 4: Установка интеграции в Bitrix24
• Как работает интеграция
• Дополнительные функции
• Лицензия
• Заключение

Обзор#

Данная интеграция позволяет вам:

1. Получать WhatsApp сообщения непосредственно в Контакт-центр Bitrix24
2. Отправлять WhatsApp сообщения из Bitrix24 вашим клиентам
3. Обрабатывать несколько инстансов GREEN-API на один портал Bitrix24
4. Поддерживать несколько линий связи в рамках одного портала

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

Сервис-адаптер

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

• Обрабатывает преобразование сообщений между Bitrix24 и WhatsApp
• Управляет OAuth-аутентификацией Bitrix24 и жизненным циклом приложения
• Предоставляет конечные точки для вебхуков от Bitrix24 и GREEN-API
• Создает и управляет инстансами GREEN-API для каждой линии Bitrix24
• Предоставляет многоязычный интерфейс (русский/английский)
• Обрабатывает файлы и различные типы сообщений

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

• База данных MySQL (5.7 или выше)
• Node.js 20 или выше
• Аккаунт и инстанс(ы) GREEN-API
• Портал Bitrix24 (облачный или коробочный)
• Публично доступный URL для сервиса-адаптера (для вебхуков)
• Аккаунт разработчика Bitrix24 для создания приложения

Шаг 1: Настройка приложения Bitrix24#

Перед развертыванием сервиса-адаптера необходимо создать и настроить приложение Bitrix24:

1. Зарегистрируйтесь как разработчик Bitrix24:

   • Сначала свяжитесь с поддержкой Bitrix24 и попросите предоставить вам статус технологического партнера
   • После этого вы сможете создать приложение на vendors.bitrix24.com

2. Создайте новое приложение:

   • Перейдите в раздел "Мои приложения" и нажмите "Создать приложение"
   • Заполните базовую информацию вашего приложения

3. Настройте конечные точки приложения:

   • Установите URL установки: YOUR_APP_URL/oauth/install
   • Установите URL приложения: YOUR_APP_URL
   • Настройте необходимые разрешения:
     • Открытые линии - для функциональности коннектора мессенджера
     • Контакт-центр - для интеграции с Контакт-центром
     • Чат и уведомления - для функциональности обмена сообщениями
     • CRM - для управления контактами и лидами

4. Сохраните учетные данные приложения:

   • Сохраните Client ID и Client Secret, они понадобятся для настройки адаптера

Шаг 2: Настройка адаптера#

1. Клонируйте репозиторий:

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

1. Установите зависимости:

npm install

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

Создайте файл .env в корне проекта:

DATABASE_URL="mysql://USER:PASSWORD@HOST:PORT/DATABASE_NAME"
APP_URL="https://your-adapter-domain.com"
BITRIX24_CLIENT_ID="your_bitrix24_client_id"
BITRIX24_CLIENT_SECRET="your_bitrix24_client_secret"

- `DATABASE_URL`: Строка подключения к вашей базе данных MySQL
- `APP_URL`: Публичный URL, где будет развернут ваш адаптер
- `BITRIX24_CLIENT_ID` и `BITRIX24_CLIENT_SECRET`: Из вашего приложения Bitrix24

1. Примените миграции базы данных:

npx prisma migrate deploy

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

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

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

Шаг 3: Развертывание#

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

Настройка Docker Compose (docker-compose.yml)#

version: '3.8'

services:
  adapter:
    build: .
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=${DATABASE_URL}
      - APP_URL=${APP_URL}
      - BITRIX24_CLIENT_ID=${BITRIX24_CLIENT_ID}
      - BITRIX24_CLIENT_SECRET=${BITRIX24_CLIENT_SECRET}
    depends_on:
      - db
    restart: unless-stopped

  db:
    image: mysql:8
    environment:
      - MYSQL_ROOT_PASSWORD=your_strong_root_password
      - MYSQL_USER=your_db_user
      - MYSQL_PASSWORD=your_db_password
      - MYSQL_DATABASE=bitrix24_adapter
    volumes:
      - mysql_data:/var/lib/mysql
    restart: unless-stopped

volumes:
  mysql_data:

Dockerfile#

FROM node:20-alpine
WORKDIR /app
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 up -d

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

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

Шаг 4: Установка интеграции в Bitrix24#

После развертывания вашего сервиса-адаптера и настройки приложения Bitrix24:

1. Установите приложение в ваш портал Bitrix24:

   • Из вашего аккаунта разработчика Bitrix24 перейдите к созданному приложению и нажмите "Протестировать"
   • Затем вам нужно будет ввести URL вашего тестового портала и нажать "Установить"
   • После перенаправления на страницу приложения в маркетплейсе, установите и откройте его

2. Зайдите в Контакт-центр:

   • Перейдите в Контакт-центр в меню вашего Bitrix24
   • Вы должны увидеть "GREEN-API WhatsApp" в списке доступных коннекторов/каналов

3. Настройте коннектор GREEN-API:

   • Нажмите на коннектор GREEN-API WhatsApp
   • Введите ваши учетные данные GREEN-API:
     • Instance ID (из console.green-api.com)
     • API Token (из console.green-api.com)
   • Нажмите "Сохранить настройки"

4. Проверьте настройку:

   • Коннектор должен отображаться как активный в Контакт-центре
   • Отправьте тестовое сообщение на ваш номер WhatsApp для проверки соединения

Как работает интеграция#

Входящие сообщения (WhatsApp → Bitrix24)#

1. Получение сообщений:

   • Клиент отправляет сообщение на ваш номер WhatsApp
   • GREEN-API получает сообщение и передает его в ваш адаптер
   • Адаптер преобразует сообщение в формат Bitrix24
   • Сообщение появляется в Контакт-центре Bitrix24

2. Поддерживаемые типы входящих сообщений:

   • Текстовые сообщения и эмодзи
   • Медиа-файлы (изображения, видео, документы, аудио)
   • Геолокации
   • Контакты
   • Голосовые сообщения
   • Цитируемые сообщения и ответы
   • Сообщения опросов и обновления
   • Интерактивные сообщения с кнопками/списками

3. Управление контактами:

   • Контакты автоматически создаются в CRM Bitrix24
   • Номера WhatsApp привязываются к записям контактов

Исходящие сообщения (Bitrix24 → WhatsApp)#

1. Отправка сообщений:

   • Используйте интерфейс обмена сообщениями Контакт-центра Bitrix24
   • Введите ваше сообщение и нажмите отправить
   • Сообщение направляется через адаптер в GREEN-API
   • Доставляется клиенту в WhatsApp через GREEN-API

2. Поддерживаемые типы исходящих сообщений:

   • Текстовые сообщения с форматированием
   • Файлы (документы, изображения, видео)

Поддержка нескольких линий#

• Настройте несколько инстансов GREEN-API для разных линий связи
• Каждая линия может обрабатывать различные типы разговоров

Дополнительные функции#

Многоязычная поддержка#

Интеграция поддерживает русский и английский интерфейсы:

• Автоматическое определение языка на основе настроек пользователя Bitrix24
• Локализованные формы настройки и сообщения об ошибках
• Языково-специфичные ссылки на документацию

Интерактивное руководство#

• Встроенное пошаговое руководство по настройке
• Визуальные скриншоты для каждого этапа настройки
• Кликабельные изображения с функцией увеличения в модальном окне
• Адаптивный дизайн для мобильных устройств и ПК

Лицензия#

Лицензировано на условиях MIT.

Заключение#

Следуя этим простым шагам, вы сможете создать интеграцию WhatsApp в Bitrix24 и позволит отправлять ответные сообщения.

GREEN-API всегда рад помочь вам в интеграции WhatsApp с другими платформами.