search string side menu

Подключить линию к мессенджерам > Произвольный мессенджер / Настройка запросов взаимодействия в произвольном мессенджере

Настройка запросов взаимодействия в произвольном мессенджере

Общие сведения

Наименование, типы методов и структура JSON-ответов разработаны в соответствии с принятыми стандартами ELMA365 и не могут быть изменены клиентом.

Базовые URL и token для взаимодействия систем прописаны в настройках мессенджера.

Логика работы оператора с сессиями клиентов реализуется в рамках стандартной логики решения ELMA365 Service, предусмотренной для остальных мессенджеров, и не подразумевает дополнительной функциональности.

Настройка мессенджера

Подключение произвольного мессенджера к линии производится аналогично другим доступным мессенджерам. Подробнее об этом читайте в разделе «Подключить линию к мессенджерам».

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

  • наименование канала связи с мессенджером с типом [string]. Не влияет на взаимодействие с мессенджером. Служит дополнительной информацией и отображается в списке подключённых каналов для администратора и в сессии для оператора;
  • токен доступа к API стороннего мессенджера (строка подтверждения) с типом [string]. Заполняется при создании канала для связи с мессенджером. Будет передаваться с каждым сообщением из системы ELMA365 в мессенджер. Может быть пустой;
  • API URL мессенджера с типом [string] — URL (вебхук), на который будут отправляться сообщения из системы ELMA365.

API

Ниже приведены методы для взаимодействия пользовательского мессенджера с ELMA365.

Все методы должны возвращать следующие значения:

  • 200 — ОК;
  • 401 — Unauthorized. Возвращается, если токен не совпадает;
  • 404 — Not Found. Возвращается, если канала не существует;
  • 500 — Internal Server Error. Возвращается в случае непредвиденной ошибки сервера.

Все методы имеют неизменяемый префикс — базовый URL, установленный настройками инсталляции ELMA365 и компании.

Методы взаимодействия ELMA365 с мессенджером (ELMA365 —> Messendger)

Запрос на подключение мессенджера (POST Connect)

Строка запроса:

https://my-domen.com/api/messengers/external/test/webhook

Параметры для запроса:

  • token — токен, сформированный на стороне мессенджера;
  • channelId — ID канала в системе ELMA365;
  • data.webhook — вебхук для отправки запросов в систему ELMA365.

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

{
    "type": "connect",
    "token": "confirm",
    "channelId": "ebf45efc-cc67-4b60-9e3f-121966ba9f30",
    "data": {
        "webhook": "https://my-domen.com/api/messengers/external/other/webhook/ebf45efc-cc67-4b60-9e3f-121966ba9f30"
    }
}

Метод отправки сообщения в мессенджер (POST Send Message)

Строка запроса:

https://my-domen.com/api/messengers/external/test/webhook

Параметры для запроса:

  • token — токен, сформированный на стороне мессенджера;
  • channelId — ID канала в системе ELMA365;
  • data.targetChatId — ID чата в мессенджере;
  • data.text — текст сообщения;
  • data.files — массив приложений.

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

{
    "type": "message",
    "token": "confirm",
    "channelId": "ebf45efc-cc67-4b60-9e3f-121966ba9f30",
    "data": {
        "targetChatId": "chat1",
        "text": "text",
        "files": [
            {
                "name": "file1.png",
                "size": 12345,
                "URL": "https://elma365.com/ru/img/partners/partners-hero.png"
            }
        ]
    }
}

Метод отправки результата приёма сообщения (POST Send Message Outcome)

Строка запроса:

https://my-domen.com/api/messengers/external/test/webhook

Если сообщение обработано успешно, то success будет в значении true.

Если success = false или ответа не последовало, повторите отправку сообщения с указанным messageId.

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

{
    "type": "messageOutcome",
    "token": "confirm",
    "data": {
        "success": true,
        "messageId": "message1"
    }
}

Метод запроса данных пользователя (POST Get User Info)

Строка запроса:

https://my-domen.com/api/messengers/external/test/webhook

