Rox.Chat CRM `postMessage` Interface

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.

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.

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.
`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.
`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).

Rox.Chat CRM postMessage Interface

Transmitted Events

Event newMessageAdded

Event chatClosedByOperator

Event visitorAuthorized

Event visitorSelected

Event notificationAdded

Event notificationRemoved

Incoming Events

Rox.Chat CRM `postMessage` Interface

Event `newMessageAdded`

Event `chatClosedByOperator`

Event `visitorAuthorized`

Event `visitorSelected`

Event `notificationAdded`

Event `notificationRemoved`