This document is a documentation for Brand Embassy Live Chat Window, which may be implemented to your website. Brand Embassy Live Chat Window offer JavaScript API to allow advance integration with your website towards better experience for your users and improving efficiency of your agents.

Note: We recommend you first implement Live Chat on your staging environment and test it before releasing to production.

Also our Business Professional Services offer service of Live Chat Technical Onboarding, which will help you with the LiveChat set-up and ensuring it's implemented correctly to your maximum benefit.

Code for initialization

Find the code in the settings/social channels/chat/Initialization & Test

 <script>
 (function (i, s, o, r, g, v, a, m) {
 g = v ? g + '?v=' + v : g; i['BrandEmbassy'] = r;
 i[r] = i[r] || function () { (i[r].q = i[r].q || []).push(arguments) }; i[r].l = +new Date();
 a = s.createElement(o); m = s.getElementsByTagName(o)[0]; a.async = 1;
 a.src = g + '?' + Math.round(Date.now() / 1000 / 3600); m.parentNode.insertBefore(a, m)
 }) (window, document, 'script', 'brandembassy', 'https://livechat-static.brandembassy.com/4/chat.js');

 brandembassy('init', brand_id , '%BRAND_HASH%');
  // `Put additional API calls here, if needed
</script>

It's mandatory to put this exact JavaScript code to your website in order to run Brand Embassy Live Chat on your website.

Communication

Open the window

Live Chat Windows is being opened by A) user clicks on the sticker of the Live Chat B) by Proactive pop-ups which are set in the Settings of your Brand Embassy account. However you may also open this window to start chatting programmatically as follows:

brandembassy('openChatWindow');

Close the window

You can close the window with:

brandembassy('closeWindow');

Set Agent's Image

When customer chats with an agent, the image of an agent is displayed. This image is set in the Settings of your Brand Embassy Account. If this image is needed to be changed dynamically, you may use the following command:

brandembassy('setAgentImage', 'http://myweb.com/some_image.png');

Start a new chat session

If needed you may also start a new chat session for the user (if there is no other currently active) right away by using the following set of commands.

Note: this will create a new session which will be loaded into an queue and will be routed to agent as soon as agent is available according to Intelligent Routing. We strongly recommend to not to initiate automatically sessions on points where high load of visitors is expected (e.g. on homepage etc.)

if all agents are at that time unavailable and serving other customers, the screen for “waiting for available agent” will be initiated.

// set customer name (as this is required field)
brandembassy('setCustomerName', 'Peter');

// open chat window so user can start to chat
brandembassy('openChatWindow');

// and finally start the new chat session (without the pre-chat form)
brandembassy('autoStartSession');

When adding commands, 'autoStartSession' should be always added as the last.

Set initial customer message

The new ticket is created in the Brand Embassy platform with the first message from the customer. Therefore when customer presses the button to begin conversation, an automated message is sent on his behalf so the ticket is created right away. The automated message is by default hidden and only agent can see that. If you want to have the message appear to your customers as well, please add the following command:

brandembassy('hideFirstSentMessage', false);

If you don't want the ticket to be created immediately and you prefer to wait for customer's first message, you can use the following command:

brandembassy('sendFirstMessageAutomatically', false);

Content of the first default message is populated from the button's label. You can override it either by following command:

 brandembassy('sendFirstMessageAutomatically', 'New conversation');

or use a second type of command and change the first message dynamically based on the page the consumer is currently on:

brandembassy('setFirstAutomatedMessageContent', 'Begin new conversation');

You can also set the wording in chat channel settings in the UI translation section.

Custom Fields

Case custom fields and hidden custom fields may be filled by using following command:

brandembassy('setCustomField', 'ident-of-custom-field', 'value-of-custom-field');

Translations

Translations can be set-up through the Brand Embassy Settings, but can be adjusted as well by using the JavaScript API for example if there is a need to dynamically change the labels or languages.

// to change one label
brandembassy('setTranslation', 'key', 'your translation');

// to change multiple labels
brandembassy('setTranslations', {
   key1: 'your translation',
   key2: 'your another translation'
});

