Genesys Webchat v1.1.11

Example Implementation and Documentation

Release Notes

Version Date Changelog
1.1.8 2015-12-14 genesys-webchat.jquery.options.min.js
  • Bug fixes
genesys-webchat.jquery.min.js
  • Bug fixes
1.1.7 2015-05-21 genesys-webchat.jquery.options.min.js
  • Removed optional jQuery library (exists in genesys-webchat.jquery.min.js)
  • Removed cookie library (exists in genesys-webchat.jquery.min.js)
genesys-webchat.jquery.options.min.js
  • Reduced filesize
  • Consolidated Eliza demo transport libraries
  • Bug fixes
1.1.6 2015-05-08 genesys-webchat.jquery.options.min.js
  • Bug fixes
  • Showing first and last name fields by default
  • Added "eliza" transport to demonstrate chat in offline mode
  • Using "eliza" transport by default
genesys-webchat.jquery.options.min.js
  • Bug fixes




Supported Browsers

10+ 5.1+
(Current-1) or Current (Current-1) or Current




File Reference

File Description
genesys-webchat-demo.htmlThis page. A demo of how to include our webchat component on your page. This page represents a page on your site. You may define any per-page userData overrides on each page. View the source to see the example implementation.
genesys-webchat.jquery.options.min.js The main configuration file for webchat. Contains all connection, rendering, and proactive engagement options. See Table. This file must be included for chat to function.
genesys-webchat-window.htmlThe popup chat window HTML file. You must point to the location of this file in your configuration.
genesys-webchat-i18n.jsonOptional multi-language pack as a separate file. You must point to the location of this file in your configuration.
genesys-webchat.jquery.min.jsThe main webchat library. This must be included on the page for overlay to work and inside the popup window HTML file.




Genesys Webchat Options (Defined in genesys-webchat.jquery.options.min.js)

Property Name Value Required Info
UI Settings
mode "overlay"
"popup"
Y Overlay mode shows the chat widget on the same page. Popup opens the chat inside a new window
template String Y (For Overlay mode only) Value is equal to the HTML Element ID of the Webchat template. This value comes preset by Genesys
prefilters Array N OPTIONAL An array of regular expressions used as prefilters to keep matching chat messages from appearing in the chat transcript
Connection Settings
transport "pod"
"apg"
"vcc"
Y Select the chat server type. Appropriate value provided by Genesys
id String Y Chat Server Connection ID. Appropriate value provided by Genesys
dataURL URL Y Chat Server URL. Typically "https://chat_server_host/api/v2/chats". Appropriate value provided by Genesys
CSRFURL URL Y Chat Server CSRF Security Token URL. Typically "https://chat_server_host/api/v2/diagnostics/version". Appropriate value provided by Genesys
userData JSON Y Optional data to pass to the chat server such as "skillLevel" or other arbitrary data
Internationalization (i18n)
i18n_lang String N Sets the current language code. Uses language codes defined in your language pack (i18n_URL JSON file or i18n_messages object). Typically customers will opt to use ISO 639-1 language codes. More Info
i18n_URL URL N URL to a JSON file containing your language packs. More Info
i18n_messages JSON N A JSON object containing your language packs. Supercedes i18n_URL language packs. More Info
Popup Window Settings
popupChatWindowHREF URL Y The URL of the genesys webchat window (genesys-webchat-window.html). You must host this file and set this URL to point to it.
popupChatWindowOptions String Y Display parameters for the webchat popup window, such as dimensions and position. For more info see the specs section here.
Flags for Basic Proactive Engagement
ShowInvite Boolean Y Enable/Disable the Chat Invite overlay and assiciated timers below.
TrackMouseIdle Boolean Y Enable/Disable the use of mouse movement idle time tracking as a basis for displaying the Chat Invite overlay. If set to true, the ChatInviteDelay countdown will be reset when the user moves their mouse. This way the invite only appears when the user is completely idle.
Timers for Basic Proactive Engagement
ChatInvite Do not modify. Internal use only.
ChatInviteMouseIdle Do not modify. Internal use only.
ChatInviteDelay Integer Y The number of milliseconds to wait before displaying the Chat Invite overlay
HTML References for Basic Proactive Engagement
FloatingChatButton $("selector") Y A JQuery selector identifying the HTML template for the floating chat button
ChatInviteOverlay $("selector") Y A JQuery selector identifying the HTML template for the Chat invite overlay
ChatInviteAccept $("selector") Y A JQuery selector identifying the Accept button within the ChatInvitePopup template
ChatInviteDecline $("selector") Y A JQuery selector identifying the Decline button within the ChatInvitePopup template




Chat Entry Form

Supported Form Inputs



Type Input Name
First Namefirstname
Last Namelastname
Nicknamenickname
Subjectsubject
Emailemail




