Quickstart Guide

Learn how to get up and running with Modern Chat

Get your launch team together! Modern Chat creates a whole new dynamic for how customers contact your business.

  • As you prepare to launch Modern Chat on your brand’s site, gather people together for these roles:
    • Project Manager: Coordinates the development and deployment efforts
    • Web Developer: Adds script code(s) to the website for authenticated and unauthenticated use cases. These scripts can be added through:
      • Google Tag Manager or another tag management tool
      • Direct insertion into the head of the webpage.
      • Assists in identifying CSS selectors and creating custom conditions.
    • Care Administrator: Sets up business logic for chat rules, priority, team configurations, tags, etc.
    • Trainer: Teaches Supervisors and/or Agents to use Modern Chat effectively.
  • If you want to take advantage of authenticated chat, you will need to contact Khoros Support to retrieve your Brand Messenger App Key ID and App Key Secret. This is used to generate the JWT used to authenticate.
  • Determine whether your chat sessions require end-user authentication. If so, you will need a developer to review the End-user authentication section and implement the instructions before you launch.
  • Review the Brand Messenger configuration options in Admin > Brand Messenger. See our guides in Khoros Atlas to learn about the General Settings and Themes options.
  • Build your theme(s).
  • Review the Content Filtering configuration options.
  • Create your Web Chat widget:
    • In Admin > Brand Messenger > Modern Chat, click New Widget.
    • Enter a name and description, select a Theme, and set your Display Conditions.
    • Create Custom Conditions as needed. Save the widget.
    • Select your Widget in the Modern Chat Widgets list.
    • Review the Rules and activate or deactivate as needed.
    • Publish the Widget.
    • Click the Script button and copy the output. You'll need to make some changes if you require authentication.
    • Place the script onto the web page. See How to get Brand Messenger onto a web page.
  • Test.
  • Tie Modern Chat widget rules to Source Tags to define routing rules for Agents in Response.

Event Listeners

Throughout this document, you will see examples that depend on event listeners to fire. Here is a quick breakdown of the events that Khoros uses with Modern Chat.


Dispatched after the widget rules have been fetched from Khoros' CDN. It's useful for debugging rule definitions or if you want to do custom logic on Khoros rule definitions.

window.addEventListener('khorosChatRulesLoaded', function (event) {
    const detail = event.detail;
    const { sdk, rulesDefinition } = detail;


window.addEventListener('khorosConfig', function (event) {
    const detail = event.detail;
    const { sdk, config } = detail;

Dispatched once the full configuration is assembled, just before the call to init is made on Modern Chat. It's useful in debugging the final configuration being sent to Khoros.


Dispatched immediately after Modern Chat init is called. This occurs right when the chat bubble appears on the front end.

window.addEventListener('khorosInit', function (event) {
    const detail = event.detail;
    const { sdk } = detail;


Dispatched when the first chat message is displayed.

window.addEventListener('khorosFirstMessageChatInitiated', function (event) {
    const detail = event.detail;
    const { sdk } = detail;


Dispatched once the widget has been opened and showing a full chat widget to the user.

window.addEventListener('khorosWidgetOpened', function (event) {
    const detail = event.detail;
    const { sdk } = detail;


Dispatched once the widget has been closed.

window.addEventListener('khorosWidgetClosed', function (event) {
    const detail = event.detail;
    const { sdk } = detail;


Dispatched once the widget has successfully connected to the backend. This usually occurs after khorosWidgetOpened, and before khorosMessageSent.

window.addEventListener('khorosWidgetConnected', function (event) {
    const detail = event.detail;
    const { sdk } = detail;


Dispatched once the message is sent from the client.

window.addEventListener('khorosMessageSent', function (event) {
    const detail = event.detail;
    const { sdk } = detail;


Dispatched once the message is received by the client.

window.addEventListener('khorosMessageReceived', function (event) {
    const detail = event.detail;
    const { sdk } = detail;

Did this page help you?