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/versions/" + (window.watsonAssistantChatOptions.clientVersion || 'latest') + "/WatsonAssistantChatEntry.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
customPanel:pre:closeFired when the custom panel closing animation has started.
customPanel:pre:openFired when the custom panel opening animation has started.
customPanel:closeFired when the custom panel closing animation has ended.
customPanel:openFired when the custom panel opening animation has ended.
customResponseFired if a response with an unrecognized or user_defined response type is received.
history:beginFired at the beginning of the web chat reloading when session history is enabled and the session hasn't expired.
history:endFired at the end of the web chat reloading when session history is enabled and the session hasn't expired.
identityTokenExpiredFired when security is enabled and your JWT token has expired.
pre:receiveFired before the web chat receives a response from your assistant, before the receive event.
pre:restartConversationFired when a request is made to restart the conversation and before any action is taken.
pre:sendFired before the web chat sends a message to your assistant, before the send event.
receiveFired when the web chat receives a response from your assistant, after the pre:receive event.
restartConversationFired after the conversation is restart and before a new conversation has begun.
sendFired when the web chat sends a message to your assistant, after the pre:send event.
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:pre:openFired when the chat window is opened. This event is fired before the web chat attempts to load any existing history data or before it requests the welcome message.
window:closeFired when the chat window is closed, after the window:pre:close event.
window:openFired when the chat window is opened. This is fired after web chat begins the process of loading existing history data and either requesting the welcome message or opening the home screen.
*Fired with every event.

Agent events summary

The following table summarizes the events that are fired by web chat as part of interacting with a human agent through our service desk integration.

EventFired When
agent:areAnyAgentsOnlineThis event is fired after web chat calls "areAnyAgentsOnline" for a service desk. This occurs right after web chat receives a "connect_to_agent" response from the assistant. It will report the value returned from that call. This is particularly useful if you want custom code to take action if no agents are online.
agent:endChatThis event is fired after a chat with an agent has ended. This is fired after "agent:pre:endChat" but can be fired both from the user leaving the chat or the agent ending the chat.
agent:pre:receiveThis event is fired before a message is received either from a human agent or from the system.
agent:pre:sendThis event is fired before a message is sent to a human agent.
agent:pre:startChatThis event is fired before a chat with a service desk has started. This occurs as soon as the user clicks the "Request agent" button and before any attempt is made to communicate with the service desk.
agent:pre:endChatThis event is fired before a chat with an agent is ended. This occurs after the user has confirmed they want to end the chat but it can also be fired if the chat is ended by the agent.
agent:receiveThis event is fired after a message is received either from a human agent or from the system.
agent:sendThis event is fired after a message is sent to a human agent.

Message object extensions

Many of the events fired by web chat provide access to the message objects that are either sent to or received from Watson Assistant. The format of these messages is documented in the Watson Assistant v2 message API documentation (either the Request or Response objects). In addition to the standard WA message format, web chat extends the message object with some additional data that is specific to web chat. The values all exist on a history property on either the request or response object.

The available properties are documented below. Any properties not documented here are for internal use and not officially supported by custom code and may be changed at any time.

PropertyTypeDescription
is_welcome_requestbooleanIndicates if this message is a request for the welcome node or greeting. This occurs when web chat is first opened and there is not an existing session. The input text of the message will be an empty string.
labelstringThis property is included on some message requests and represents the user displayed text for the message which might be different than the actual message text that the assistant acts on. For message requests that were generated as the result of the user choosing a value from an option or suggestion response (buttons and dropdowns). The value in the input.text property of the request is the text sent to the assistant for it to act on but this is not necessarily the same as the user display text that corresponds to that value. This value is also what appears as the "user said" text that appears in the message list.
silentbooleanThis property can be included on either a message request or response and it indicates that this message should not be displayed to the user.
timestampNumberThe time a message was sent or received. Note that this value on a request will change from the original value it had at the time it was sent when the message is loaded from session history. The message will originally use the clock on the end user's machine (which could be set incorrectly). When the message is loaded from session history, the value will be updated to use the time from the server when it received the request.
user_definedObjectThis object is present on messages loaded from session history that were updated with updateHistoryUserDefined. This allows you to associate custom data with a previously sent or received message. For example, you could use this to keep track of the data the user entered in a field of a custom response so that if the user switches pages and web chat is reloaded, that data is still available to your custom response.
Example

