Skip to content

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