Skip to content

README.ru.md

Latest commit

 

History

History
310 lines (203 loc) · 20.4 KB

README.ru.md

File metadata and controls

310 lines (203 loc) · 20.4 KB
Raw

whatsapp-api-webhook-server-cpp

Поддержка

Support Support Support

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

Guides News News

whatsapp-api-webhook-server-cpp — вебхук сервер для интеграции с мессенджером WhatsApp Messenger через API сервиса green-api.com. Для работы с сервером нужно получить регистрационный токен и ID аккаунта в личном кабинете. Есть бесплатный тариф аккаунта разработчика.

API

Документация к вебхукам находится по ссылке. Приложение является обработчиком вебхуков, поэтому документация по ссылке выше применима и к самому приложению.

Получение Webhook Token

Чтобы получить Webhook Token и иметь возможность отправлять запросы на этот сервер, необходимо авторизовать учетную запись WhatsApp в приложении для телефона. Чтобы авторизовать учетную запись, зайдите в личный кабинет и отсканируйте QR-код с помощью приложения WhatsApp.

Сборка приложения

Это приложение использует C++ 17, CMake 3.5, поддерживает компиляторы Linux (GCC) и Windows (Visual Studio 2019/2022).

Перед сборкой вам необходимо создать следующий файл:

  • source/user_adapter.cpp

Если у вас нет требуемого файла, создайте его путем удаления нижнего подчеркивания из названия ```source/_user_adapter.cpp`` файла.

Мы будем обновлять include/user_adapter.h и source/_user_adapter.cpp файлы по мере выпуска новых вебхуков. Если вы столкнулись с ошибкой сборки, где написано о том, что компилятор не смог найти требуемые функции из user_adapter, то в этом случае вам необходимо добавить новые функции из source/_user_adapter.cpp в ваш source/user_adapter.cpp.

Проект не будет собран, если это не будет сделано.

Windows

Для сборки приложения необходимо:

  • git - кроссплатформенная утилита, используемая в этом проекте для загрузки библиотек.

  • CMake - кроссплатформенная утилита для автоматического создания ПО из исходного кода.

  • Компилятор Microsoft Visual C++ (MSVC) для C++ приложений.

cmake и git должны быть доступны в PATH.

Сборка выполняется запуском скрипта build.bat (или .\build.bat для Powershell):

git clone --branch=master --depth=1 https://github.com/green-api/whatsapp-api-webhook-server-cpp
cd whatsapp-api-webhook-server-cpp
build.bat

Приложение по умолчанию собирается с типом конфигурации Release. Файл конфигурации config.json и директория jsonSchema копируются в директорию build\bin. Приложение дает приоритет файлам build\bin, загружая файлы с директории проекта, только если не может найти файлы в build\bin.

После успешной сборки, повторная сборка приложения доступна через скрипт build.bat или

cmake --build build --config=Release

Исполняемый файл приложения находится в build/bin/.

Запуск приложения:

start build\bin\whatsapp-api-webhook-server-cpp.exe

При исполнении программы создается сервер на порте из конфигурации config.json (по умолчанию 5000). Подробное описание конфигурации доступно здесь.

Linux

Для сборки приложения необходимы git, g++, cmake:

sudo apt-get install git g++ cmake

cmake и git должны быть доступны в Bash.

Сделайте git clone для загрузки проекта и перейдите в директорию. Сборка скрипта выполняется запуском скрипта build.sh:

git clone --branch=master --depth=1 https://github.com/green-api/whatsapp-api-webhook-server-cpp
cd whatsapp-api-webhook-server-cpp
.\build.sh

Приложение по умолчанию собирается с типом конфигурации Release.

После успешной сборки, повторная сборка приложения доступна через скрипт .\build.sh или

cmake --build build --config=Release

Исполняемый файл приложения находится в build/bin/. Файл конфигурации config.json и директория jsonSchema копируются в директорию build/bin. Приложение дает приоритет файлам build/bin, загружая файлы с директории проекта, только если не может найти файлы в build/bin.

Запуск приложения:

./build/bin/whatsapp-api-webhook-server-cpp

При исполнении программы создается сервер на порте из конфигурации config.json (по умолчанию 5000). Подробное описание конфигурации доступно здесь.

Docker

Для запуска сервера через Docker вам понадобится Docker и Docker Compose.

Вы можете установить Docker Desktop для всех платформ или установить Docker Engine для Linux.

Сделайте git clone для загрузки проекта и перейдите в директорию:

git clone --branch=master --depth=1 https://github.com/green-api/whatsapp-api-webhook-server-cpp
cd whatsapp-api-webhook-server-cpp

Перед сборкой контейнера Docker вам необходимо создать следующий файл:

  • source/user_adapter.cpp

Если у вас нет требуемого файла, создайте его путем удаления нижнего подчеркивания из названия ```source/_user_adapter.cpp`` файла.

Мы будем обновлять include/user_adapter.h и source/_user_adapter.cpp файлы по мере выпуска новых вебхуков. Если вы столкнулись с ошибкой сборки, где написано о том, что компилятор не смог найти требуемые функции из user_adapter, то в этом случае вам необходимо добавить новые функции из source/_user_adapter.cpp в ваш source/user_adapter.cpp

По умолчанию в образе открыт port 5000. Если вы хотите изменить порт, тогда:

  • Поменяйте поле Address в config.json на требуемый вами порт;

  • Поменяйте поле ports в docker-compose.yaml на требуемый вами порт;

Запустите Docker образ с помощью Docker Compose. Используйте флаг --build, если вы запускаете контейнер в первый раз или вы изменили файлы в проекте:

docker compose up --build