function preSendHandler(event) {
  // Set a skill variable to the user's name if this message is a welcome request.
  if (event.data.history.is_welcome_request) {
    event.data.context.skills['actions skill'].skill_variables.User_Name = fullName;
  }
}

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
}

In addition to the event data passed to each handler, a second argument is passed to every handler that is the current instance of web chat. This is a convenience so your handler has access to the instance without you having to store the value somewhere that is accessible to your handler. This may be useful if you want to do something like send a message or open a custom panel as part of the logic of your handler.

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

ParameterTypeDescription
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.
instanceObjectThe current instance of web chat
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.
instanceObjectThe current instance of web chat
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.
event.updateHistoryBooleanDefaults to True. If session history is enabled this flag allows you to automatically save updates made to messages in pre:receive. If the page is reloaded/changed after updates to a message have been saved then the message will re-render the same way it was initially rendered (after the pre:receive edits). Note: the updated message will only be saved for the length of a session. For more info and examples take a look at this tutorial.
instanceObjectThe current instance of web chat
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";
      // Save changes made to this message so it will be re-rendered the same way if session history is enabled.
      event.updateHistory = true;
    }
    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."
      // Don't save the changes made to this message, it will re-render the way web chat initially received it from the
      // Assistant (even if session history is enabled).
      event.updateHistory = false;
    }
  }
}
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.
instanceObjectThe current instance of web chat
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 });

history:begin

Fired at the beginning of the web chat reloading when session history is enabled. This event indicates that the session hasn't expired and the messages from the session history are going to be re-rendered in the chat window. Messages are allowed to be edited during this event (similar to pre:receive). The only events that will fire between here and history:end will be customResponse events (if a customResponse occurs in history). For more info and examples take a look at this tutorial.

ParameterTypeDescription
eventObjectThe event
event.typeStringEvent type (history:begin)
event.messagesArrayAn array of the message requests and responses that have occurred during the session. Any updates saved for a message response with instance.updateHistoryUserDefined() will be available within messages[n].history.user_defined.
instanceObjectThe current instance of web chat
Example

function receiveHandler(event) {
  const { generic } = event.data.output;
  for (let i = 0; i < generic.length; i++) {
    const item = generic[i];
    if (item.response_type === 'text') {
      if (item.text === "TypeScript isn't awesome :(" && !event.data.history.user_defined) {
        // Since there's no history.user_defined info for this message it must be the first time we've seen it. (or at
        // least the first time we're saving state for it).
        // Lets save some state about the message response to be used on reload.
        instance.updateHistoryUserDefined(
          event.data.id,
          { state1: "just kidding, TypeScript is awesome" }
        );
      }
    }
  }
}
instance.on({ type: "receive", handler: receiveHandler });

function historyHandler(event){
  for (let i = 0; i < event.messages.length; i++){
    if(event.messages[i].history.user_defined?.state1 === "just kidding, TypeScript is awesome"){
      // On reload we found the state we saved for the message.
      // Lets use the updated state instead of the original.
      event.messages[i].output.generic[0].text = event.messages[i].history.user_defined.state1;
    }
  }
}
instance.on({ type: "history:begin", handler: historyHandler });

history:end

Fired at the end of the web chat reloading when session history is enabled. This event indicates that the session hasn't expired and the messages from the session history have been re-rendered in the chat window. Messages aren't allowed to be edited during this event.

ParameterTypeDescription
eventObjectThe event
event.typeStringEvent type (history:end)
event.messagesArrayAn array of the message requests and responses that have occurred during the session. Any changes made to messages in history:begin will be visible here.
instanceObjectThe current instance of web chat
Example

function handler(event){
  for (let i = 0; i < event.messages.length; i++){
    // Console log the final versions of the messages after web chat reload.
    console.log(event.message[i]);
  }
}
instance.on({ type: "history:end", handler: handler });

identityTokenExpired

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

ParameterTypeAssignableDescription
eventObjectThe event
event.typeStringEvent type (identityTokenExpired)
event.identityTokenstringYesSets a token in the same format as instance.updateIdentityToken(identityToken) and then retries the message.
instanceObjectThe current instance of web chat
Example

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

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 response type that web chat does not recognize.