Example of Fully Loaded Entry Form


    <div class='form'>
        <label><span class='i18n' data-message='ChatFormFirstName'>First Name</span><input name='firstname'></label>
        <label><span class='i18n' data-message='ChatFormLastName'>Last Name</span><input name='lastname'></label>
        <label><span class='i18n' data-message='ChatFormNickname'>Nickname</span><input name='nickname'></label>
        <label><span class='i18n' data-message='ChatFormSubject'>Subject</span><input name='subject'></label>
        <label><span class='i18n' data-message='ChatFormEmail'>Email</span><input name='email'></label>
        <button class='submit i18n' data-message='ChatFormSubmit'>Start Chat</button>
    </div>



You may add or remove these inputs as you require for your implementation. Currently these are the only supported fields.

Chat Support






Internationalization (i18n)

Selecting a Language

You may change the language of the chat widget by changing this value on your page.

    <script>

        window.oChatOptions.i18n_lang = "en";

    </script>

Here the selected language is hardcoded as "en". Replace "en" with a reference to the value of the language code you opt to use in your language pack. If you use a cookie to store the language code on your site, set this to the value of that cookie on every page load.



Referencing a Language Pack

Using a separate file

The setting "i18n_URL" is used for identifying your i18n file. The value of this should be a direct URL to the file containing the different languages. An example file named genesys-webchat-i18n.json is included. It contains two example languages, English and Russian. They use the language codes "en" and "ru" respectively but you can choose any language code schema you want to use. These language codes should match the values of your language cookie for easiest integration.

Example JSON File:


    {

        "en": {

            "ChatStarted": "Chat Started",
            "ChatEnded": "Chat Ended",
            "ChatFailed": "Failed to Start Chat Session",
            "UserNameDefault": "Anonymous",
            "AgentNameDefault": "Agent",
            "AgentConnected": "<%Agent%> Connected",
            "AgentDisconnected": "<%Agent%> Disconnected",
            "AgentTyping": "<%Agent%> is typing",
            "AgentPending": "An Agent will be with you shortly",
            "AgentUnavailable": "Sorry. There are no agents available. Please try later",
            "ChatTitle": "Chat Support",
            "ChatEnd": "End Chat",
            "ChatClose": "Close",
            "ChatFormName": "Name",
            "ChatFormEmail": "Email",
            "ChatFormSubmit": "Start Chat",
            "ChatInputPlaceholder": "Type your message here and hit return...",
            "ChatInputSend": "SEND"
        },

        "ru": {

            "ChatStarted": "чат работы",
            "ChatEnded": "чат состава",
            "ChatFailed": "Не удалось запустить сеанс чата",
            "UserNameDefault": "анонимный",
            "AgentNameDefault": "агент",
            "AgentConnected": "<%Agent%> связанный",
            "AgentDisconnected": "<%Agent%> отключен",
            "AgentTyping": "<%Agent%> печатает",
            "AgentPending": "Агент будет с Вами в ближайшее время",
            "AgentUnavailable": "Извините. Там нет агентов, доступных . Пожалуйста, попробуйте позже",
            "ChatTitle": "Чат поддержки",
            "ChatEnd": "Конец Чат",
            "ChatClose": "близко",
            "ChatFormName": "имя",
            "ChatFormEmail": "Email",
            "ChatFormSubmit": "Начать Чат",
            "ChatInputPlaceholder": "Введите Ваше сообщение здесь и нажмите возврат...",
            "ChatInputSend": "слать"
        }
    }


Defining languages inline

Instead of hosting a separate file, you can include the language pack JSON inline in the file genesys-webchat-i18n.json under the "i18n_messages" property.

Example Inline Definition:


    "i18n_messages": {

        "en": {

            "ChatStarted": "Chat Started",
            "ChatEnded": "Chat Ended",
            "ChatFailed": "Failed to Start Chat Session",
            "UserNameDefault": "Anonymous",
            "AgentNameDefault": "Agent",
            "AgentConnected": "<%Agent%> Connected",
            "AgentDisconnected": "<%Agent%> Disconnected",
            "AgentTyping": "<%Agent%> is typing",
            "AgentPending": "An Agent will be with you shortly",
            "AgentUnavailable": "Sorry. There are no agents available. Please try later",
            "ChatTitle": "Chat Support",
            "ChatEnd": "End Chat",
            "ChatClose": "Close",
            "ChatFormName": "Name",
            "ChatFormEmail": "Email",
            "ChatFormSubmit": "Start Chat",
            "ChatInputPlaceholder": "Type your message here and hit return...",
            "ChatInputSend": "SEND"
        },

        "ru": {

            "ChatStarted": "чат работы",
            "ChatEnded": "чат состава",
            "ChatFailed": "Не удалось запустить сеанс чата",
            "UserNameDefault": "анонимный",
            "AgentNameDefault": "агент",
            "AgentConnected": "<%Agent%> связанный",
            "AgentDisconnected": "<%Agent%> отключен",
            "AgentTyping": "<%Agent%> печатает",
            "AgentPending": "Агент будет с Вами в ближайшее время",
            "AgentUnavailable": "Извините. Там нет агентов, доступных . Пожалуйста, попробуйте позже",
            "ChatTitle": "Чат поддержки",
            "ChatEnd": "Конец Чат",
            "ChatClose": "близко",
            "ChatFormName": "имя",
            "ChatFormEmail": "Email",
            "ChatFormSubmit": "Начать Чат",
            "ChatInputPlaceholder": "Введите Ваше сообщение здесь и нажмите возврат...",
            "ChatInputSend": "слать"
        }
    }




