Перейти к содержанию

GoHighLevel x GREEN-API - разработка собственной интеграции#

Данная интеграция обеспечивает взаимодействие с WhatsApp в GoHighLevel (GHL) через платформу GREEN-API. Разработана на базе Universal Integration Platform от GREEN-API и состоит из адаптера NestJS, обеспечивающего связь между двумя платформами.

Важная информация

Эта интеграция предназначена исключительно для суб-аккаунтов GoHighLevel. Попытка установить или использовать её на уровне агентства или выбрать "Agency" во время настройки приложения может привести к некорректной работе или проблемам с функциональностью.

Содержание#

Обзор#

Данная документация проведет вас через процесс настройки вашей собственной интеграции между GREEN-API и GoHighLevel. Вместо использования готового приложения вы:

  1. Создадите своё собственное приложение в GoHighLevel Marketplace
  2. Настроите и развернёте сервис-адаптер
  3. Свяжете один или несколько инстансов GREEN-API с вашим суб-аккаунтом GoHighLevel через удобный интерфейс управления

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

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

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

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

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

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

  • База данных MySQL (5.7 или выше)
  • Node.js 20 или выше
  • Аккаунт и инстанс(ы) GREEN-API
  • Аккаунт разработчика GoHighLevel. Вы можете создать его на сайте https://marketplace.gohighlevel.com/
  • Суб-аккаунт GoHighLevel для тестирования установки и функциональности приложения
  • Публично доступный URL-адрес для сервиса-адаптера (для вебхуков)

Настройка приложения в GoHighLevel Marketplace#

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

  1. Зарегистрируйтесь и войдите на сайте https://marketplace.gohighlevel.com/

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

    • Перейдите в раздел Apps и нажмите "Create New App"
    • Заполните базовую информацию вашего приложения (название, описание и т.д.)

  3. Настройте параметры публикации:

    • В конфигурации приложения найдите "Listing Configuration"
    • ВАЖНО: Выберите только "Sub-Account" в качестве опции установки
    • НЕ выбирайте "Agency" или оба варианта, так как это может вызвать проблемы с функциональностью

  4. Настройте OAuth:

    • Перейдите в "Advanced Settings" -> "Auth"
    • Настройте URL перенаправления: YOUR_APP_URL/oauth/callback
    • Выберите необходимые разрешения (scopes):
      • contacts.readonly
      • contacts.write
      • conversations.readonly
      • conversations.write
      • conversations/message.readonly
      • conversations/message.write
      • locations.readonly
      • users.readonly

  5. Сгенерируйте учетные данные:

    • Пролистайте до раздела "Client Keys"
    • Сгенерируйте Client ID и Client Secret
    • Немного ниже будет раздел "Shared Secret" — сгенерируйте его тоже
    • Сохраните эти значения - они понадобятся для конфигурации адаптера

  6. Создайте Conversation Provider:

    • Перейдите в настройки "Conversation Provider" в настройках приложения
    • Имя: "GREEN-API" (или любое другое по вашему выбору)
    • Тип: SMS
    • URL доставки: YOUR_APP_URL/webhooks/ghl (то же, что и URL вебхука)
    • Отметьте оба пункта: "Is this a Custom Conversation Provider?" и "Always show this Conversation Provider?"
    • При желании добавьте алиас и логотип
    • Сохраните Conversation Provider ID - он понадобится для конфигурации

  7. Настройте пользовательскую страницу:

    • Включите функциональность Custom Page
    • Установите URL пользовательской страницы: YOUR_APP_URL/app/whatsapp
    • Это предоставит пользователям интерфейс для управления их инстансами GREEN-API

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

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

git clone https://github.com/green-api/greenapi-integration-gohighlevel.git
cd greenapi-integration-gohighlevel
2. Установите зависимости:

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

Создайте файл .env в корне проекта со следующими переменными:

DATABASE_URL="mysql://USER:PASSWORD@HOST:PORT/DATABASE_NAME"
APP_URL="https://your-adapter-domain.com"
GHL_CLIENT_ID="your_ghl_client_id_from_developer_portal"
GHL_CLIENT_SECRET="your_ghl_client_secret_from_developer_portal"
GHL_CONVERSATION_PROVIDER_ID="your_ghl_conversation_provider_id_from_app_settings"
GHL_SHARED_SECRET="your_secure_random_string_for_encryption"
- DATABASE_URL: Строка подключения к вашей базе данных MySQL
- APP_URL: Публичный URL, где будет развернут ваш адаптер
- GHL_CLIENT_ID и GHL_CLIENT_SECRET: Из шага 5 настройки приложения GHL
- GHL_CONVERSATION_PROVIDER_ID: Из шага 7 настройки приложения GHL
- GHL_SHARED_SECRET: Из шага 5 настройки приложения GHL
4. Примените миграции базы данных:

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

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

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

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

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

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

docker-compose.yml 

version: '3.8'