Available labels for translation

{
 "allAgentsForQueueAreBusy": "All our agents dedicated to your queue are currently busy. There {queue, plural, one {is} other {are}} <strong>{queue, number}</strong> {queue, plural, one {person} other {people}} ahead of you in the queue.",
 "beginButton": "Begin chat!",
 "cancel": "Cancel",
 "caseNumber": "Case #{caseNumber}",
 "change": "Change",
 "chattedWith": "You just had a chat with",
 "commonErrorText": "There was an unexpected error. Please try again later.",
 "done": "Done",
 "dragAndDropDropzone": "Drag & drop files here, to send them",
 "dragAndDropDropzoneRejected": "Impossible to upload file :(",
 "EmailLabel": "E-mail",
 "endChat": "End chat",
 "endChatTitle": "Are you sure you want to end this conversation?",
 "endGame": "End game",
 "ending": "Ending chat...",
 "fileSendingFailed": "File sending failed",
 "getTranscriptDescription": "Send transcript of this conversation to the following email address:",
 "getTranscriptLink": "Get chat transcript",
 "invalidToken": "Invalid token",
 "ipAddressBlocked": "IP address is blocked",
 "loading": "Loading ...",
 "loadPreviousButton": "Load previous conversations",
 "messageLabel": "Message",
 "networkErrorText": "There was an network error. Please try again.",
 "newCase": "New case",
 "noAgentOnlineForQueue": "No agent is available for your queue at the moment.",
 "offline": "Offline",
 "offlineFormDesc": "We are not available at the moment",
 "offlineFormSuccessMsgHead": "Thank you!",
 "offlineFormSuccessMsgSub": "Your email was successfully sent. We'll get back to you soon.",
 "online": "Online",
 "onlineFormText": "To start a chat, please tell us your name. One of our agents will start helping you immediately ;)",
 "pleaseSelect": "Please select...",
 "poweredBy": "Powered by",
 "preparingSession": "Preparing session...",
 "replyBoxPlaceholder": "Write here, press<enter> to send",
 "retry": "Retry",
 "sendFileTextSize": "Please upload files smaller than {filesize} and of ",
 "sendFileTextSupportedFormat": "supported formats.",
 "sendFileTextSupportedFormatDesc": "Images, Videos, {fileFormats}",
 "sendMessageButton": "Send message",
 "sendNewEmail": "Send new email",
 "sendTranscript": "Send transcript",
 "snakeWaiting": "You're {queue} in queue.",
 "startChatInPopup": "Ask us!",
 "startNewChat": "Start a new chat",
 "statusReconnecting": "Trying to connect…",
 "surveySuccesfullySent": "Thank's for your feedback!",
 "systemChattingWith": "You are now chatting with {name}",
 "topic": "Topic",
 "transciptSentFailed": "Send failed.",
 "transciptSuccesfullySent": "Transcipt succesfully sent!",
 "tryAgainButton": "Try again",
 "unexpectedError": "Unexpected error.",
 "validationInvalidEmail": "E-mail address is not valid",
 "validationMandatory": "This field is mandatory",
 "validationShorterName": "Please use shorter name",
 "validationShortMessage": "Your messge is too short",
 "waiting": "Waiting...",
 "waitingDescription": "One of our agents will talk to you shortly.",
 "waitingFooter": "Hit <spacebar> to shorten the waiting.",
 "waitingForAgent": "Waiting for agent...",
 "waitingInQueue": "Waiting for agent. You're {queue} in queue.",
 "weAreOffline": "We're currently offline.",
 "weAreOnline": "We're online",
 "yourNameLabel": "Your name"
}

UI

You can transform UI elements through API to achieve desire look for your type of implementation

Hide Header

You can hide the header of the livechat with:

brandembassy('hideHeader');

Hide Popups

You can explicitly hide popups with:

brandembassy('hidePopups');

Hide/Show Send Transcript

You can explicitly hide/show transcript button:

brandembassy('hideSendTranscript');
brandembassy('showSendTranscript');

Show Send Button

You can turn on case reply button which is shown to the customer in chat window. This is useful for in-app integration.