Special Codes in Language Pack

You may have noticed that the messages in the language pack include the curious code <%Agent%>. This code is replaced by the name of the agent that comes from the chat server. If no name is provided by the server, this value will default to whatever value you have set for "AgentNameDefault" in the language pack. You can see in the example language pack that "AgentNameDefault" is "Agent" for English and "агент" for Russian. 

In the example, <%Agent%> is being used in 3 messages:


    "AgentNameDefault":  "Agent",
    "AgentConnected":    "<%Agent%> Connected",
    "AgentDisconnected": "<%Agent%> Disconnected",
    "AgentTyping":       "<%Agent%> is typing",

If the server returned the name of the agent as "Tom Smith" the messages would be transformed like this:


    "AgentNameDefault":  "Agent",
    "AgentConnected":    "Tom Smith Connected",
    "AgentDisconnected": "Tom Smith Disconnected",
    "AgentTyping":       "Tom Smith is typing",

If the server returned no name for the agent, "AgentNameDefault" will be used instead, resulting in this:


    "AgentNameDefault":  "Agent",
    "AgentConnected":    "Agent Connected",
    "AgentDisconnected": "Agent Disconnected",
    "AgentTyping":       "Agent is typing",

Using <%Agent%> is optional and is included in the example to illustrate it's purpose.



Final Language Notes

If you do not specify a language pack file URL or you don't specify a language pack inline, the Chat client will default to its internal language pack which is English and matches the English example in genesys-webchat-i18n.json.







Public Methods

Method Arguments Description
open()noneThe chat widget will go from a hidden state to a visible state
close()noneThe chat widget will go from a visible state to a hidden state
clear()noneThe transcript and all inputs will be cleared to a default empty state
reset()noneCalls clear() then showForm() to return the widget to a default state
startSession()noneStarts the chat session using the chat options from your configuration
endSession()noneEnds the active chat session
suspend()noneSuspend/pause polling
resume()noneResume polling
showForm()noneHides the transcript view and shows the entry form view
hideForm()noneShows the transcript view and hides the entry form view
checkForm()noneChecks form for completeness (if any checks are in place)
updateI18nMessages()noneUpdates all the strings appearing in the chat template to the current language set (does not modify the transcript)
addPrefilter( /regex/ or [/regex/] )/regex/ = a regular expression used to filter out a message

or

[/regex/] = an array of regular expressions
Allows you to pass in one or more regular expressions as prefilters to block matching messages from appearing in the chat transcript.
clearPrefilters()noneClears all regular expression prefilters currently registered in the Chat UI instance
sendFilteredMessage( string, /regex/ )string = message body

/regex/ = a regular expression used to filter out the message
Allows you to send a special message that wont appear in the transcript. Useful for sending special codes/commands to the server. You may optionally send a new regular expression prefilter along with the message. This will register the expression into the prefilters list. If no prefilters are registered, your message will appear in the transcript. You can register new prefilters using the "prefilters":[] parameter in the chat options object, using .addPrefilter(), or passing the new filter with sendPrefilteredMessage()
isReady()noneReturns a boolean value indicating ready status
isAgentConnected()noneReturns a boolean value indicating if an agent is connected or not




Event Handlers

You can attach a callback function to event handlers in the chat widget.
You may set these in the genesys-webchat.jquery.options.min.js file.

Attach event handlers like so:

GenesysWebChatInstance.onOpen = function(){ /* do something */ };

Event Description
onOpenTriggered when chat window is opened
onCloseTriggered when chat window is closed
onReadyTriggered when the chat UI has fully initialized and can start a session
onStartTriggered when chat starts
onStartFailedTriggered when chat fails to start
onCancelledTriggered when the user clicks the "close" button while waiting for the chat to start
onEndTriggered when chat is ended by user (clicking "End" button)
onRestoreTriggered when chat is restored in overlay mode after refresh or page navigation
onAgentConnectedTriggered when agent connects to the chat
onAgentDisconnectedTriggered when agenet disconnects from the chat
onSessionEndedTriggered when the chat server sends successful chat session end