Webchat Events

The webchat script loaded onto your website will emit events when certain things happen with chat.

You can use javascript on your website to subscribe to these events, allowing you to perform custom tasks such as:

• reporting an analytics event when a chat is started
• showing a banner promoting webchat when the chat is set to be visible on that page.

We expose an object named saEvents on the global window object in Javascript. saEvents has a subscribe function we can use to subscribe to webchat events.

Subscribing to events

The following basic Javascript code will allow you to subscribe to any events emitted from the chat.

if (window.saEvents) {
  window.saEvents.subscribe(event => {
    console.log(`Chat event: ${event.type}`, event.data);
    // do something useful here

  });
}

Note!

More events will be added in future and additional data may be sent in the ‘data’ attribute with events in future, so ensure your code will handle this gracefully.

Historic events

When you call the subscribe function, a history of all webchat events since page load will be delivered to the function you supply. This makes it possible to reliably detect events such as CHAT_LOADED with accurate timestamps. If historic events are not required, their timestamp can be compared to the current time.

Events schema

All events follow the schema:

{
  type: <string>,
    data: <object>,
      timestamp: <number>
}

Note!

Timestamps are displayed in Milliseconds since Unix Epoch format. The current time can be calculated in this format in Javascript using new Date().getTime().

For example:

{
  "type": "CHAT_VISIBLE",
    "data": {
    "chatInstanceName": "help_faq_bot"
  },
  "timestamp": 1637147056035
}

Supported events

Type	Description	Data	Example
CHAT_LOADED	Chat loader script has successfully loaded onto the page.	chatInstanceName: ID of the active SmartAgent chat instance	{ "type": "CHAT_LOADED", "timestamp": 1637147056035, "data": { "chatInstanceName": "help_faq_bot" }}
CHAT_VISIBLE	The chat is configured (based on time and url) to display on this page and we’ve displayed the ‘start chat’ button to the customer.	chatInstanceName: ID of the active SmartAgent chat instance	{ "type": "CHAT_VISIBLE", "timestamp": 1637147056035, "data": { "chatInstanceName": "help_faq_bot" }}
CONTACT_STARTED	Customer has started a new chat.	contactId: Amazon Connect Contact ID	{ "type": "CONTACT_STARTED", "timestamp": 1637147056035, "data": { "contactId": 9960459a-233f-4963-95f9-dde57ac4d9c5" }}
CONTACT_ENDED	Customer has ended a chat, regardless of whether they were connected to an agent.	contactId: Amazon Connect Contact ID	{ "type": "CONTACT_ENDED", "timestamp": 1637147056035, "data": { "contactId": "9960459a-233f-4963-95f9-dde57ac4d9c5" }}
TRANSFER_TO_QUEUE	Customer has been transferred to a queue in Amazon Connect.	contactId: Amazon Connect Contact ID	{ "type": "CHAT_VISIBLE", "timestamp": 1637147056035, "data": { "contactId": "9960459a-233f-4963-95f9-dde57ac4d9c5" }}
CONNECT_TO_AGENT	Customer has successfully been connected to an agent.	contactId: Amazon Connect Contact ID	{ "type": "CHAT_VISIBLE", "timestamp": 1637147056035, "data": { "contactId": "9960459a-233f-4963-95f9-dde57ac4d9c5" } }