# Webim CRM postMessage Interface
Для обмена информацией между **Webim**, встроенным через [iframe](https://webim.ru/kb/devops/admin-iframe.html) в другой веб-интерфейс (обычно это CRM), и этой CRM используется механизм [window.postMessage()](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage). postMessage позволит отправлять события между родительским окном CRM и встроенным в него РМО, а также обмениваться командами и осуществлять некоторые действия в CRM из РМО, не используя при этом интерфейс самой CRM.
## Передаваемые события
При включении postMessage-интеграции **Webim** начинает передавать в родительское окно CRM-системы события типов, описанных в данном разделе.
Для того, чтобы отправлять наборы данных CRM, на сервере **Webim** должны быть заданы соответствующие настройки, так как по умолчанию это запрещено из соображений безопасности. Если сервис **Webim** размещён на облачных серверах, то необходимо обращаться в техническую поддержку **Webim**. Если на ваших серверах, в [конфигурации аккаунта](https://webim.ru/kb/for-admins/service-pages/account-config-editor.html) в поле `operator_iframe_allowed_parent_origin` требуется добавить `origin` окна (окон), на которые требуется отправлять события.
В теории, РМО можно встроить в любую CRM, которая предусматривает возможность расширения своего интерфейса и вставки сторонних разработчиков в свой веб-интерфейс через iframe. На практике тестировалось встраивание через iframe в [Siebel CRM](https://www.oracle.com/cis/cx/siebel/).
Данные передаются в формате `JSON`.
Общий вид передаваемых данных:
```
{
"source": "webim",
"event": (тип события),
"params": (дополнительные параметры)
}
```
Пример передаваемых данных:
```
{
"source": "webim",
"event": "chatClosedByOperator",
"params": {
"webimVisitorId": "c3fa5841c772895f8645b33ac784f694",
"providedVisitorId": "12345",
"chatId": 1024,
"siebelId": "4-1GQJDL78",
"channelId": "073afd9ccfee448dba19a5c974940bfc",
"channelType": "vk",
"channelUserId": "16248561",
"channelUserName": "Пётр Петрович"
}
}
```
### Событие newMessageAdded
Событие вызывается, когда посетитель или оператор оставляет сообщение в чате. Пример полей объекта `params` для события `newMessageAdded`:
```
{
"webimVisitorId": "c3fa5841c772895f8645b33ac784f694",
"providedVisitorId": "12345",
"chatId": 483,
"sessionId" : "c9905a4eab2a4148add9b1c8ac97ad7d",
"kind": "visitor",
"messageText": "Здравствуйте",
"siebelId": "4-1GQDLH42"
}
```
Описание полей:
| Название параметра | Тип | Описание |
|---------------------|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `webimVisitorId` | `String` | Внутренний идентификатор посетителя в системе **Webim**.
Пример: `e01baca71a28557b52b4e6038d12bcb8` |
| `providedVisitorId` | `String` | Идентификатор посетителя, присваиваемый в системе клиента, сообщаемый клиентом сервису **Webim**. Его вид зависит от того, какого вида идентификаторы используются в системе клиента. |
| `chatId` | `Integer` | Идентификатор чата **Webim**, который создаётся, как правило, после первого сообщения посетителя.
Пример: `874` |
| `sessionId` | `String` | Идентификатор сессии **Webim**.
Пример: `c8405a4eab2a4945add9b1c8ac97ad7d` |
| `kind` | `String` | Тип сообщения. Полный перечень типов и подтипов сообщений можно посмотреть [здесь](https://webim.ru/kb/dev/basic-objects/message-types.html). |
| `messageText` | `String` | Текст сообщения. |
| `SiebelId` | `String` | Идентификатор посетителя в **CRM Siebel**.
Пример: `4-1GQJDL78` |
### Событие chatClosedByOperator
Событие вызывается, когда чат был закрыт оператором. Пример полей объекта params для события `chatClosedByOperator` (посетитель с канала общения ВКонтакте):
```
{
"webimVisitorId": "c3fa5841c772895f8645b33ac784f694",
"providedVisitorId": "12345",
"chatId": 1024
"siebelId": "4-1GQJDL78",
"channelId": "073afd9ccfee448dba19a5c974940bfc",
"channelType": "vk",
"channelUserId": "16248561",
"channelUserName": "Пётр Петрович"
}
```
Пример полей объекта params для события `chatClosedByOperator` (посетитель из неавторизованной зоны):
```
{
"webimVisitorId": "c3fa5841c772895f8645b33ac784f694",
"providedVisitorId": null,
"chatId": 1024
"siebelId": null,
"channelId": null,
"channelType": null,
"channelUserId": null,
"channelUserName": null
}
```
Описание полей:
| Название параметра | Тип | Описание |
|---------------------|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `webimVisitorId` | `String` | Внутренний идентификатор посетителя в системе **Webim**.
Пример: `e01baca71a28557b52b4e6038d12bcb8` |
| `providedVisitorId` | `String` | Идентификатор посетителя, присваиваемый в системе клиента, сообщаемый клиентом сервису **Webim**. Его вид зависит от того, какого вида идентификаторы используются в системе клиента. |
| `chatId` | `Integer` | Идентификатор чата **Webim**, который создаётся, как правило, после первого сообщения посетителя.
Пример: `874` |
| `SiebelId` | `String` | Идентификатор посетителя в **CRM Siebel**.
Пример: `4-1GQJDL78` |
| `channelId` | `String` | Идентификатор канала, из которого поступил чат, в системе **Webim**.
Пример: `073afd9ccfee448dba19a5c974940bfc` |
| `channelType` | `String` | Тип канала, откуда поступило обращение.
Пример: `telegram` |
| `channelUserId` | `String` | Идентификатор посетителя на стороне канала. Его вид зависит от того, какого вида идентификаторы используются в канале.
Пример: `95851142` (ID посетителя в Telegram) |
| `channelUserName` | `String` | Имя посетителя в канале, с которого поступил чат.
Пример: `username` |
### Событие visitorAuthorized
Событие вызывается, когда посетитель авторизуется. Общий вид:
```
{
"old": { //данные до авторизации
"webimVisitorId": "66b46319af05e55ac9fd34aa541e9eee",
"providedVisitorId": null,
"siebelId": null
},
"new": { //данные после авторизации
"webimVisitorId": "52eed6ec3c12494a88e62e2ff636c2a9",
"providedVisitorId": "7925",
"siebelId": null
}
}
```
Описание полей:
| Название параметра | Тип | Описание |
|---------------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `webimVisitorId` | `String` | Внутренний идентификатор посетителя в системе **Webim**.
Пример: `e01baca71a28557b52b4e6038d12bcb8` |
| `providedVisitorId` | `String` | Идентификатор посетителя, присваиваемый в системе клиента, сообщаемый клиентом сервису **Webim**. При каждой новой авторизации его значение заменяется на новое. Его вид зависит от того, какого вида идентификаторы используются в системе клиента. |
| `SiebelId` | `String` | Идентификатор посетителя в **CRM Siebel**.
Пример: `4-1GQJDL78` |
### Событие visitorSelected
Событие вызывается, когда оператор открыл чат с посетителем в РМО.
Пример:
```
{
"source": "webim",
"event": "visitorSelected",
"params": {
"webimVisitorId": "c3fa5841c772895f8645b33ac784f694",
"providedVisitorId": "12345",
"chatId": 1024,
"sessionId": "c9905a4eab2a4148add9b1c8ac97ad7d",
"taskId": "20913584",
"siebelId": "4-1GQJDL78",
"channel": {
"id": "873afd9cfeec448dba19a5c974940bfc",
"name": "webim test iframe chat example",
"type": "site"
},
"visitorFields": {
"phone": "+7 (999) 222-33-44",
"email": "user@example.com"
}
}
}
```
Описание полей `params`:
| Название параметра | Тип | Описание |
|---------------------|-----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `webimVisitorId` | `String` | Внутренний идентификатор посетителя в Webim. |
| `providedVisitorId` | `String` | Идентификатор посетителя, присвоенный внешней системой (например, CRM). Вид и формат зависят от клиентской системы. |
| `chatId` | `Integer` | Идентификатор чата Webim. |
| `sessionId` | `String` | Идентификатор сессии Webim. |
| `taskId` | `String` | Идентификатор задачи в CRM (если используется связка с роутером задач CRM). |
| `siebelId` | `String` | Идентификатор посетителя в CRM Siebel (если используется). |
| `channel` | `Object` | Структура с информацией о канале (точке входа): `id`, `name`, `type`. |
| `visitorFields` | `Object` | Набор визиторских полей, доступных в аккаунте. Гарантированно включает стандартные: `phone`, `email`. Возможны и другие поля, если они заведены в аккаунте. |
Структура `channel`:
| Поле | Тип | Описание |
|--------|--------|---------------------------------------------------------------------------------------------|
| `id` | String | Идентификатор канала в Webim. |
| `name` | String | Название канала (точка входа), если задано. Может быть `null`. |
| `type` | String | Тип канала (строковой код типа канала, используется для идентификации источника обращения). |
!!! Note "Нулевые значения"
Для отдельных размещений канала некоторые поля могут быть недоступны. В этом случае соответствующие значения в `channel` или `visitorFields` передаются как `null` или отсутствуют.
Для обратной совместимости возможен возврат плоских полей `channelName` и `visitorNumber` дополнительно к новым структурам. Включается через параметр account config `agent_iframe_visitor_selected_post_message_additional_fields`. По умолчанию пустой массив.
Пример значения:
```
["channelName", "visitorNumber"]
```
При включении новых полей структуры `channel` и `visitorFields` остаются в сообщении и не удаляются.
### Событие notificationAdded
Событие вызывается, когда приходит уведомление. Пример параметра `params` для события `notificationAdded`:
```
{
"notification": {
"id": "c9905a4eab2a4148add9b1c8ac97ad7d",
"kind": "visitor",
"text": "Посетитель покинул чат",
"sessionId": "c3fa5841c772895f8645b33ac784f694"
}
}
```
Описание полей параметра `params`:
| Название параметра | Тип | Описание |
|--------------------|----------|-----------------------------------------------------------------------------------|
| `id` | `String` | Идентификатор уведомления.
Пример: `c9905a4eab2a4148add9b1c8ac97ad7d` |
| `kind` | `String` | Тип уведомления. |
| `text` | `String` | Текст уведомления. |
| `sessionId` | `String` | Идентификатор сессии **Webim**.
Пример: `c3fa5841c772895f8645b33ac784f694` |
### Событие notificationRemoved
Событие вызывается, если уведомление было удалено (вне зависимости от того, было ли оно отсмотрено пользователем). Пример параметра `params` для события `notificationRemoved`:
```
{
"notification": {
"id": "c9905a4eab2a4148add9b1c8ac97ad7d",
}
}
```
Описание полей параметра `params`:
| Название параметра | Тип | Описание |
|--------------------|----------|------------------------------------------------------------------------------|
| `id` | `String` | Идентификатор уведомления.
Пример: `c9905a4eab2a4148add9b1c8ac97ad7d` |
## Приходящие события
При включении postMessage-интеграции **Webim** получает из родительского окна CRM-системы события типа `message`.
### Событие message
**Webim** прослушивает приходящие события типа `message`, при помощи которого родительское окно CRM передаёт данные в РМО через iframe.
Описание параметров события типа `message`:
| Название параметра | Тип | Пример | Описание | Обязательность |
|------------------------------|----------|------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------|----------------|
| `source` | `Object` | — | Ссылка на объект `window`, отправивший событие. `Source` может быть использован для установки соединения между окнами с разными `origins`. | Нет |
| `origin` | `String` | `https://somecrm.com` | URL-адрес CRM-системы клиента. | Да |
| `data.action` | `String` | `start_outgoing_chat` | Событие, отправляемое CRM-системой клиента. Может принимать значение `start_outgoing_chat`, при котором оператором начинается исходящий чат. | Да |
| `data.params.webimVisitorId` | `String` | `e01baca71a28557b52b4e6038d12bcb8` | Внутренний идентификатор посетителя в системе **Webim**. | Да |
| `data.params.sessionId` | `String` | `c8405a4eab2a4945add9b1c8ac97ad7d` | Идентификатор сессии **Webim**. | Да |
При неудачной попытке начать чат могут быть возвращены следующие ошибки, текст которых определяется в редакторе ресурсов:
| Код ошибки | Текст ошибки |
|-----------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------|
| `operator_cant_start_chat_with_visitor_from_another_department` | Вы не можете приглашать к диалогу посетителей из другого отдела. |
| `visitor_starting_chat_from_his_side` | Вы не можете пригласить к диалогу посетителя в связи с тем, что он начинает диалог со своей стороны. |
| `visitor_already_in_chat` | Посетитель уже в диалоге. |
| `no_tariff_option` | Для выполнения данного действия необходимо перейти на другой тариф либо подключить соответствующую тарифную опцию. |
| `unable_to_start_outgoing_chat` | При создании чата произошла ошибка [при неизвестной ошибке]. |
---
Источник: https://webim.ru/kb/dev/postmessage.html