services:
    adapter:
        build: .
        ports:
            - "3000:3000"
        environment:
            - DATABASE_URL=${DATABASE_URL}
            - APP_URL=${APP_URL}
            - GHL_CLIENT_ID=${GHL_CLIENT_ID}
            - GHL_CLIENT_SECRET=${GHL_CLIENT_SECRET}
            - GHL_CONVERSATION_PROVIDER_ID=${GHL_CONVERSATION_PROVIDER_ID}
            - GHL_SHARED_SECRET=${GHL_SHARED_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=ghl_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:

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

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

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

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

Установка и использование интеграции#

После настройки вашего приложения GoHighLevel и развертывания сервиса-адаптера, вы можете установить и использовать интеграцию:

  1. Установите приложение в ваш суб-аккаунт GoHighLevel:

    • Перейдите в "App Marketplace" (расположен в боковой панели)
    • Если ваше приложение приватное:
      • Скопируйте ID вашего приложения из marketplace.gohighlevel.com
      • Из вашего суб-аккаунта GoHighLevel перейдите в маркетплейс
      • Нажмите на любое приложение и измените URL, заменив ID приложения на ID вашего приложения
    • Если ваше приложение публичное, вы можете просто найти его в поиске
    • Нажмите "Install" на странице вашего приложения и затем "Allow and Install"

  2. Получите доступ к интерфейсу управления инстансами WhatsApp:

  3. После установки вы можете перейти к пользовательской странице для управления вашими инстансами GREEN-API (появится в боковой панели)

  4. Интерфейс позволит вам добавлять/управлять несколькими инстансами

  5. Добавьте инстансы GREEN-API:

    • Используйте интерфейс управления для добавления ваших инстансов GREEN-API
    • Для каждого инстанса предоставьте:
    • Имя инстанса (необязательно, для удобной идентификации)
    • ID инстанса (из console.green-api.com)
    • API Token (из console.green-api.com)
    • Вы можете добавить несколько инстансов и управлять ими независимо

  6. Управляйте вашими инстансами:

  7. Просматривайте все ваши подключенные инстансы GREEN-API
  8. Редактируйте имена инстансов для лучшей организации
  9. Удаляйте инстансы, когда они больше не нужны
  10. Отслеживайте статус инстансов и состояние авторизации

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

После установки интеграция работает автоматически:

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

  1. Когда клиент отправляет сообщение на ваш номер WhatsApp:

    • GREEN-API получает сообщение и отправляет его в ваш адаптер
    • Адаптер создает или обновляет контакт в GHL
    • Контакт помечается тегом с конкретным ID инстанса, с которым связались (Данный тег нельзя изменить никаким образом)
    • Сообщение появляется в интерфейсе переписки GHL

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

    • Текстовые сообщения
    • Медиа (изображения, видео, документы, аудио)
    • Геолокации
    • Контактные карточки
    • И другие (стикеры, опросы и т.д.)

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

  1. Чтобы ответить контакту WhatsApp:

    • Используйте стандартный интерфейс сообщений GHL
    • Сообщение будет направлено через ваш адаптер к соответствующему инстансу GREEN-API на основе тега контакта

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

    • Текстовые сообщения
    • Вложенные файлы

  3. Поддержка групп:

  4. Групповые сообщения полностью поддерживаются - когда кто-то отправляет сообщение в группу WhatsApp
  5. Группы создаются с именами вида [Group] Команда продаж для четкой идентификации групп
  6. "Номера телефонов" групп на самом деле являются ID чата группы (длинный числовой идентификатор вида 120363418570879210)
  7. Групповые сообщения показывают имя отправителя и его номер телефона: Иван Иванов (+1234567890): Привет всем!
  8. Один диалог на группу - все групповые сообщения появляются в одном диалоге независимо от того, кто их отправляет

Важные замечания#

⚠️ Диалоги с несколькими инстансами: Если один и тот же номер телефона пишет на несколько ваших инстансов GREEN-API (разные номера WhatsApp), данная интеграция не будет создавать отдельные диалоги. Все сообщения от этого номера телефона, независимо от того, с каким инстансом они связались, будут появляться в одном диалоге.

📱 Идентификация групп:

Группы можно легко определить по: - Имени контакта, начинающемуся с [Group] - Полю телефона, содержащему длинный числовой ID вместо обычного номера телефона - Автоматически применяемому тегу whatsapp-group к группам

Распространенные ошибки и их устранение#

  1. Сообщения не доставляются:

    • Проверьте логи адаптера на наличие ошибок
    • Убедитесь, что URL вебхуков настроены правильно
    • Проверьте статус инстансов в интерфейсе управления

  2. Проблемы управления инстансами:

    • Проверьте, что OAuth-аутентификация завершена первой
    • Убедитесь, что все необходимые переменные окружения установлены
    • Проверьте, что пользовательская страница может связаться с вашим сервисом-адаптером

  3. Ошибки подключения к базе данных:

    • Проверьте правильность DATABASE_URL
    • Убедитесь, что пользователь базы данных имеет соответствующие разрешения
    • Проверьте, что миграции базы данных были применены

Лицензия#

Лицензировано в соответствии с MIT