Вы можете разрабатывать ботовые модули для чатов (внутреннее название сервиса — MessageGateway). Боты могут слушать то, что происходит в чатах, а также выполнять какие-либо действия с помощью Bot API: назначать диалоги на менеджеров или ботов, писать в чаты, реагировать на команды и др.
Вначале вам требуется зарегистрировать модуль в аккаунте CRM с помощью методов API. Подробнее про это написано ниже. При регистрации вам возвращается URL и токен для работы с Bot API сервиса MessageGateway. Вся дальнейшая работа строится с Bot API.
- Общая схема взаимодействия
- Регистрация и настройка бота
- Получение информации о боте
- Работа с 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-клиенты для ряда языков.
- Документация по Bot API
- Bot API клиент для Go
- Bot API клиент для Javascript
Если бот будет реагировать на команды, то их нужно зарегистрировать с помощью метода PUT /my/commands/{name} сразу после регистрации модуля бота.
Дальнейший типовой цикл работы с Bot API строится следующим образом:
- Бот подключается к WebSocket и начинает слушать интересующие его события
- При поступлении интересующих событий бот выполняет действия через вызовы методов Bot API
Важно!
Обеспечить обработку ситуации, когда веб-сокет штатно или нештатно закрывается со стороны MessageGateway, и бот с неким таймаутом пытается переподключиться к веб-сокету.