Source: https://rox.chat/kb/pt/dev/postmessage.html
> To exchange information between Rox.Chat, embedded through an iframe into another web interface (usually a CRM), and this CRM, the window.postMessage() mechanism is used. postMessage allows you to send events between the parent window of the CRM and the embedded Agent Workspace, as well as exchange commands and perform some actions in the CRM from the Agent Workspace, without using the CRM interface itself.
# Rox.Chat CRM `postMessage` Interface
To exchange information between Rox.Chat, embedded through an [iframe](https://rox.chat/kb/pt/dev/iframe.html) into another web interface (usually a CRM), and this CRM, the [window.postMessage()](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) mechanism is used. `postMessage` allows you to send events between the parent window of the CRM and the embedded **Agent Workspace**, as well as exchange commands and perform some actions in the CRM from the **Agent Workspace**, without using the CRM interface itself.
## Transmitted Events
When enabling `postMessage` integration, **Rox.Chat** begins to transmit events of the types described in this section to the parent window of the CRM system.
To send data sets to the CRM, the corresponding settings must be specified on the **Rox.Chat** server, as this is prohibited by default for security reasons. If the **Rox.Chat** service is hosted on cloud servers, you need to contact **Rox.Chat** technical support. If it is on your servers, you need to add the `origin` of the window(s) to which events are to be sent in the `operator_iframe_allowed_parent_origin` field in the account configuration
In theory, the **Agent Workspace** can be embedded in any CRM that allows for the expansion of its interface and the insertion of third-party developments into its web interface through an iframe. In practice, embedding through an iframe has been tested in [Siebel CRM](https://www.oracle.com/cis/cx/siebel/).
Data is transmitted in `JSON` format.
The general view of the transmitted data:
```
{
"source": "roxchat",
"event": (event type),
"params": (additional parameters)
}
```
Example of transmitting data:
```
{
"source": "roxchat",
"event": "chatClosedByOperator",
"params": {
"roxchatVisitorId": "c3fa5841c772895f8645b33ac784f694",
"providedVisitorId": "12345",
"chatId": 1024,
"siebelId": "4-1GQJDL78",
"channelId": "073afd9ccfee448dba19a5c974940bfc",
"channelType": "skype",
"channelUserId": "16248561",
"channelUserName": "John Doe"
}
}
```
### Event `newMessageAdded`
This event is triggered when a visitor or an agent leaves a message in the chat. Here is an example of the `params` object fields for the `newMessageAdded` event:
```
{
"roxchatVisitorId": "c3fa5841c772895f8645b33ac784f694",
"providedVisitorId": "12345",
"chatId": 483,
"sessionId" : "c9905a4eab2a4148add9b1c8ac97ad7d",
"kind": "visitor",
"messageText": "Greetings!",
"siebelId": "4-1GQDLH42"
}
```
Field descriptions:
| Parameter Name | Type | Description |
| ------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `roxchatVisitorId` | `String` | The internal identifier for the visitor in the **Rox.Chat** system.
Example: `e01baca71a28557b52b4e6038d12bcb8` |
| `providedVisitorId` | `String` | The identifier for the visitor, assigned in the client's system and communicated to the **Rox.Chat** service. Its format depends on the type of identifiers used in the client's system. |
| `chatId` | `Integer` | The **Rox.Chat** chat identifier, generally created after the visitor's first message.
Example: `874` |
| `sessionId` | `String` | The **Rox.Chat** session identifier.
Example: `c8405a4eab2a4945add9b1c8ac97ad7d` |
| `kind` | `String` | The message type. You can find the complete list of message types and subtypes [here](https://rox.chat/kb/pt/dev/basic-objects/message-types.html). |
| `messageText` | `String` | The message text. |
| `SiebelId` | `String` | The visitor identifier in **Siebel CRM**.
Example: `4-1GQJDL78` |
### Event `chatClosedByOperator`
This event is triggered when the chat is closed by the agent. Here is an example of the params object fields for the `chatClosedByOperator` event (visitor from the **Skype** communication channel):
```
{
"roxchatVisitorId": "c3fa5841c772895f8645b33ac784f694",
"providedVisitorId": "12345",
"chatId": 1024
"siebelId": "4-1GQJDL78",
"channelId": "073afd9ccfee448dba19a5c974940bfc",
"channelType": "skype",
"channelUserId": "16248561",
"channelUserName": "John Doe"
}
```
Example of the `params` object fields for the `chatClosedByOperator` event (visitor from an unauthorized zone):
```
{
"roxchatVisitorId": "c3fa5841c772895f8645b33ac784f694",
"providedVisitorId": null,
"chatId": 1024
"siebelId": null,
"channelId": null,
"channelType": null,
"channelUserId": null,
"channelUserName": null
}
```
Field descriptions:
| Parameter Name | Type | Description |
| ------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `roxchatVisitorId` | `String` | The internal identifier for the visitor in the **Rox.Chat** system.
Example: `e01baca71a28557b52b4e6038d12bcb8` |
| `providedVisitorId` | `String` | The identifier for the visitor, assigned in the client's system and communicated to the **Rox.Chat** service. Its format depends on the type of identifiers used in the client's system. |
| `chatId` | `Integer` | The **Rox.Chat** chat identifier, generally created after the visitor's first message.
Example: `874` |
| `SiebelId` | `String` | The visitor identifier in **Siebel CRM**.
Example: `4-1GQJDL78` |
| `channelId` | `String` | The identifier of the channel from which the chat originated, in the **Rox.Chat** system.
Example: `073afd9ccfee448dba19a5c974940bfc` |
| `channelType` | `String` | The type of channel from which the inquiry came.
Example: `telegram` |
| `channelUserId` | `String` | The identifier of the visitor on the channel side. Its form depends on the kind of identifiers used in the channel.
Example: `95851142` (visitor ID in **Telegram**) |
| `channelUserName` | `String` | The name of the visitor in the channel from which the chat originated.
Example: `username` |
### Event `visitorAuthorized`
The event is triggered when the visitor authorizes. General view:
```
{
"old": { // data before authorization
"roxchatVisitorId": "66b46319af05e55ac9fd34aa541e9eee",
"providedVisitorId": null,
"siebelId": null
},
"new": { // data after authorization
"roxchatVisitorId": "52eed6ec3c12494a88e62e2ff636c2a9",
"providedVisitorId": "7925",
"siebelId": null
}
}
```
Field descriptions:
| Parameter Name | Type | Description |
| ------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `roxchatVisitorId` | `String` | The internal identifier for the visitor in the **Rox.Chat** system.
Example: `e01baca71a28557b52b4e6038d12bcb8` |
| `providedVisitorId` | `String` | The identifier for the visitor, assigned in the client's system and communicated to the **Rox.Chat** service. Its format depends on the type of identifiers used in the client's system. |
| `SiebelId` | `String` | The visitor identifier in **Siebel CRM**.
Example: `4-1GQJDL78` |
### Event `visitorSelected`
The event is triggered when the agent opens a chat with a visitor in the **Agent Workspace**. Example:
```
{
"roxchatVisitorId": "c3fa5841c772895f8645b33ac784f694",
"providedVisitorId": "12345",
"chatId": 874,
"sessionId" : "c9905a4eab2a4148add9b1c8ac97ad7d",
"taskId": "20913584",
"siebelId": "4-1GQJDL78"
}
```
Field descriptions:
| Parameter Name | Type | Description |
| ------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `roxchatVisitorId` | `String` | The internal identifier for the visitor in the **Rox.Chat** system.
Example: `e01baca71a28557b52b4e6038d12bcb8` |
| `providedVisitorId` | `String` | The identifier for the visitor, assigned in the client's system and communicated to the **Rox.Chat** service. Its format depends on the type of identifiers used in the client's system. |
| `chatId` | `Integer` | The **Rox.Chat** chat identifier, generally created after the visitor's first message.
Example: `874` |
| `sessionId` | `String` | The **Rox.Chat** session identifier.
Example: `c8405a4eab2a4945add9b1c8ac97ad7d` |
| `taskId` | `String` | The task identifier in the CRM, enriching the visitor object. It is associated with `siebelId`. Used in the [chat router](https://rox.chat/kb/pt/dev/chat-router.html). |
| `SiebelId` | `String` | The visitor identifier in **Siebel CRM**.
Example: `4-1GQJDL78` |
### Event `notificationAdded`
The event is triggered when a notification arrives. Example of the `params` parameter for the `notificationAdded` event:
```
{
"notification": {
"id": "c9905a4eab2a4148add9b1c8ac97ad7d",
"kind": "visitor",
"text": "Visitor left the site",
"sessionId": "c3fa5841c772895f8645b33ac784f694"
}
}
```
Description of the `params` parameter fields:
| Parameter Name | Type | Description |
| -------------- | -------- | ----------------------------------------------------------------------------------- |
| `id` | `String` | Notification identifier.
Example: `c9905a4eab2a4148add9b1c8ac97ad7d` |
| `kind` | `String` | Notification type. |
| `text` | `String` | Notification text. |
| `sessionId` | `String` | **Rox.Chat** session identifier.
Example: `c3fa5841c772895f8645b33ac784f694` |
### Event `notificationRemoved`
The event is triggered if a notification has been removed (regardless of whether it was viewed by the user). Example of the `params` parameter for the `notificationRemoved` event:
```
{
"notification": {
"id": "c9905a4eab2a4148add9b1c8ac97ad7d",
}
}
```
Description of the `params` parameter fields:
| Parameter Name | Type | Description |
| -------------- | -------- | --------------------------------------------------------------------------- |
| `id` | `String` | Notification identifier.
Example: `c9905a4eab2a4148add9b1c8ac97ad7d` |
## Incoming Events
Rox.Chat listens for incoming message type events, through which the parent CRM window transmits data to the **Agent Workspace through an iframe.
Description of the parameters of the `message` type event:
| Parameter Name | Type | Example | Description | Mandatory |
| ------------------------------ | -------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| `source` | `Object` | — | Reference to the `window` object that sent the event. Source can be used to establish a connection between windows with different `origins`. | No |
| `origin` | `String` | `https://somecrm.com` | The URL of the client's CRM system. | Yes |
| `data.action` | `String` | `start_outgoing_chat` | The event sent by the client's CRM system. It can take the value `start_outgoing_chat`, which starts an outgoing chat initiated by the agent. | Yes |
| `data.params.roxchatVisitorId` | `String` | `e01baca71a28557b52b4e6038d12bcb8` | The internal identifier of the visitor in the **Rox.Chat** system. | Yes |
| `data.params.sessionId` | `String` | `c8405a4eab2a4945add9b1c8ac97ad7d` | The session identifier in the **Rox.Chat** system. | Yes |
In the event of a failed attempt to start a chat, the following errors can be returned, the text of which is defined in the resource editor:
| Error code | Error text |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `operator_cant_start_chat_with_visitor_from_another_department` | You cannot invite visitors from another department to the chat. |
| `visitor_starting_chat_from_his_side` | You cannot invite the visitor to the chat because they are initiating the chat from their side. |
| `visitor_already_in_chat` | The visitor is already chatting. |
| `no_tariff_option` | To perform this action, you need to switch to another tariff or connect the appropriate tariff option. |
| `unable_to_start_outgoing_chat` | An error occurred while creating the chat (in case of an unknown error). |