Overview

How to access the Message Bus

  /**
       * Callback function called after the chat has been initialized.
       *
       * @param bus The message bus used to publish and subscribe to topics
       */
       onInit: function(bus) {
          // Message bus created and ready to be used,
                                window.bus = bus;
                     }            
       };

How to publish to a topic

  // Publish to other-topic, sending some data
  bus.publish("other-topic", {
      message: "Hello world!"
  });

How to subscribe to a topic

  // Subscribe to some-topic, and log the event data
  var subscription = bus.subscribe("some-topic", function(data) {
      console.log(data);
  });

How to unsubscribe from a topic

  // Unsubscribe from a previously created subscription
  subscription.remove();

How to set a variable in a script

// set the _options variable to "DEF"
bus.publish("chat:set-variables", {"_options":"DEF"});

Customer Information

Introduction

Usage

• customer:set-info: Sets the customer information, passing an object containing the desired properties. These properties are merged to any previously set customer information, overwriting properties with the same name.

  bus.publish("customer:set-info", {
      "First name": "John",
      "Last name":  "Doe",
      "Age":        25,
      "Premium":    true
  });

• customer:reset-info: Resets the customer information, erasing any properties previously set.

  bus.publish("customer:reset-info");

• customer:info-sent: Published as soon as the customer information is sent to the server, passing the information just submitted as well as the current chat phase.

  bus.subscribe("customer:info-sent", function(data) {
      // data.info contains the customer information just sent
      // to the server, and data.phase the current chat phase
  });

Implementation Example

Screenshots

• Customer information in agent transcript.

• Customer information in case details.

• Customer information in offline form email.

Important Notes

• The customer information can be set and/or reset at any time using the message bus and the respective customer:set-info and customer:reset-info topics, but it will only be actually sent to the server when the customer is added to a queue and/or has submitted an offline form.
• Whenever the customer information is submitted to the server, a message containing the data that was just sent will be immediately published to the message bus using the customer:info-senttopic. The tenant has no control over when the data is submitted to the server.
• Only primitive data types (strings, numbers and booleans) are allowed as values. Trying to set the customer information with non-primitive data types (e.g., objects, arrays and functions) will result in console warnings, and their values will be discarded.
• Setting a customer information already previously set will overwrite that information, unless the new value is undefined. If the new value is null, that information will be removed from the customer information and will not be sent to the server from that moment on, unless it is set again with a non-null, defined value.
• The customer information key:value pair is limited in 100 characters for the key and 500 character for the value. Any key:pair bigger than the specified value will be ignored.

Troubleshooting

• Make sure that, when trying to remove properties from the customer information without resetting all its properties (i.e., by using the customer:set-info topic), the passed properties have null values (and not undefined), as setting undefined values to properties do not have any effect on the final customer information.
• If the message Customer info <info> is not of a primitive type and will be discarded is shown in the browser console when trying to set the customer information, it means that the logged property value is of a data type unsupported by the embedded chat. Only primitive data types (strings, numbers and booleans) are currently allowed.
• If the message Customer info <info> key is too big and will be discarded is shown in the browser console when trying to set the customer information, it means that the key string length is too big. Only strings with length less than 100 characters are allowed.
• If the message Customer info <info> value is too big and will be discarded is shown in the browser console when trying to set the customer information, it means that the value string length is too big. Only strings with length less than 500 characters are allowed.

Chat Language

Introduction

• English: en
• Russian: ru
• German: de
• Japanese: ja
• Spanish: es
• French: fr
• Portuguese: pt
• Italian: it
• Polish: pl
• Croatian: hr
• Hindi: hi
• Dutch: nl
• Arabic: ar
• Danish: da
• Korean: ko
• Norwegian: no
• Swedish: sv
• Vietnamese: vi
• Welsh: cy
• Thai: th
• Simplified Chinese: zh-CN
• Traditional Chinese: zh-TW

Usage

• chat:set-language: Set the chat language.

  bus.publish("chat:set-language", "pt");

Important Notes

