Порядок интеграции бота с системой
Скопировать ссылку на статью
Скопировано

Вы можете разрабатывать ботовые модули для чатов (внутреннее название сервиса — MessageGateway). Боты могут слушать то, что происходит в чатах, а также выполнять какие-либо действия с помощью Bot API: назначать диалоги на менеджеров или ботов, писать в чаты, реагировать на команды и др.

Вначале вам требуется зарегистрировать модуль в аккаунте CRM с помощью методов API. Подробнее про это написано ниже. При регистрации вам возвращается URL и токен для работы с Bot API сервиса MessageGateway. Вся дальнейшая работа строится с Bot API.

Общая схема взаимодействия


          Бот                      Пользователь                   CRM                  MessageGateway 
       --------------------------------------------------------------------------------------------------
            |                           |                          |                          |
1.          |                        Создание  ------------------> |                          |
            |                       API-ключа                      |                          |
            |                           |                          |                          |
            |                           |                          |                          |
2.          |                        Нажимает                      |                          |
            |                   кнопку «Подключить» -------------> |                          |
            |                    в карточке Модуля                 |                          |
            |                     в Маркетплейсе                   |                          |
            |                           |                    Перенаправление                  |
3.          | <-------------------------------------------    Пользователя                    |
            |                           |                  на форму настройки                 |
            |                           |                  и включения Модуля                 |
4.          | <------------------ Заполняет форму                  |                          |      
            |                           |                          |                          |
5.   Проверка API-ключа,                |                          |                          |
     прав для API-ключа  ----------------------------------------> |                          |
       и API-версии                     |                          |                          |
            |                           |                          |                          |
6.      Регистрация                     |                       Получение                     |
           бота  ------------------------------------------->    токена   ------------------> |
            |                           |                          |                          |
            |                           |                    Возврат токена                   |
7.          | <---------------------------------------     и url для доступа к                |
            |                           |                     MessageGateway                  |
            |                           |                          |                          |
            |                           |                          |                          |
8.          |                    Заполняет форму  с                |                          |
            | <---------------    настройками бота                 |                          |
            |                           |                          |                          |
9.      Сохранение                      |                          |                          |
       настроек бота -----------------------------------------------------------------------> |
            |                           |                          |                          |
10.   Перенаправление                   |                          |                          |
       пользователя    ------------------------------------------> |                          |
        в аккаунт                       |                          |                          |
           CRM                          |                          |                          |
            |                           |                          |                          |
       --------------------------------------------------------------------------------------------------

Регистрация и настройка бота

Регистрация нового бота, а также изменение настроек существующего производится с помощью метода POST /api/v5/integration-modules/{code}/edit, в который обязательно нужно передать пустой параметр integrationModule[integrations][mgBot]={}. Если модуль с кодом code уже существует, метод меняет его настройки, в противном случае создается новый модуль.

При регистрации необходимо указать название integrationModule[name], код integrationModule[code], базовый url integrationModule[baseUrl] и уникальный код integrationModule[clientId], для возможности идентификации аккаунта системы. В случае успешной регистрации в ответе будет содержаться адрес MessageGateway Bot API (info[mgBot][endpointUrl]) и ключ доступа к нему (info[mgBot][token]). Дальнейшая настройка бота должна выполняться в MessageGateway посредством Bot API.

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

Пример запроса:

{
    "code": "awesomebot-101",
    "integrationCode": "awesomebot",
    "active": true,
    "name": "Awesome Bot",
    "logo": "http://download.awesomebot.server.net/logos/robot.svg",
    "clientId": "client-101",
    "baseUrl": "https://awesomebot.server.net",
    "accountUrl": "https://awesomebot.server.net/profile/client-101",
    "actions": {
        "activity": "/activity"
    },
    "integrations": {
        "mgBot": {}
    }
}

Пример ответа:

{
  "success": true,
  "info": {
    "mgBot": {
      "endpointUrl": "http://127.0.0.1:8080",
      "token": "5bbdfd67ed17486e32363c95d462a39a138b215ccd9f87ef4c23e8f89f18e10a5"
    }
  }
}

Получение информации о боте

Получение информации о боте с помощью метода GET /api/v5/integration-modules/{code}.

Пример ответа:

{
  "success": true,
  "integrationModule": {
    "code": "awesomebot-101",
    "integrationCode": "awesomebot",
    "active": true,
    "freeze": false,
    "name": "Awesome Bot",
    "logo": "http://download.awesomebot.server.net/logos/robot.svg",
    "native": false,
    "clientId": "client-101",
    "baseUrl": "https://awesomebot.server.net/",
    "actions": {
      "activity": "/activity"
    },
    "availableCountries": [],
    "accountUrl": "https://awesomebot.server.net/profile/client101",
    "integrations": {
      "mgBot": {
        "token": "5bbdfd67ed17486e32363c95d462a39a138b215ccd9f87ef4c23e8f89f18e10a5",
        "isActive": true
      }
    }
  }
}

Работа с Bot API

API Endpoint: https://mg-s1.retailcrm.pro/api/bot/v1/

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

Для каждого запроса необходимо передавать этот токен в заголовке
X-Bot-Token:X2EDxEta9U3lcsSV0dwdF38UvtSCxIuGh

Важно!

При обращении действует ограничение - 30 запросов в секунду с одного токена. При превышении лимитов по частоте запросов API возвращает ответ с HTTP-статусом 429 Too Many Requests.

Если вы не сохранили токен при регистрации, то вы можете получить его вместе с информацией о боте.

Ниже приведены ссылки на документацию для Bot API, а также на готовые API-клиенты для ряда языков.

Если бот будет реагировать на команды, то их нужно зарегистрировать с помощью метода PUT /my/commands/{name} сразу после регистрации модуля бота.

Дальнейший типовой цикл работы с Bot API строится следующим образом:

  1. Бот подключается к WebSocket и начинает слушать интересующие его события
  2. При поступлении интересующих событий бот выполняет действия через вызовы методов Bot API

Важно!

Обеспечить обработку ситуации, когда веб-сокет штатно или нештатно закрывается со стороны MessageGateway, и бот с неким таймаутом пытается переподключиться к веб-сокету.

Благодарим за отзыв.
Была ли статья полезна?
Нет
  • Рекомендации не помогли
  • Нет ответа на мой вопрос
  • Текст трудно понять
  • Не нравится описанный функционал
Да
Предыдущая статья
Порядок интеграции платежной системы через API
Порядок интеграции платежной системы через API.
Следующая статья
Порядок интеграции мессенджера с системой
Порядок интеграции мессенджера с системой.