Skip to main contentWatson Assistant web chat

Events

Your website can react to web chat behavior by listening to events.

Overview

The web chat uses an event system to communicate with your website. By using these events, you can build your own custom UI responses, send messages to your assistant from your website code, or even have your website react to changes of state within the web chat.

To subscribe to events, use the on() and once() instance methods. Event handlers are called in the order in which they were registered.

Example

<script>
  window.watsonAssistantChatOptions = {
    integrationID: "YOUR_INTEGRATION_ID",
    region: "YOUR_REGION",
    serviceInstanceID: "YOUR_SERVICE_INSTANCE_ID",
    onLoad: function(instance) {
      // Your handler
      function handler(obj) {
        console.log(obj.type, obj.data);
      }
      console.log('instance', instance);
  
      // console.log out details of any "receive" event
      instance.on({ type: "receive", handler: handler });
      // console.log out details of any "send" event
      instance.on({ type: "send", handler: handler });
  
      // 30 seconds later, unsubscribe from listening to "send" events
      setTimeout(function(){
        instance.off({ type: "send", handler: handler});
      }, 30000);
  
      // Actually render the web chat.
      instance.render();
    }
  };
  setTimeout(function(){const t=document.createElement('script');t.src='https://web-chat.global.assistant.watson.appdomain.cloud/loadWatsonAssistantChat.js';document.head.appendChild(t);});
</script>

Events summary

The following table summarizes the events that are fired by web chat. For more information about an event, see Event details.

EventFired When
*Fired with every event.
pre:sendFired before the web chat sends a message to your assistant, before the send event.
sendFired when the web chat sends a message to your assistant, after the pre:send event.
pre:receiveFired before the web chat receives a response from your assistant, before the receive event.
receiveFired when the web chat receives a response from your assistant, after the pre:receive event.
identityTokenExpiredFired when security is enabled and your JWT token has expired.
errorFired when the web chat encounters an error.
customResponseFired if a response with an unrecognized or user_defined response type is received.
window:openFired when the chat window is opened.
window:pre:closeFired when the chat window is closed, before the window:close event. Returning a Promise here will prevent the web chat window from closing until the promise is resolved.
window:closeFired when the chat window is closed, after the window:pre:close event.

Event callbacks

When an event fires, subscribed callbacks are called in the order in which they were subscribed using the on or once method. Each callback parameter is an object:


{
  type: 'string',
  data: {} //object specific to event type
}

To prevent accidental reassignment of data that might be in use by other methods, the parameters for most callbacks are deep clones of the event data rather than references to the original objects. The exceptions are the pre:send and pre:receive events. These events do provide references to the original objects, making it possible for your code to manipulate the data before it is passed on to the send or receive events. For example, you might use the pre:send event to modify context variables before sending a message to your assistant.

Asyncronyous event callbacks

An event callback does not require a return value. However, you can optionally return a Promise object. If you return a Promise, processing of the event queue pauses until the Promise is resolved. This can be useful for asynchronous methods that need to be called while preprocessing data from your pre:send or pre:receive event handlers.

Example


/**
 * Waits 5 seconds before showing message.
 */
function handler(event) {
  return new Promise(function(resolve, reject) {
    setTimeout(function() {
      console.log('I waited 5 seconds before continuing!');
      resolve();
    }, 5000);
  });
}
instance.on({ type: "pre:receive", handler: handler });

Event details

pre:send

Fired when sending a message to the assistant, before the send event. The pre:send event gives you the opportunity to synchronously manipulate the object referenced by event.data before the web chat passes it to the send event (for example, to update context data).

ParamTypeDescription
eventObjectThe event
event.typeStringEvent type (pre:send)
event.dataObjectA v2 message API request object. (For more information, see the API Reference.) Note that this parameter is a reference to the object that will be sent, so you can modify it in place.
Example

/**
 * Console out the context object.
 */
function handler(event) {
  console.log(event.data.context); // You can also manipulate context here.
  console.log(event.data.input); // You can also manipulate input here. Maybe filter private data?
}
instance.on({ type: "pre:send", handler: handler });

send

Fired when sending a message to the assistant, after the pre:send event. This event indicates that the message has been sent to the assistant.

ParameterTypeDescription
eventObjectThe event
event.typeStringEvent type (send)
event.dataObjectA v2 message API request object. (For more information, see the API Reference.) This parameter is a copy of the message that was sent.
Example

function handler(obj) {
  console.log(obj.type, obj.data);
}
instance.on({ type: "send", handler: handler });

pre:receive

Fired when receiving a response from the assistant, before the receive event. The pre:receive event gives you the opportunity to synchronously manipulate the object referenced by event.data before the web chat passes it to the receive event for processing.