• The chat language can be set on any time before starting a chat (customer enter a queue) and you can change it as many time as you want, only the last value will be considered.
• Only system messages and the chat transcription will be localized to the configured language.
• This event should be published in the same bus as when setting the customer information.
• If there is a chat form with language question, the selected language has priority over language configured in chat-api.
• If there is a chat form with language question, the "set-language" sets the default language on the drop-down.
• The  set-language (default language) on the drop-down has priority over the browser language and the default language configured in the chat form.

Troubleshooting

• If the message "Chat language <language> is not valid and will be discarded" is shown in the browser console when trying to set the chat language, it means that the language code is not valid. Only language codes specified in the list of available languages above are valid.

End Chat Trigger

Introduction

Usage

• Chat: end: Trigger the chat end.

  bus.publish("chat:end");

Important Notes

• The API call to end the chat closes the chat window if an agent is not connected.
• The API call to end the chat triggers the confirmation to close if an agent is connected.
• The API call to end chat must be called on the same bus as the customer information.

Invitation Window Trigger

Introduction

Usage

• chat:trigger-invitation: Trigger the Invitation window.

  bus.publish("chat:trigger-invitation");

Important Notes

• When triggering the Invitation, it will only be open if the customer is not in a Pre-chat, Chat window or Offline form. So, it will show the Invitation window if the chat is closed or if it is displaying another Invitation. In this last case, the Invitation will be replaced by the new one.
• Calling this message will trigger the Invitation window, which is displayed only if an Invitation window is available for display in the Chat Script.
• If you don’t want your Invitation window to be automatically displayed (only by calling chat:trigger-invitation), set all your Invitations nodes in the Chat Script as Invitation to chat pops up after (seconds): Custom.
• This message must be called in the same bus as the Customer Information.
• When triggering the Invitation, a flag will be displayed on both Transaction Information Panel and Chat Log to identify the interaction was started by Chat API.

Troubleshooting

• Triggering the Invitation window is not a guarantee that a Invitation will be shown. The request will be sent to the server in order to check for an Invitation window in the Chat Script. So, if there isn’t any Invitation window available, none will be displayed.
• If the message Missing next step from step initInvitation [invitation] is shown in the browser console when trying to trigger the Invitation, it means that the Invitation is not available given the Chat Script conditions.

Pre-Chat window trigger

Introduction

Usage

• chat:trigger-pre-chat

bus.publish("chat:trigger-pre-chat");

Important Notes

• When triggering the Pre-Chat, it will only be open if the customer is not in a Pre-chat, Chat window or Offline form. So, it will show the Pre-Chat window if the chat is closed or if it is displaying an Invitation window.
• Calling this message will trigger the Pre-Chat window to be displayed only if a Pre-Chat window is available to be displayed in the Chat Script.
• This message must be called in the same bus as the Customer Information.
• When triggering the Pre-Chat, a flag will be displayed on both Transaction Information Panel and Chat Log to identify the interaction was started by Chat API.
• In case the Chat is configured to open as a popup in Chat Script, make sure the API is called as a result of a user's action, otherwise the Browser can block the popup window.
• In case the Chat is configured to open as a popup in Chat Script, the Pre-Chat window will be displayed only if no popup window is already opened.

Troubleshooting

• Triggering the Pre-Chat window is not a guarantee that a Pre-Chat will be shown. The request will be sent to the server in order to check for a Pre-Chat window in the Chat Script. So, if in that moment there isn't any Pre-Chat window available, none will be displayed.
• If the message Missing next step from step initPreChat [preChat] is shown in the browser console when trying to trigger the Pre-chat, it means that the Pre-Chat is not available given the Chat Script conditions.

Chat window trigger

Introduction

Usage

• chat:trigger-chat-window

bus.publish("chat:trigger-chat-window");

Important Notes

• When triggering the Chat, it will only be open if the customer is not in a Chat window. So, it will show the Chat window if the chat is closed or if it is displaying an Invitation or Pre-Chat window.
• Calling this message will trigger the Chat window to be displayed only if a Chat window is available to be displayed in the Chat Script.
• This message must be called in the same bus as the Customer Information.
• When triggering the Chat, a flag will be displayed on both Transaction Information Panel and Chat Log to identify the interaction was started by Chat API.
• In case the Chat is configured to open as a popup in Chat Script, make sure the API is called as a result of a user's action, otherwise the Browser can block the popup window.
• In case the Chat is configured to open as a popup in Chat Script, the Chat window will be displayed only if no popup window is already opened.

