retailCRM Документация

Порядок интеграции бота с системой

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

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

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


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

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

Регистрация нового бота, а также изменение настроек существующего производится с помощью метода 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.

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

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

{
    "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

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

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

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

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

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


Редакция от 27.09.2018 11:35