# Запросы взаимодействия в произвольном мессенджере

> [HTML Version](custom-messenger-settings.html)

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

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

Логика работы оператора с сессиями клиентов реализуется в рамках стандартной логики [работы в линиях](live-chats-structure.md), предусмотренной для остальных мессенджеров, и не подразумевает дополнительной функциональности.

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

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

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

- наименование канала связи с мессенджером с типом `\[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

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

- \[OBJECT\] — токен, сформированный на стороне мессенджера; 

- \[OBJECT\] — ID канала в системе ELMA365; 

- \[OBJECT\] — ID чата в мессенджере;

- \[OBJECT\] — текст сообщения; 

- \[OBJECT\] — массив приложений. 

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

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

````
Если сообщение обработано успешно, то \[OBJECT\] будет в значении \[OBJECT\].

Если \[OBJECT\] или ответа не последовало, повторите отправку сообщения с указанным \[OBJECT\].

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

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

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

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

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

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

- \[OBJECT\] — токен, сформированный на стороне мессенджера; 

- \[OBJECT\] — ID канала в системе ELMA365; 

- \[OBJECT\] — ID пользователя в мессенджере.

Ответ:

- \[OBJECT\] — файл в 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

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

- \[OBJECT\] — токен, сформированный на стороне мессенджера; 

- \[OBJECT\] — ID сообщения в мессенджере; 

- \[OBJECT\] — ID чата в мессенджере; 

- \[OBJECT\] — ID пользователя в мессенджере; 

- \[OBJECT\] — текст сообщения;

- \[OBJECT\] — массив приложений.

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

````
\{  
    "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): 

- \[OBJECT\] — запрос на создание соединения. Используется всегда при создании нового канала в системе ELMA365. Служит для закрытия потребности стороннего мессенджера в подготовке данных. Если вам не требуется подготовка данных, верните код 200;

- \[OBJECT\] — запрос на отправку сообщения клиенту от оператора;

- \[OBJECT\] — запрос на получение данных о пользователе: ФИО, логин (уникальный идентификатор), номер телефона, аватар и т. д.;

- \[OBJECT\] — запрос на пометку сообщения, как прочитанное, в стороннем мессенджере;

- \[OBJECT\] — запрос-оповещение о прекращении взаимодействия с мессенджером.

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

- \[OBJECT\] — запрос на отправку сообщения оператору от клиента;

- \[OBJECT\] — запрос-оповещение о прекращении взаимодействия по инициативе мессенджера.

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

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

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

В [настройках подключения мессенджера](custom-messenger.md#custom-messenger-settings) в ELMA365 укажите его вебхук, а также строку подтверждения. После соединения в системе создаётся канал с уникальным ID. На вебхук мессенджера придёт событие типа \[OBJECT\], содержащее вебхук 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 — ОК.

2. Отправка сообщения из мессенджера в 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 будет принято сообщение, от системы отправится запрос на получение информации о пользователе. На вебхук мессенджера придёт событие типа \[OBJECT\]:

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

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

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

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

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

````
Ответ: 200 — ОК.

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

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

````
\{  
    "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 — ОК.