Troubleshooting

• Triggering the Chat window is not a guarantee that a Chat will be shown. The request will be sent to the server in order to check for a Chat window in the Chat Script. So, if in that moment there isn't any Chat window available, none will be displayed.
• If the message Missing next step from step initChatWindow [chatWindow] is shown in the browser console when trying to trigger the Chat, it means that the Chat is not available given the Chat Script conditions.

System Message Localization

Introduction

Configuration

Available System Messages that can be Customized

• endChatButton: “End chat”
• closeChatButton: “Close”
• errorServerUnavailable: “Server is unavailable. Please, try again later.”
• chatEstablished: “Your chat session has been established.”
• chatEstablishedName: "You are now chatting with {<agent>}."
• chatEstablishedAgent: "You are now chatting with an agent."
• chatEstablishedAgentNew: "You are now chatting with a new agent."
• chatQueued: “We will be with you shortly.”
• chatForwarded: “Your chat is being forwarded. Please wait.”
• chatMsgTooLong: “Your last message was shortened because it exceeded maximum length.”
• chatDisconnected: “You have been disconnected from your chat session. Please check your network connection and try again.”
• chatEnded: “You have ended your chat session.”
• agent: "Agent"
• agentTyping: “Agent is typing…”
• agentTypingName: "{<agent>} is typing..."
• agentDisconnected: “The agent has disconnected from this chat session.”
• errorInvalidLogin: “We have encountered an error trying to start a new chat. Please try again later.”
• endChatNotification: “Chat session has been ended.”
• endChatConfirmation: “Are you sure you want to end this chat session?”
• chatLogTitle: “Chat Log”
• chatLogDescription: “Below is a complete log of the chat session.”
• yesButton: “Yes”
• noButton: “No”
• coBrowsingStartButton: "Start co-browsing session"
• coBrowsingEndButton: "End co-browsing session"
• saveButton: “Save”
• clearButton: “Clear”
• pullDownInfo: “Swipe to see more options”
• errorGenericMessage: “Sorry, something went wrong. Please try again later.”
• errorRequiredMessage: “Please verify the mandatory fields”
• errorCrmFieldInvalidMessage: “Sorry, we couldn’t find your information using the value you provided.”
• errorInvalidNumber: “The field is a numeric field.”
• errorInvalidEmail: “The field only accept the valid e-mail format.”
• preChatFormData: “Pre-Chat form data”
• offChatFormData: “Offline form data”
• skipQueueFormData: “Skip Queue form data”
• chatTranslationOn: “Automatic chat translation has been turned on.”
• chatTranslationOff: “Automatic chat translation has been turned off.”
• chatTranslationServiceError: “Translation service error.”
• coBrowsingInvitePrompt: "Allow agent to see your browser window?"
• coBrowsingInviteAccept: "Yes, start sharing"
• coBrowsingInviteReject: "No"
• coBrowsingInviteAccepted: "You accepted the request."
• coBrowsingInviteRejected: "You rejected the request."
• coBrowsingSessionStarted: "Co-browsing session started."
• coBrowsingSessionEnded: "Co-browsing session ended."
• coBrowsingSessionRestored: "Co-browsing session restored."
• sessionDisconnected: “Your chat session has ended.”
• emptySubject: "[ Customer message ] No subject"

Implementation Example

Important Notes

Custom Stylesheet

Introduction

Configuration

An example style sheet

The stylesheetURL parameter MUST be a CSS file served over SSL (HTTPS protocol).

Important Notes

• A functional stylesheet should be written by inspecting the current chat window HTML structure. This can be done using a web inspector, a tool shipped with most web browsers today.
• As the chat window HTML structure may change between versions, the tenant should test their customizations when upgrading to make sure they are working as expected.