Skip to content

README.ru.md

Latest commit

 

History

History
256 lines (190 loc) · 11.6 KB

README.ru.md

File metadata and controls

256 lines (190 loc) · 11.6 KB
Raw

Интеграция GREEN-API для Bitrix24

Данная интеграция обеспечивает взаимодействие с WhatsApp в Bitrix24 через платформу GREEN-API. Разработана на базе Universal Integration Platform от GREEN-API и предоставляет бесшовный WhatsApp коннектор для Контакт-центра 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 и попросите предоставить вам статус технологического партнера
    • После этого вы сможете создать приложение на https://vendors.bitrix24.ru/

  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

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

    npm install

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

    Создайте файл .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

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

    npx prisma migrate deploy

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

    # Сборка приложения
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