Note: if session history is enabled then this event will also fire in between the history:begin and history:end events. This is done so that customResponse handlers can be re-envoked when web chat reloads which is necessary since there will be new event.data.elements to attach a customResponse to. If data needs to be saved for a customResponse so that it can be re-render with the same state in mind that it was initially rendered with then use the instance.updateHistoryUserDefined() method. For more info and examples take a look at this tutorial.

ParameterTypeDescription
eventObjectThe event
event.typeStringEvent type (customResponse)
event.dataObjectEvent data
event.data.messageObjectThe part of a v2 message API Response object that includes the response_type and user_defined fields. This parameter only includes the output.generic[n] part of the response that was received.
event.data.fullMessageObjectThe full v2 message API Response object. (For more information, see the API Reference.) This parameter is a copy of the response that was received and includes the message id needed to save customResponse state for session history.
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.
instanceObjectThe current instance of web chat
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 });

Example with session history

function handler(event, instance) {
  const { element } = event.data;

  // If there's no user_defined history then this must be the first time we've seen this custom response.
  if (!event.data.fullMessage.history.user_defined) {
    element.innerText = 'on reload this will say "yay it worked"';
    instance.updateHistoryUserDefined(
      event.data.fullMessage.id,
      { firstSave: 'yay it worked' }
    );
  }

  // If there is history and user_defined data then we must be seeing this customResponse after reload.
  else if (event.data.fullMessage.history?.user_defined) {
    if (event.data.fullMessage.history.user_defined.firstSave) {
      element.innerText = event.data.fullMessage.history.user_defined.firstSave;
    }
  }
}
instance.on({ type: "customResponse", handler: handler });

window:pre:open

Fired when the chat window is opened. This event is fired before the web chat attempts to load any existing history data or before it requests the welcome message. This can be used to send a different message first if you want to customize the welcome message that is displayed.

ParameterTypeAssignableDescription
eventObjectThe event
event.typeStringEvent type (window:pre:open)
event.reasonstringThe reason the window was opened. See Window open reasons for an explanation of the possible values here.
event.cancelOpenbooleanYesIf true, indicates that the open should be cancelled and the window should not be opened.
instanceObjectThe current instance of web chat

window:open

Fired when the chat window is opened. This event is fired before the web chat attempts to load any existing history data or before it requests the welcome message. This can be used to send a different message first if you want to customize the welcome message that is displayed. You can also use this event to open a custom panel that can display a pre-chat form for gathering data from the customer before starting the conversation.

ParameterTypeAssignableDescription
eventObjectThe event
event.typeStringEvent type (window:open)
event.reasonstringThe reason the window was opened. See Window open reasons for an explanation of the possible values here.
event.cancelOpenbooleanYesIf true, indicates that the open should be cancelled. Since the window is already open when this event is fired, this property will cause the window to close. Note that the window close events are not fired when this occurs.
instanceObjectThe current instance of web chat
Window open reasons

This is a list of the possible reasons that the web chat window may be opened and the value of the reason property on the window:open and window:pre:open events.

ReasonDescription
called_open_windowIndicates the widget was opened by a call to the instance function openWindow or toggleOpen.
default_launcherIndicates the user clicked on our built-in launcher button that opened the web chat.
linkIndicates the widget was opened because a link ID was found that started a specific conversation. See Creating links to web chat for more information.
open_by_defaultIndicates the widget was opened because the openChatByDefault property was set to true
session_historyIndicates the widget was opened as a result of session history.

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.

ParameterTypeAssignableDescription
eventObjectThe event
event.typeStringEvent type (window:pre:close)
event.cancelClosebooleanYesIf true, indicates that the close should be cancelled.
event.vetoClosebooleanYes
Deprecated
Use cancelClose instead.
instanceObjectThe current instance of web chat
Example

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

window:close

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

ParameterTypeDescription
eventObjectThe event
event.typeStringEvent type (window:close)
instanceObjectThe current instance of web chat

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)
instanceObjectThe current instance of web chat
Example

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

customPanel:pre:open

Fired when the custom panel opening animation has started after calling panelInstance.open().

ParameterTypeDescription
eventObjectThe event
event.typeStringEvent type (customPanel:pre:open)
instanceObjectThe current instance of web chat

customPanel:open

Fired when the custom panel opening animation has ended.

ParameterTypeDescription
eventObjectThe event
event.typeStringEvent type (customPanel:open)
instanceObjectThe current instance of web chat

agent:pre:startChat

