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

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

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

Наименование, типы методов и структура 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 —> Messenger)

Запрос на подключение мессенджера (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"
    }
}

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

{
    "id": "extUser1"
    "username": "JohnDoe"
    "phoneNumber": "89990002266"
    "avatar": "data:image/jpeg;base64,/9j/4AAQSkZJRg... "
}

Метод для получения метки о прочтении сообщения (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 (Messenger —> 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 — запрос-оповещение о прекращении взаимодействия по инициативе мессенджера.

Примеры запросов и ответов при взаимодействии ELMA365 с произвольным мессенджером

Рассмотрим примеры следующих типов взаимодействия ELMA365 с произвольным мессенджером: connect, message и userInfo.

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

В настройках подключения мессенджера в ELMA365 укажите его вебхук, а также строку подтверждения. После соединения в системе создаётся канал с уникальным ID. На вебхук мессенджера придёт событие типа connect, содержащее вебхук ELMA365:

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

Ответ: 200 — ОК.

Отправка сообщения из мессенджера в ELMA365.

Производится в несколько этапов:

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

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

Тело запроса:

{
    "type": "message",
    "token": "123",
    "data": {
        "externalMessageId": "extMsgId",
        "externalChatId": "extChat1",
        "externalChatName": "Chat name: chat 12",
        "externalUserId": "extUser1",
        "text": "sample",
        "files": [
            {
                "name": "file1.png",
                "URL": "https://elma365.com/ru/img/partners/partners-hero.png"
            }
        ]
    }
}

Ответ: 200 — ОК.

2. После того как в ELMA365 будет принято сообщение, от системы отправится запрос на получение информации о пользователе. На вебхук мессенджера придёт событие типа userInfo:

{
    "type": "userInfo",
    "token": "123",
    "data": {
        "userId": "extUser1"
    }
}

Пример ответа с информацией о пользователе от мессенджера:

{
    "id": "extUser1"
    "username": "JohnDoe"
    "phoneNumber": "89990002266"
    "avatar": "data:image/jpeg;base64,/9j/4AAQSkZJRg... "
}

3. Когда информация о пользователе поступит в ELMA365, на вебхук мессенджера придёт событие типа messageOutcome с оповещением об успешном получении сообщения системой:

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

Ответ: 200 — ОК.

Получение сообщения от ELMA365.

На вебхук мессенджера приходит событие типа message:

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

Ответ: 200 — ОК.

custom-messenger.html connect-bot.html

Была ли статья полезной?