Сервер будет запущен автоматически после сборки проекта. Подробное описание конфигурации доступно здесь.

Запуск приложения

Исполняемый файл приложения находится в build/bin/.

Сервером используется config.json для установки следующих значений:

  • Address (по умолчанию: :5000). Сервер будет запущен на этом порту. Запросы должны отправляться на этот порт. Настройка инстанса;

  • Pattern (по умолчанию: /). Часть URI после порта: "Address""Pattern". Все запросы, отправленные на неверный pattern, будут отклонены. По умолчанию сервер обрабатывает запросы по URI = localhost:5000/. Настройка инстанса;

  • WebhookToken (по умолчанию: отсутствует). Токен авторизации в заголовке приходящего запроса должен совпадать с токеном в вашем инстансе green-api (по умолчанию отсутствует). Настройка инстанса;

  • LogToFile (по умолчанию: false). Данный флаг отвечает за создание файла и запись логов в него. Доступные значения: true, false.

  • LogToConsole (по умолчанию: false). Данный флаг отвечает за запись логов в консоль. Доступные значения: true, false.

  • LoggerFilename (по умолчанию: log.txt). Имя файла логгера.

После запуска приложения будет запущен сервер, использующий значения из конфига. Если конфиг отсутствует, будут использоваться значения по умолчанию.

Вы можете использовать Коллекцию Postman для тестирования сервера.

User Adapter

Для указания пользовательских функций при получении уведомления используются файлы user_adapter. В данных файлах вам требуется указать функции обработки уведомлений (например: запись уведомления в базу, отправка запроса в другой микросервис). В качестве шаблона можно переименовать файл source/_user_adapter.cpp. Пример обработки всех типов уведомлений доступен в файле user_adapter_example.cpp в папке examples.

Адаптер для пользователя находится в следующем файле:

  • source/user_adapter.cpp

Если у вас нет требуемого файла, создайте его путем удаления нижнего подчеркивания из названия ```source/_user_adapter.cpp`` файла.

Мы будем обновлять include/user_adapter.h и source/_user_adapter.cpp файлы по мере выпуска новых вебхуков. Если вы столкнулись с ошибкой сборки, где написано о том, что компилятор не смог найти требуемые функции из user_adapter, то в этом случае вам необходимо добавить новые функции из source/_user_adapter.cpp в ваш source/user_adapter.cpp.

Адаптер для пользователя содержит ваши обработчики вебхуков. Программа работает по следующему алгоритму:

  1. Запрос к серверу принимает класс webhook;

  2. Класс webhook создает объект Response и передает тело запроса классу Validator;

  3. После проверки, объект Response передается в обработчик User Adapter на основе webToken в теле запроса;

  4. Функция обработки в User Adapter возвращает true в случае ошибки или false, если обработка произошла без ошибок. На основе этого значения, сервер вернет или 200 OK или 400 Bad Request.

Структура объекта Response (response.h):

struct Response {
    bool error = true; // true, если вебхук не прошел валидацию
    std::string typeWebhook = ""; // webhookType из тела запроса
    std::string bodyStr = "";  // содержит тело запроса, если error = false, иначе описание ошибки валидации
    nlohmann::json bodyJson = ""; //  тело пришедшего запроса
}
  1. Функции в UserAdapter описываются как:
static bool onWebhookType(greenapi::Response& body);
  1. Пример функции UserAdapter:

В данном примере, обработчик будет вызван вебхуком с типом IncomingMessageReceived. С помощью структуры Response, описанной выше, вы можете проверить результат валидации запроса (body.error), обратиться к json структуре вебхука (body.bodyJson) или получить доступ к телу запроса (body.bodyStr).

bool UserAdapter::onIncomingMessageReceived(greenapi::Response& body) {
    // Каждый запрос содержит typeWebhook. Если typeWebhook нет в запросе, запрос отклоняется сервером.
    const auto typeWebhook = body.bodyJson["typeWebhook"];

    // Если вам нужно вернуть ошибку в процессе обработки запроса, верните true из этой функции.
    // Это изменит статус запроса на 400 Bad Request с немедленным возвратом результата HTTP запроса.
    // 
    // if (<error>) {
    //    return true;
    //}

    greenapi::Logger::Log("Received webhook: " + nlohmann::to_string(typeWebhook) + std::string(" with body: ") + body.bodyStr, "info");

    // Опишите ваш обработчик здесь:

    // Если нет ошибок, верните false. После этого сервер вернет статус запроса 200 OK
    return false;
}

Примеры

Примерны доступны в user_adapter_example.cpp.

Документация по методам вебхуков

https://green-api.com/docs/api/.

Валидация JSON

JSON схемы для проверки вебхуков расположены в директории jsonSchema и копируются в директорию сборки при запуске скрипта сборки. Вы можете добавлять любые файлы .json в build/bin/jsonSchema, они будут загружены в программу при ее запуске.

JSON схемы имеют следующую структуру:

{
  "$id": "schemas",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "yourNameOfObject": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "sampleField": {
          "type": "string"
        },
        "sampleRef_Field": {
          "$ref": "#/properties/commonSchemaComponents/properties/senderData"
        }
      },
      "required": [
        "typeWebhook",
      ],
      "additionalProperties": true
    },
    "yourOtherObject": {
        ...
    }
  }
}

Для работоспособности вашего .jsonфайла, любой .json файл должен содержать только один объект с "properties". Все объекты для валидации должны находиться в объекте "properties". В противном случае файл JSON будет проигнорирован.

Зависимости приложения

Лицензия

Лицензировано на условиях Creative Commons Attribution-NoDerivatives 4.0 International (CC BY-ND 4.0) . LICENSE.