Webim CRM postMessage Interface

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

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

Типы передаваемых событий (параметр event):

Для того, чтобы отправлять наборы данных 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

Событие вызывается, когда уведомление исчезает.

Пример параметра 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 Идентификатор посетителя на стороне канала.

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

Тип message

Webim прослушивает приходящие события типа message, при помощи которого родительское окно CRM передаёт данные в РМО через iframe. Данные из события парсятся и передаются в соответствующие обработчики.

Тип action

{
    "source": "external_source", // опционально
    "action": "start_outgoing_chat",
    "params": {
        "webimVisitorId": "c3fa5841c772895f8645b33ac784f694",
        "sessionId" : "c9905a4eab2a4148add9b1c8ac97ad7d"
    }
}

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

Название параметра Тип Описание
source String Внешний источник (CRM клиента), отправляющий событие. Может быть NULL.
action String Событие, отправляемое CRM-системой клиента. Может принимать значение start_outgoing_chat.
webimVisitorId String Внутренний идентификатор посетителя в системе Webim.
Пример: "e01baca71a28557b52b4e6038d12bcb8"
sessionId String Идентификатор сессии Webim.
Пример: "c8405a4eab2a4945add9b1c8ac97ad7d"