This event is fired before a chat with a service desk has started. This occurs as soon as the user clicks the "Request agent" button and before any attempt is made to communicate with the service desk. This can be useful for gathering information before connecting to the service desk. A custom panel can be displayed to the user to collect this information. The service desk is not connected to until after all this event's handlers have resolved.

This event can also be used to cancel the chat.

ParameterTypeAssignableDescription
eventObjectThe event
event.typeStringEvent type (agent:pre:startChat)
event.messageObjectThe full v2 message API Response object that will be passed to the service desk. (For more information, see the API Reference)
event.cancelStartChatbooleanYesThis flag can be set by a listener to indicate that the chat process should be cancelled.
event.preStartChatPayloadanyYesSome arbitrary payload of data that will be passed to the service desk when a chat is started. The value assigned here will be passed to the service desk when its startChat function is called.
instanceObjectThe current instance of web chat
Example

let preStartChatResolve;
let preStartChatEvent;

function preStartChatHandler(event, instance) {
  // This Promise will cause the "agent:pre:startChat" event to pause until the custom panel is closed.
  // There is a click listener in the custom panel that will resolve it.
  return new Promise((resolve) => {
    preStartChatResolve = resolve;
    preStartChatEvent = event;

    instance.customPanels.getPanel().open({ "title": "Connect to agent", hideCloseButton: true });
  });
}

function createCustomPanel(panel) {
  const container = document.createElement('div');
  container.innerText = 'To get an agent, click this button:';

  const button = document.createElement('button');
  button.type = 'button';
  button.innerText = 'Agent!';
  
  button.addEventListener('click', () => {
    // Once the user has clicked the button, close the panel, set a payload that can be made available to the service
    // desk and the resolve the promise that our handler is waiting on to continue the connect to agent.
    preStartChatEvent.preStartChatPayload = 'You clicked the button.';
    panel.close();
    preStartChatResolve();
  });

  container.appendChild(button);

  panel.hostElement.appendChild(container);
}

window.watsonAssistantChatOptions = {
  integrationID: "YOUR_INTEGRATION_ID",
  region: "YOUR_REGION",
  serviceInstanceID: "YOUR_SERVICE_INSTANCE_ID",
  
  onLoad: function(instance) {
    instance.render();
    
    // Set up the custom panel and register a listener that will open it and wait for the button to be clicked.
    instance.on({ type: "agent:pre:startChat", handler: preStartChatHandler });
    createCustomPanel(instance.customPanels.getPanel());
  }
};

setTimeout(function(){
  const t=document.createElement('script');
  t.src='https://web-chat.global.assistant.watson.appdomain.cloud/versions/' + (window.watsonAssistantChatOptions.clientVersion || 'latest') + '/WatsonAssistantChatEntry.js';
  document.head.appendChild(t);
});

agent:pre:endChat

This event is fired before a chat with an agent is ended. This occurs after the user has selected "Yes" from the confirmation modal but it can also be fired if the chat is ended by the agent. This can be useful for gathering post-chat information or conducting a survey with the user before disconnecting from the service desk. A custom panel can be displayed to the user to collect this information. The service desk is not disconnected from until after all this event's handlers have resolved.

This event can also be used to cancel ending the chat.

Note that this event is only fired if a chat was successfully started and an agent joined. If an error occurs while starting the chat or the request for an agent is cancelled before an agent joins, this event is not fired (since ending the chat cannot be cancelled in these cases which this event allows for). However, the agent:endChat event is fired in these cases.

ParameterTypeAssignableDescription
eventObjectThe event
event.typeStringEvent type (agent:pre:endChat)
event.endedByAgentbooleanIndicates if the chat was ended by the agent instead of the user.
event.cancelEndChatbooleanYesThis flag can be set by a listener to indicate that the end chat process should be cancelled.
event.preEndChatPayloadanyYesSome arbitrary payload of data that will be passed to the service desk when a chat is ended. The value assigned here will be passed to the service desk when its endChat function is called.
instanceObjectThe current instance of web chat
Example
See the example for agent:pre:startChat for how to use the agent events to open a custom panel.

agent:pre:receive

This event is fired before a message is received either from a human agent or from the system.