Параметры для запроса:

  • token — токен, сформированный на стороне мессенджера;
  • channelId — ID канала в системе ELMA365;
  • data.userId — ID пользователя в мессенджере.

Ответ:

  • Avatar — файл в base64.

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

{
    "type": "userInfo",
    "token": "confirm",
    "data": {
        "userId": "user1"
    }
}

Метод для получения метки о прочтении сообщения (POST Mark Message As Read)

Строка запроса:

https://my-domen.com/api/messengers/external/test/webhook

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

{
    "type": "markAsRead",
    "token": "confirm",
    "data": {
        "messageId": "message1"
    }
}

Метод запроса-оповещения о разрыве соединения с мессенджером (POST Disconnect)

Строка запроса:

https://my-domen.com/api/messengers/external/test/webhook

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

{
    "type": "disconnect",
    "token": "confirm",
    "channelId": "ebf45efc-cc67-4b60-9e3f-121966ba9f30"
}

Методы взаимодействия мессенджера с ELMA365 (Messendger —> ELMA365)

Метод отправки сообщения в ELMA365 (POST Send Message)

Строка запроса:

https://my-domen.com/api/messengers/external/other/webhook/8ec8228f-7ff2-462b-a8d7-4f9b3f62c253

Параметры для запроса:

  • token — токен, сформированный на стороне мессенджера;
  • data.externalMessageId — ID сообщения в мессенджере;
  • data.externalChatId — ID чата в мессенджере;
  • data.externalUserId — ID пользователя в мессенджере;
  • data.text — текст сообщения;
  • data.files — массив приложений.

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

{
    "type": "message",
    "token": "confirm2",
    "data": {
        "externalMessageId": "message63",
        "externalChatId": "chat12",
        "externalChatName": "Chat name: chat 12",
        "externalUserId": "user12",
        "text": "text test",
        "files": [
            {
                "name": "file1.png",
                "URL": "https://elma365.com/ru/img/partners/partners-hero.png"
            }
        ]
    }
}

Метод запроса-оповещения о разрыве соединения по инициативе мессенджера (POST Disconnect)

Строка запроса:

https://my-domen.com/api/messengers/external/other/webhook/ebf45efc-cc67-4b60-9e3f-121966ba9f30

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

{
    "type": "disconnect",
    "token": "confirm"
}

Метод запроса данных пользователя (POST Get User Info)

Строка запроса:

https://my-domen.com/api/messengers/external/other/webhook/c5f9889f-0fcc-4112-a8bd-d1a93cd5ab53

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

{
    "type": "userInfo",
    "token": "confirm",
    "data": {
        "userId": "95806fe5-f8e8-460c-b2be-ce607068726c"
    }
}

Запросы взаимодействия

Все запросы отправляются на вебхук (API URL мессенджера) и содержат в себе следующую информацию:

  • token мессенджера;
  • тип запроса;
  • данные запроса.

Все запросы должны получить ответ 200, как успешное выполнение запроса.

Типы запросов для взаимодействия ELMA365 с мессенджером (ELMA365 → Messenger):

  • Connect — запрос на создание соединения. Используется всегда при создании нового канала в системе ELMA365. Служит для закрытия потребности стороннего мессенджера в подготовке данных. Если вам не требуется подготовка данных, верните код 200;
  • Message — запрос на отправку сообщения клиенту от оператора;
  • UserInfo — запрос на получение данных о пользователе: ФИО, логин (уникальный идентификатор), номер телефона, аватар и т. д.;
  • MarkMessageAsRead — запрос на пометку сообщения, как прочитанное, в стороннем мессенджере;
  • Disconnect — запрос-оповещение о прекращении взаимодействия с мессенджером.

Типы запросов для взаимодействия мессенджера с ELMA365 (Messenger → ELMA365):

  • Message — запрос на отправку сообщения оператору от клиента;
  • Disconnect — запрос-оповещение о прекращении взаимодействия по инициативе мессенджера.
custom-messenger.html connect-bot.html