Webim CRM postMessage Interface

Для обмена информацией между Webim, встроенным через iframe в другой веб-интерфейс (обычно это CRM), и этой CRM используется механизм window.postMessage(). postMessage позволит отправлять события между родительским окном CRM и встроенным в него РМО, а также обмениваться командами и осуществлять некоторые действия в CRM из РМО, не используя при этом интерфейс самой CRM.

Передаваемые события

При включении postMessage-интеграции Webim начинает передавать в родительское окно CRM-системы события типов, описанных в данном разделе.

Для того, чтобы отправлять наборы данных CRM, на сервере Webim должны быть заданы соответствующие настройки, так как по умолчанию это запрещено из соображений безопасности. Если сервис Webim размещён на облачных серверах, то необходимо обращаться в техническую поддержку Webim. Если на ваших серверах, в конфигурации аккаунта в поле operator_iframe_allowed_parent_origin требуется добавить origin окна (окон), на которые требуется отправлять события.

В теории, РМО можно встроить в любую CRM, которая предусматривает возможность расширения своего интерфейса и вставки сторонних разработчиков в свой веб-интерфейс через iframe. На практике тестировалось встраивание через iframe в Siebel CRM.

Данные передаются в формате 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	Тип сообщения. Полный перечень типов и подтипов сообщений можно посмотреть здесь.
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

Событие вызывается, когда оператор открыл чат с посетителем в РМО.Пример:

{
    "webimVisitorId": "c3fa5841c772895f8645b33ac784f694",
    "providedVisitorId": "12345",
    "chatId": 874,
    "sessionId" : "c9905a4eab2a4148add9b1c8ac97ad7d",
    "taskId": "20913584",
    "siebelId": "4-1GQJDL78"
}

Описание полей:

Название параметра	Тип	Описание
webimVisitorId	String	Внутренний идентификатор посетителя в системе Webim. Пример: "e01baca71a28557b52b4e6038d12bcb8"
providedVisitorId	String	Идентификатор посетителя, присваиваемый в системе клиента, сообщаемый клиентом сервису Webim. Его вид зависит от того, какого вида идентификаторы используются в системе клиента.
chatId	Integer	Идентификатор чата Webim, который создаётся, как правило, после первого сообщения посетителя. Пример: 874
sessionId	String	Идентификатор сессии Webim. Пример: "c8405a4eab2a4945add9b1c8ac97ad7d"
taskId	String	Идентификатор задачи в CRM, обогащающий объект посетителя. Связан с siebelId. Используется в маршрутизаторе чатов.
SiebelId	String	Идентификатор посетителя в CRM Siebel. Пример: "4-1GQJDL78"

Событие 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"

Событие selectVisitorInSiebelButtonClick

Событие вызывается, когда оператор нажимает кнопку Siebel в РМО.Пример параметра params для события selectVisitorInSiebelButtonClick:

{
    "webimVisitorId": "e01baca71a28557b52b4e6038d12bcb8",
    "providedVisitorId": "12345",
    "visitorFields": {
        "id": "12345",
        "display_name": "Евгений",
        "phone": "+78123855337",
        "email": "abc@webim.ru"
    },
    "channelId": "142a171852f34530b4b66f7b0824812c",
    "channelType": "telegram",
    "channelUserId": "12578956"
}

Описание полей параметра params:

Название параметра	Тип	Описание
webimVisitorId	String	Внутренний идентификатор посетителя в системе Webim. Пример: "e01baca71a28557b52b4e6038d12bcb8"
providedVisitorId	String	Идентификатор посетителя, присваиваемый в системе клиента, сообщаемый клиентом сервису Webim. Его вид зависит от того, какого вида идентификаторы используются в системе клиента.
visitorFields	Json	Данные о посетителе, если есть. Если идентифицирующие посетителя данные предоставляются, то передавать их следует точно в соответствии со статьёй об идентификации.
channelId	String	Идентификатор канала, генерируется на стороне Webim, виден в настройках канала.
channelType	String	Название канала канала.
channelUserId	String	Идентификатор посетителя на стороне канала.

Приходящие события

При включении 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`	При создании чата произошла ошибка [при неизвестной ошибке].

Webim CRM postMessage Interface

СОДЕРЖАНИЕ

Передаваемые события

Событие newMessageAdded

Событие chatClosedByOperator

Событие visitorAuthorized

Событие visitorSelected

Событие notificationAdded

Событие notificationRemoved

Событие selectVisitorInSiebelButtonClick

Приходящие события

Событие message

Смотрите также: