Skip to content

Chat Event Handlers

In this article, the mechanism for connecting external handlers for events occurring in the chat via the HTTP interface is described. Handlers allow configuring integration with external systems (CRM and others). Using webhooks, Rox.Chat sends the client system information about the main actions that occur in the system when processing chats, and this mechanism is essentially a "reverse API".

Integration Setup

To activate event sending, specify in the section General Settings -> Integration the URLs to which Rox.Chat will send data.

If Basic Auth is used when contacting, specify the authorization data as in the example below:

https://username:password@www.company.com/handler/roxchat_chat_start.php

Event Description

Rox.Chat sends three types of events: chat started, chat handled by the agent, chat closed.

  • chat_started: the event is sent at the moment of chat creation; only one event is possible for each chat.

  • chat_assigned: the event is sent when assigning a chat to an agent. Assignments can be several times for one chat.

  • chat_closed: the event is sent upon final completion of the chat; only one event is possible for each chat.

The chat finally closes either by the timeout_for_chat_auto_close_if_chat_is_inactive timeout or the timeout_for_chat_auto_close_if_closed_by_operator timeout, read more about timeouts in this article. If you need to finally close the chat immediately after the agent clicked the Close Chat button, contact the Rox.Chat technical support service with a request to activate the operator_closes_chat_finally parameter.

Features of the Data Transfer Mechanism

When an action is performed that fits one of the types of events, the Rox.Chat Server sends a corresponding request to the client's CRM system to the URL specified in the integration settings. Sending a request can be accompanied by a delay of up to 5 seconds. Currently, events are performed asynchronously, independently of each other, so the original sequence of events may not be observed, but this does not affect the system's performance.

Description of the Transmitted Data

Events are sent to the specified address by a POST request via the HTTP protocol with the header "Content-Type": "application/x-www-form-urlencoded". The same data structures are transmitted for all events, the types of requests are similar, only the chat states at the time of sending differ. Data is transmitted in the query string parameters of the request, despite the fact that the type of request is POST, and the request body (body) is sent empty. Fields transmitted in the request:

  • signature: checksum from the chat field.

  • chat: data about the dialogue, messages, and service information.

Chat Object Content

You can see an example of the transmitted data below. Parameter descriptions:

Parameter Name Parameter Description
category Chat category, assigned by the agent.
start_page The page where the user initiated the chat.
subcategory Chat subcategory, assigned by the agent.
locale Visitor's language.
visitor User data.
created_at Date and time when the chat started.
messages Array of messages in the chat at the time of event sending.
department_key Text identifier of the department the visitor contacted.
operator Agent data.
id Unique chat number in the Rox.Chat system.
visit_session Visitor session data.

Visitor Object Content

Parameter Name Parameter Description
fields Additional details about the user, provided if data is available.
id Unique user number in the Rox.Chat system.

Messages Object Instance Content

Parameter Name Parameter Description
created_at Message sending time.
message Message text.
kind Message kind (see Message Kinds and Subkinds).

Operator Object Content

Parameter Name Parameter Description
id Unique agent number in the Rox.Chat system.
email Agent's email.
name Symbolic agent identifier.

Visit_session Object Content

Parameter Name Parameter Description
ip Visitor's IP address.
landing_page The page the visitor was on before opening the chat.

Checksum Calculation

To ensure data authenticity, a checksum is transmitted along with it, calculated using the following algorithm:

  1. Create a string: chat content + private key. There are no characters between the object content and the private key.

  2. Calculate the checksum of the string created in step 1 using the SHA256 algorithm.

  3. Record the obtained string in signature.

Examples of transmitting data

{
   "Timestamp":"2023-06-26T19:25:57.418306Z",
   "Method":"POST",
   "RemoteAddr":"104.234.65.36",
   "ID":452862475,
   "Headers":{
      "Accept":[
         "*/*"
      ],
      "Content-Length":[
         "3457"
      ],
      "Content-Type":[
         "application/x-www-form-urlencoded"
      ],
      "Host":[
         "ptsv2.com"
      ],
      "User-Agent":[
         "python-requests/2.22.0"
      ],
      "X-Cloud-Trace-Context":[
         "9f4559001f74185b93ea0227212d390e/120038278221001008"
      ],
      "X-Google-Apps-Metadata":[
         "domain=gmail.com,host=ptsv2.com"
      ]
   },
   "FormValues":{
      "chat":[
         "{
            "category": null,
            "start_page": {
               "url": "https://mycompany.com"
            },    
            "subcategory": null,
            "locale": "en",
            "visitor": {
               "fields": {
                  "name": "Visitor"
               },
            "id": "afa6083ca15a40d6aa94a8ee67407fab"
            },
            "created_at": "2023-06-26T19:25:52Z",
            "messages": [
               {
                  "created_at": "2023-06-26T19:25:52Z",
                  "message": "test message",
                  "kind": "for_operator"
               },
               {
                  "created_at": "2023-06-26T19:25:52Z",
                  "message": "test message 2",
                  "kind": "for_operator"
               },
               {
                  "created_at": "2023-06-26T19:25:52Z",
                  "message": "Test Department Test Department Test Department",
                  "kind": "info"
               },
               {
                  "created_at": "2023-06-26T19:25:52Z",
                  "message": "test message 3",
                  "kind": "for_operator"
               },
               {
                  "created_at": "2023-06-26T19:25:52Z",
                  "message": "some info message...",
                  "kind": "info"
               },
               {
                  "created_at": "2023-06-26T19:25:54Z",
                  "message": "Hi! I have a test question...",
                  "kind": "visitor"
               }
            ],
            "department_key": "test",
            "operator": {
               "id": 207529,
               "email": "admin@hehehe.he",
               "name": "admin"
            },
            "id": 1458,
            "visit_session": {
               "ip": "31.193.122.170",
               "landing_page": {
                  "url": "https://mycompany.com"
               }
            }
         }"
      ],
      "crc":[
         "b82177f521f8b35a88d4841b4ba7df8e"
      ]
   },
   "Body":"",
   "Files":null,
   "MultipartValues":null
}

Example of transmitted data in chat field:

{
   "category":"Requests",
   "start_page":{
      "url":"https://mycompany.com"
   },
   "subcategory":null,
   "locale":"en",
   "visitor":{
      "fields":{
         "phone":"+1 (23) 456-78-90",
         "name":"Visitor",
         "email":"test@rox.chat"
      },
      "id":"13bf13179c144c1eafdaefb0fa19a1a4"
   },
   "created_at":"2023-07-05T16:28:20 Z",
   "messages":[
      {
         "created_at":"2023-07-05T16:28:20 Z",
         "message":"Good morning!",
         "kind":"visitor"
      }
   ],
   "department_key":"helpdesk",
   "operator":{
      "id":175954,
      "email":"admin@admin.com",
      "name":"Administrator"
   },
   "id":23,
   "visit_session":{
      "ip":"127.0.0.1",
      "landing_page":{
         "url":"https://mycompany.com"
      }
   }
}