brandembassy('showSendButton');

Show case info

You can turn on case information which are shown to the customer in chat window. ONLY for asynchronous chat.

brandembassy('showCaseInfo');

Size

You can set up custom width and height of chat window. You can use absolute or relative units supported by CSS specification. (https://www.w3schools.com/cssref/css_units.asp)

brandembassy('setWindowWidth', '100%');
brandembassy('setWindowHeight', '100%');

Full Display mode

You can stretch chat window to the full width and height with following shortcut or alternatively use commands for sizing.

brandembassy('setFullDisplay');

// OR

brandembassy('setWindowWidth', '100%');
brandembassy('setWindowHeight', '100%');

Move the window [Deprecated - use 'Position and offset' instead]

You can move the window horizontally. You can choose if you prefer to have the window on the left or right side and the distance on screen from the left or right corner like so:

brandembassy('moveChatWindow', 'left', '50');

Position and offset

We redefine how you can set up the position of the chat window on your website. With 'SetPositionX' you define the left or right side of the screen as starting position. With 'setOffsetX' and 'setOffsetY' you can define how many pixels it should be offset horizontally or vertically.

// set horizontal starting position
brandembassy('setPositionX', 'right');

// set horizontal and vertical offset
brandembassy('setOffsetX', '40'); // default = 20
brandembassy('setOffsetY', '40'); // default = 20

Snake Game

Your customers will be able to play a vintage game called ‘Snake’, while they are waiting in queue for the next available agent.

brandembassy('allowGameMode');

Set character limit for reply box

You can limit number of characters, which can customer write in one message.

brandembassy('setReplyBoxLimit', '280'); // default = null

Custom CSS

You can customize Live Chat components with your own CSS rules.

brandembassy('setCustomCss', 'div {background: red}');

We also introduced component selectors which are inserted in attribute 'data-selector'. This selectors should help you select and style components used on many different views. We can not guaranteed that your class selectors will work properly, because we are using dynamic generated css classes for every new version of Live Chat window. The best way how to validate your CSS selections is to use development console in Chrome or any other browser, where you can look into the HTML structure and inspect the elements.

Currently available component selectors

MESSENGER
WINDOW
WIDGET
HEADER
DROPDOWN_MENU
CONTENT
CUSTOMER_MESSAGE
CUSTOMER_MESSAGE_BUBBLE
AGENT_MESSAGE
AGENT_MESSAGE_BUBBLE
REPLY_BOX
INPUT
TEXTAREA
TEXT_BUTTON
PRIMARY_BUTTON
SECONDARY_BUTTON
POPUP
SEND_BUTTON
ACTIVITY_BAR
DELIMITER
AVATAR
IS_TYPING
TERMS_OF_USE_BUTTON
TERMS_OF_USE_MODAL

[CORRECT] Example of component selector usage in CSS:

[data-selector="PRIMARY_BUTTON"] {
  background: red;
}

[WRONG] Example of class selector usage in CSS:

.Widget__Widget___1qQCf {
  background: red;
}

Best Practices

Nesting

Components are often build with multiple blocks which are nested, but our selectors will give you only root of each component. We suggest to use developers console and inspect specific component, which you want to modified.

Example #1: I want to change color of the text in reply box to red

[CORRECT]

[data-selector="REPLY_BOX"] textarea {
  color: red;
}

[WRONG]

[data-selector="REPLY_BOX"] {
  color: red;
}

Authorization via OAuth

It is possible to authorize the end user of chat window via OAuth. For the full functionality to work, you need to add following command before the chat initialization code:

brandembassy('setAuthorizationCode', 'authorization code');

In the chat initiatilization script, the codes should then be in this order:

brandembassy('setAuthorizationCode', 'authorization code');
brandembassy('init', brandId, channelId);

The 'authorization code' value needs to be passed via your web application or application within the smartphone. The OAuth authorization needs OAuth server to be set up and enabled in the settings.

Functionality

Terms of Use

This functionality makes your own 'Terms of Use' accessible for your customers directly from the Chat Window. The new button will be available, in which you can define its label, style, and on click function - it can show the 'Terms of Use' as:

Internal Modal Window
External Link

// Internal Modal Window
brandembassy('showTermsOfUse', 'Show terms of Use', 'modal' , 'Our terms of use are ...');

// External Link
brandembassy('showTermsOfUse', 'Show terms of Use', 'externalLink' , 'http://yourdomain.com/terms-of-use');

// If you want to explicitely disable this feature, you can use
brandembassy('hideTermsOfUse');

If you want to define your own styles for the button or for the internal modal window, we recommend using the custom CSS function described above.

Integration to Android/iOS Application

There is a possibility to use our chat directly in Android/iOS App. In this case, the native application is required to use WebView where the javascript initialization code needs to be put in.

We recommend to publish the code on a html page publicly available from the internet and then embed it into your mobile app.

The code is using API calls from documentation to achieve the desired look and behavior.

<script async type=”text/javascript”>
  (function(i,s,o,r,g,v,a,m){g=v?g+'?v='+v:g;i['BrandEmbassy']=r;
    i[r]=i[r]||function(){(i[r].q=i[r].q||[]).push(arguments)};i[r].l=+new Date();
    a=s.createElement(o);m=s.getElementsByTagName(o)[0];a.async=1;
    a.src=g+'?'+Math.round(Date.now()/1000/3600);m.parentNode.insertBefore(a,m)
  })(window,document,'script','brandembassy','https://livechat-static.brandembassy.com/3/chat.js');

  //init of Livechat
  brandembassy(‘init’, BRAND_HASH);

  // hiding unwanted UI elements
  brandembassy('hideHeader');
  brandembassy('hidePopups');
 
  // stretching livechat to full width and height
  brandembassy('setFullDisplay');

  // Customer's name
  brandembassy('setCustomerName', 'CUSTOMER_NAME');

  // Other optional Custom Fields
  brandembassy('setCustomField', 'CUSTOM_FIELD_NAME_SET_IN_BRANDEMBASSY', 'CUSTOM_FIELD_VALUE');
    
  // Start Chat
  brandembassy('openChatWindow');
  brandembassy('autoStartSession');

</script>

Event subscription

Host environment is able to listen to events emitted by Chat Window.

Subscription

You can subscribe to a variety of events with the following command.

brandembassy('setAllowedExternalMessageTypes', ['EVENT_TYPE', 'ANOTHER_EVENT_TYPE'])

Events

We are currently supporting the following events.

MESSAGE_RECEIVED
CHAT_SESSION_RECOVERED

Listening

We are using window.postMessage (https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) method for safe cross-origin communication between Window objects. Our data are coming in the following structure.

...
data: {
  actionType: 'MESSAGE_RECEIVED',
  payload: {agentId: 2}
}

Messaging

Our chat solution also offers Messaging capabilities. Messaging is an asynchronous type of conversation and is usually used in the websites and applications where the customer is logged in and his identity is known. In this section, you can find commands which are related to the Messaging experience.

Set Activity Status

You can set the availability/activity status message which is shown in the activity bar. Brands usually use it to communicate their response time on messaging channels to manage customer’s expectations.

brandembassy('setStatusMessage', 'We typically reply in 3h');

Set Customer Name

Customer Name is a mandatory field for a customer to fill in to start to chat with an agent. This field may be pre-filled dynamically as follows:

brandembassy('setCustomerName', 'John Doe');

Hide pre-survey form

You can hide a pre-survey form, where you asked usually for the customer's name and show the conversation right away.

brandembassy('hidePreSurvey');

Autostart session

In case you need to autostart session in async chat (for example for the purposes of initiating chatbot flow), you need to use the set of following commands:

brandembassy('sendFirstMessageAutomatically', 'New conversation');

brandembassy('autoStartSession');

Please keep the same order, as the autoStartSession command needs to happen after the sendFirstMessageAutomatically command.

The commands will skip the pre-chat survey and automatically send a message from customer's side that triggers the start of the session. You can change the wording of the first message either via UI translation settings or via the following command:

brandembassy('setFirstAutomatedMessageContent', 'Begin new conversation');