ParameterTypeDescription
eventObjectThe event
event.typeStringEvent type (agent:pre:receive)
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 was received, so you can modify it in place.
event.agentProfileObjectIf this message was sent by an agent, this may contain information about the agent. Messages sent by the system will not provide a value for this.
event.agentProfile.idstringA unique identifier for the agent. The value assigned here depends on the service desk being used.
event.agentProfile.nicknamestringThe visible name for the agent. This can be the agent's full name or just a first name.
event.agentProfile.profile_picture_urlstringAn optional URL pointing to a profile picture for the agent.
instanceObjectThe current instance of web chat

agent:receive

This event is fired after a message is received either from a human agent or from the system.

ParameterTypeDescription
eventObjectThe event
event.typeStringEvent type (agent:receive)
event.dataObjectA v2 message API request object. (For more information, see the API Reference)
event.agentProfileObjectIf this message was sent by an agent, this may contain information about the agent. Messages sent by the system will not provide a value for this.
event.agentProfile.idstringA unique identifier for the agent. The value assigned here depends on the service desk being used.
event.agentProfile.nicknamestringThe visible name for the agent. This can be the agent's full name or just a first name.
event.agentProfile.profile_picture_urlstringAn optional URL pointing to a profile picture for the agent.
instanceObjectThe current instance of web chat

agent:pre:send

This event is fired before a message is sent to a human agent.

ParameterTypeDescription
eventObjectThe event
event.typeStringEvent type (agent: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.
instanceObjectThe current instance of web chat

agent:send

This event is fired after a message is sent to a human agent.

ParameterTypeDescription
eventObjectThe event
event.typeStringEvent type (agent:send)
event.dataObjectA v2 message API request object. (For more information, see the API Reference)
instanceObjectThe current instance of web chat

agent:areAnyAgentsOnline

This event is fired after web chat calls "areAnyAgentsOnline" for a service desk. This occurs right after web chat receives a "connect_to_agent" response from the assistant. It will report the value returned from that call. This is particularly useful if you want custom code to take action if no agents are online.

ParameterTypeDescription
eventObjectThe event
event.typeStringEvent type (agent:areAnyAgentsOnline)
event.areAnyAgentsOnlinestringThis is the result of the "areAnyAgentsOnline" call. A value of "online" indicates that agents are online. A value of "offline" indicates that agents are not online. A value of "unknown" indicates that the service desk did not report a result. This may occur if the service desk does not support this operation. If the service desk generated an error, then "offline" will be returned.
instanceObjectThe current instance of web chat

agent:endChat

This event is fired after a chat with an agent has ended. This is fired after agent:pre:endChat (except in cases where a request for an agent was cancelled) but can be fired both from the user ending the chat or the agent ending the chat. This can be useful for gathering post-chat information or conducting a survey with the user. A custom panel can be displayed to the user to collect this information.

ParameterTypeDescription
eventObjectThe event
event.typeStringEvent type (agent:endChat)
event.endedByAgentbooleanIndicates if the chat was ended by the agent instead of the user.
event.requestCancelledbooleanIndicates if the request for an agent was cancelled before one joined. This occurs when the user cancels the request or when an error occurs while attempting to start a new chat.
instanceObjectThe current instance of web chat
Example
See the example for agent:pre:startChat for how to use the agent events to open a custom panel.

customPanel:pre:close

Fired when the custom panel closing animation has started after calling panelInstance.close() or the user clicks the close button in the panel header.

ParameterTypeDescription
eventObjectThe event
event.typeStringEvent type (customPanel:pre:close)
instanceObjectThe current instance of web chat

customPanel:close

Fired when the custom panel closing animations has ended.

ParameterTypeDescription
eventObjectThe event
event.typeStringEvent type (customPanel:close)
instanceObjectThe current instance of web chat

pre:restartConversation

Fired when a request is made to restart the conversation. At this point web chat has not executed any operations to restart the conversation. If you want the restart to cause web chat to close this event would be a good place to call closeWindow(). If you do use closeWindow(), make sure to use `await` or `then` to ensure the event will wait for the close to complete before doing the restart.

ParameterTypeDescription
eventObjectThe event
event.typeStringEvent type (pre:restartConversation)
instanceObjectThe current instance of web chat

restartConversation

Fired after the conversation is restart and before a new conversation has begun. At this point the previous conversation has been cleared and the web chat state has been restart to a default state. However a new conversation has not yet begun. If you wish the restart to trigger a custom welcome message, this event would be a good place to call send()with your custom message.

ParameterTypeDescription
eventObjectThe event
event.typeStringEvent type (restartConversation)
instanceObjectThe current instance of web chat