ParameterTypeDescription
eventObjectThe event
event.typeStringEvent type (pre:receive)
event.dataObjectA v2 message API response object. (For more information, see the API Reference.) Note that this parameter is a reference to the object that will be received, so you can modify it in place.
Example

/**
 * Override our response_type for options with one of your own.
 */
function handler(event) {
  const generic = event.data.output.generic;
  for (let i = 0; i < generic.length; i++) {
    const item = generic[i];
    if (item.response_type === "options") {
      item.response_type = "my_custom_options_override";
    }
    if (item.response_type === "connect_to_agent") {
      item.response_type = "text";
      item.text = "All our agents are busy, please call us at 555-555-5555."
    }
  }
}
instance.on({ type: "pre:receive", handler: handler });

receive

Fired when the web chat receives a response from your assistant, after the pre:receive event. This event indicates that the response has been received; if the response type is recognized, the response is then rendered in your chat window.

ParameterTypeDescription
eventObjectThe event
event.typeStringEvent type (receive)
event.dataObjectA v2 message API response object. (For more information, see the API Reference.) This parameter is a copy of the response that was received.
Example

  /**
   * Console.log out intents on every message you receive from your Assistant.
   */
  function handler(event) {
    console.log('intents:', event.data.output.intents);
  }
  instance.on({ type: "receive", handler: handler });
  
  

identityTokenExpired

Fired when security is enabled and the JWT token needs to be refreshed.

ParameterTypeDescription
eventObjectThe event
event.typeStringEvent type (identityTokenExpired)
event.identityTokenstringSets a token in the same format as instance.updateIdentityToken(identityToken) and then retries the message.
Example

/**
 * Update the identityToken.
 */
function handler(event) {
  // Make your async call to fetch a new token here.
  return makeCallToFetchApiToken().then(function (token) {
    event.identifyToken = token;
  }
}
instance.on({ type: "identityTokenExpired", handler: handler });
  

error

Fired when the web chat encounters an error (including network, response format, or uncaught code errors).

ParameterTypeDescription
eventObjectThe event
event.typeStringEvent type (error)
event.dataObjectError data

customResponse

Fired when the web chat receives a response with an unrecognized response type from your assistant. The event includes the response data and the DOM element where any response should be rendered. Based on the response type, you can choose to render a custom view, perform an action on your website, or both.

There are two use cases for this event.

1) A user_defined response type. This is a response type that enables you to define your own content and provide your own code to render it. You can also mark a user_defined response type as silent and not render anything, but instead take some other action on your web page (for example, opening a tutorial or interacting with other widgets on the page). For more information, see the examples of user_defined response types.

2) A known response type that web chat does not handle. Currently, web chat does not support the connect_to_agent response type outside the private beta program.

ParamTypeDescription
eventObjectThe event
event.typeStringEvent type (customResponse)
event.dataObjectEvent data
event.data.messageObjectA v2 message API Response object. (For more information, see the API Reference.) This parameter is a copy of the response that was received.
event.data.elementElementA DOM element inside the chat window where the response should be rendered. This will be null if a user_defined message has the silent attribute set to true.
Example

function handler(event) {
  const type = event.type;
  const message = JSON.stringify(event.data.message);
  const element = event.data.element;
  if (type === "my_silly_response_type") {
    element.innerHTML = message;
  }
}
instance.on({ type: "customResponse", handler: handler });

window:open

Fired when the web chat window opens.

ParameterTypeDescription
eventObjectThe event
event.typeStringEvent type (window:open)

window:pre:close

Fired when the web chat window closes, before the window:close event. Returning a Promise here will prevent the web chat window from closing until the promise is resolved.

ParamTypeDescription
eventObjectThe event
event.typeStringEvent type (window:pre:close)
Example

  /**
   * Stop the window from closing by setting vetoClose in the event handler.
   */
function handler(event) {
  return new Promise(function(resolve, reject) {
    event.vetoClose = not_ready_to_close;
    resolve();
  });
}
instance.on({ type: "window:pre:close", handler: handler });
  

window:close

Fired when the web chat window closes, after the window:pre:close event.

ParamTypeDescription
eventObjectThe event
event.typeStringEvent type (window:close)

Wildcard (*)

Wildcard event. When any event is fired, callbacks that are subscribed to the wildcard event are called after any subscriptions to the specific event type.

ParameterTypeDescription
eventObjectThe event
event.typeStringEvent type
event.dataObjectEvent data (content depends on event type)
Example

function handler(event) {
  console.log(event.type, event.data);
}
instance.on({ type: "*", handler: handler });