Общие сведения
Наименование, типы методов и структура 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"
}
}
Пример ответа на запрос:
{
"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 (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
— запрос-оповещение о прекращении взаимодействия по инициативе мессенджера.
Примеры запросов и ответов при взаимодействии 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 — ОК.