Genesys Documentation - User contributions [en]

WID/Current/SDK/WebChatService-combined

2020-10-29T17:11:27Z

Chrissyforrest: Published

{{Article
|Standalone=No
|DisplayName=WebChatService
|TocName=WebChatService
|Context=Learn how to use Genesys chat services.
|ComingSoon=No
|Platform=GenesysEngage-cloud
|Role=Developer
|Section={{Section
|sectionHeading=Overview
|anchor=overview
|alignment=Vertical
|structuredtext=WebChatService exposes high-level API access to Genesys chat services, so you can monitor and modify a chat session on the front end, or develop your own custom WebChat widgets. Compared to developing a custom chat UI and using the chat REST API, WebChatService dramatically simplifies integration—improving the reliability, feature set, and compatibility of every widget on the bus.

===Usage===

WebChatService and the matching WebChat widget work together right out of the box and they share the same configuration object. Using WebChat uses WebChatService.

You can also use WebChatService as a high-level API using bus commands and events to build your own WebChat widget or other UI features based on WebChatService events.

===Namespace===

The WebChat Service plugin has the following namespaces tied to each of the following types:

{{{!}}
{{!}}-
!{{!}}Type
!{{!}}Namespace
{{!}}-
{{!}}{{!}}{{Link-SomewhereInThisVersion|manual=SDK|topic=WebChatService-combined|anchor=config|display text=Configuration}}
{{!}}{{!}}webchat
{{!}}-
{{!}}{{!}}CXBus—{{Link-SomewhereInThisVersion|manual=SDK|topic=WebChatService-combined|anchor=commands|display text=API commands}} & {{Link-SomewhereInThisVersion|manual=SDK|topic=WebChatService-combined|anchor=events|display text=API events}}
{{!}}{{!}}WebChatService
{{!}}}

===Customization===

WebChatService has many configuration options but no customization options. It is a plug-and-play plugin and works as is.
|Status=No
}}{{Section
|sectionHeading=Configuration
|anchor=config
|alignment=Vertical
|structuredtext=WebChat and WebChatService share the '''_genesys.widgets.webchat''' configuration namespace. WebChat contains the UI options and WebChatService contains the connection options.

{{NoteFormat|Starting with version 9.0.008.04, WebChatService allows you to choose between the types of chat services available in Genesys via the transport section in {{Link-SomewhereInThisVersion|manual=SDK|topic=WebChatService-combined|anchor=options|display text=configuration options}}.|}}

{{AnchorDiv|example}}
===Example===

<pre>
// When using v2 API

window._genesys.widgets.webchat = {

apikey: 'n3eNkgxxxxxxxxxxxx8VA',
dataURL: 'https://api.genesyscloud.com/gms-chat/2/chat',
enableCustomHeader: true,

userData: {},
emojis: true,
actionsMenu: true,

autoInvite: {

enabled: false,
timeToInviteSeconds: 10,
inviteTimeoutSeconds: 30
},

chatButton: {

enabled: true,
template: '<div>CHAT NOW</div>',
effect: 'fade',
openDelay: 1000,
effectDuration: 300,
hideDuringInvite: true
}
};

// When using v3 API

window._genesys.widgets.webchat = {

emojis: true,
userData: {},
transport: {

type: 'pureengage-v3-rest',
dataURL: https://<hostname>/nexus/v3/chat/sessions,
endpoint: 'xxxxxxxxx',
headers: {
'x-api-key': 'xxxxxxxx'
},
async: {

enabled: true,

getSessionData: function(sessionData, Cookie, CookieOptions) {

// Note: You don't have to use cookies. You can, instead, store in a secured location like a database.
Cookie.set('customer-defined-session-cookie', JSON.stringify(sessionData), CookieOptions);
},

setSessionData: function(Open, Cookie, CookieOptions) {

// Retrieve from your secured location.
return Cookie.get('customer-defined-session-cookie');
}
},

chatButton: {

enabled: true,
template: '<div>CHAT NOW</div>',
effect: 'fade',
openDelay: 1000,
effectDuration: 300,
hideDuringInvite: true
}
};
</pre>
{{AnchorDiv|options}}
===Options===

{{AnchorDiv|v2}}
====Version 2 API====
{{{!}} class="wikitable"
!Name
!Type
!Description
!Default
!Required
!Introduced/Updated
{{!}}-
{{!}}apikey
{{!}}string
{{!}}Apigee Proxy secure token.
{{!}}n/a
{{!}}Yes, if using Apigee Proxy
{{!}}
{{!}}-
{{!}}endpoint
{{!}}string
{{!}}Manually select the endpoint on which to initiate chat.
{{!}}n/a
{{!}}n/a
{{!}}
{{!}}-
{{!}}dataURL
{{!}}string (URL)
{{!}}URL for GMS REST chat service. If cometD.enabled is set to true, this property will be ignored.
{{!}}n/a
{{!}}Always
{{!}}
{{!}}-
{{!}}enableCustomHeader
{{!}}boolean
{{!}}Enables the use of the custom authorization header defined in _genesys.widgets.main.header static config. Attaches the custom authorization header to all WebChatService request.
{{!}}false
{{!}}No
{{!}}9.0.002.06
{{!}}-
{{!}}userData
{{!}}object
{{!}}Arbitrary attached data to include when initiating a chat.
{{!}}{}
{{!}}n/a
{{!}}
{{!}}-
{{!}}ajaxTimeout
{{!}}number
{{!}}Number of milliseconds to wait before AJAX timeout.
{{!}}3000
{{!}}n/a
{{!}}
{{!}}-
{{!}}xhrFields
{{!}}object
{{!}}Allows you to set the properties for the AJAX xhrFields object (for example, {withCredentials: false}).
{{!}}{withCredentials: false}
{{!}}n/a
{{!}}
{{!}}-
{{!}}pollExceptionLimit
{{!}}number
{{!}}Number of successive poll exceptions (chat server offline) before WebChatService publishes 'chatServerWentOffline'.
{{!}}5
{{!}}n/a
{{!}}
{{!}}-
{{!}}restoreTimeout
{{!}}number
{{!}}Number of milliseconds before restore timeout. Prevents the chat session from restoring after a certain time away from the session (for example, user navigated to a different site during chat and never ended the session).
{{!}}60000
{{!}}
{{!}}
{{!}}}

{{AnchorDiv|v3}}
====Version 3 API====
{{{!}}
{{!}}-
!Name
!Type
!Description
!Default
!Required
!Introduced/Updated
{{!}}-
{{!}}transport
{{!}}object
{{!}}Object containing the transport service configuration options.
{{!}}n/a
{{!}}Yes, when using new transport services available with WebChat.
{{!}}9.0.008.04
{{!}}-
{{!}}transport.type
{{!}}string
{{!}}Select the type of transport service that needs to work with WebChat UI plugin. For Pure Engage v3 REST API, the value is 'pureengage-v3-rest'.
{{!}}n/a
{{!}}Yes, when using Pure Engage v3 REST API.
{{!}}9.0.008.04
{{!}}-
{{!}}transport.dataURL
{{!}}string (URL)
{{!}}URL for Pure Engage v3 REST API chat service. Please contact your local Genesys customer representative to obtain a valid dataURL.
{{!}}n/a
{{!}}Always
{{!}}9.0.008.04
{{!}}-
{{!}}transport.endpoint
{{!}}string
{{!}}The endpoint for Genesys Engage v3 API.
{{!}}n/a
{{!}}Yes
{{!}}9.0.008.04
{{!}}-
{{!}}transport.headers
{{!}}object
{{!}}Object containing key value pairs of any custom headers.
{{!}}n/a
{{!}}Yes
{{!}}9.0.008.04
{{!}}-
{{!}}transport.headers[x-api-key]
{{!}}string
{{!}}The API key provided from Genesys. Please contact your local Genesys customer representative to obtain a valid API key.
{{!}}n/a
{{!}}Yes
{{!}}9.0.008.04
{{!}}-
{{!}}transport.async
{{!}}object
{{!}}Object containing Async mode configuration options.{{NoteFormat|To properly restore a chat session that has ended previously, you'll need to navigate back to the page and open the WebChat Widget. This way, the chat session is restored in the background and is ready. Presently, this is a current limitation in Async WebChat.|}}
{{!}}{}
{{!}}No
{{!}}9.0.008.04
{{!}}-
{{!}}transport.async.enabled
{{!}}boolean
{{!}}Enable Asynchronous Chat where a chat session can be active indefinitely. When you close WebChat without ending the chat session, the session will simply go dormant. When you open WebChat again, the session will restore and continue chatting where left off.
{{!}}false
{{!}}Yes, when Async WebChat mode is enabled
{{!}}9.0.008.04
{{!}}-
{{!}}transport.async.setSessionData
{{!}}function
{{!}}A function that you can define to retrieve updated session data from WebChatService plugin. This function is called back when starting a new Async chat session for the first time or when the sessionData changes over the course of an active chat session. This function takes the following arguments - sessionData (current active session data), Cookie (Widgets Internal cookie reference) and CookieOptions (a parameter that is needed when using Widgets Cookie). The purpose of this function is to provide you the active session data so that it can be stored somewhere safe and secure. Later this needs to be provided in the below setSessionData function to restore the chat session. Refer to the {{Link-SomewhereInThisVersion|manual=SDK|topic=WebChatService-combined|anchor=example|display text=example}} for usage.
{{!}}none
{{!}}Yes, when Async WebChat mode is enabled
{{!}}9.0.008.04
{{!}}-
{{!}}transport.async.getSessionData
{{!}}function
{{!}}A function that you can define to return the session data to WebChatService plugin. During initialization, WebChatService plugin will call this function to check if any session data is returned. If found, WebChatService tries to restore the chat session using this session data and open WebChat Widget. WebChatService will also pass the following arguments into this function - Open (WebChat current open state value), Cookie (Widgets Internal cookie reference) and CookieOptions (a parameter that will be needed when using Widgets Cookie). Refer to the {{Link-SomewhereInThisVersion|manual=SDK|topic=WebChatService-combined|anchor=example|display text=example}} for usage.
{{!}}none
{{!}}Yes, when Async WebChat mode is enabled
{{!}}9.0.008.04
{{!}}-
{{!}}transport.async.deleteSessionData
{{!}}function
{{!}}A function that you can define to delete the session data from your secret storage, it will be called by WebChatService plugin when Async chat session is lost or cannot find anymore due to unknown reasons. This function will enable you write the script for deleting the session data from your secret storage, in this way WebChat will try to start a new chat normally rather than trying to restore a lost chat session. WebChatService will also pass the following arguments into this function - errorData (lost session and error details), Cookie (Widgets Internal cookie reference) and CookieOptions (a parameter that will be needed when using Widgets Cookie).
{{!}}none
{{!}}Yes, when Async WebChat mode is enabled
{{!}}9.0.015.12
{{!}}-
{{!}}userData
{{!}}object
{{!}}Arbitrary attached data to include when initiating a chat.
{{!}}{}
{{!}}n/a
{{!}}
{{!}}-
{{!}}ajaxTimeout
{{!}}number
{{!}}Number of milliseconds to wait before AJAX timeout.
{{!}}3000
{{!}}n/a
{{!}}
{{!}}-
{{!}}}
|Status=No
}}{{Section
|sectionHeading=Localization
|anchor=localize
|alignment=Vertical
|structuredtext=WebChatService doesn't have any localization options.
|Status=No
}}{{Section
|sectionHeading=API commands
|anchor=commands
|alignment=Vertical
|structuredtext=Once you've registered your plugin on the bus, you can call commands on other registered plugins. Here's how to use the global bus object to register a new plugin on the bus.

{{NoteFormat|The global bus object is a debugging tool. When implementing Widgets on your own site, do not use the global bus object to register your custom plugins. Instead, see {{Link-SomewhereInThisVersion|manual=SDK|topic=GWCBusExtensions|display text=Genesys Widgets Extensions}} for more information about extending Genesys Widgets.|1}}

<source lang="javascript">var oMyPlugin = window._genesys.widgets.bus.registerPlugin('MyPlugin');

oMyPlugin.command('WebChatService.getAgents');</source>

{{NoteFormat|Starting with version 9.0.008.04, WebChatService allows you to choose between the types of chat API services available in Genesys via the transport section configuration options. For more information, see the Options table in {{Link-SomewhereInThisVersion|manual=SDK|topic=WebChatService-combined|anchor=options|display text=configuration options}}.|1}}

===configure===

Internal use only. The main App plugin shares configuration settings to widgets using each widget’s <code>configure</code> command. The <code>configure</code> command can only be called once at startup. Calling <code>configure</code> again after startup may result in unpredictable behavior.

===startChat===

Initiates a new chat session with the chat server via GES or with the service configured under the transport section.

====Example====
<source lang="javascript">
oMyPlugin.command('WebChatService.startChat', {

nickname: 'Jonny',
firstname: 'Johnathan',
lastname: 'Smith',
email: 'jon.smith@mail.com',
subject: 'product questions',
userData: {}

}).done(function(e){

// WebChatService started a chat successfully

}).fail(function(e){

// WebChatService failed to start chat
});
</source>

====Options====

{{{!}}
{{!}}-
!Option
!Type
!Description
{{!}}-
{{!}}nickname
{{!}}string
{{!}}Chat Entry Form Data: 'nickname'.
{{!}}-
{{!}}firstname
{{!}}string
{{!}}Chat Entry Form Data: 'firstname'.
{{!}}-
{{!}}lastname
{{!}}string
{{!}}Chat Entry Form Data: 'lastname'.
{{!}}-
{{!}}email
{{!}}string
{{!}}Chat Entry Form Data: 'email'.
{{!}}-
{{!}}subject
{{!}}string
{{!}}Chat Entry Form Data: 'subject'.
{{!}}-
{{!}}userData
{{!}}object
{{!}}Arbitrary data to attach to the chat session (AKA attachedData). Properties defined here will be merged with default userData set in the configuration object.
{{!}}-
{{!}}}

====Resolutions====

{{{!}}
{{!}}-
!Status
!When
!Returns
{{!}}-
{{!}}resolved
{{!}}Server confirms session started
{{!}}(AJAX Response Object)
{{!}}-
{{!}}rejected
{{!}}A chat session is already active
{{!}}'There is already an active chat session'
{{!}}-
{{!}}rejected
{{!}}AJAX exception occurs
{{!}}(AJAX Response Object)
{{!}}-
{{!}}rejected
{{!}}Server exception occurs
{{!}}(AJAX Response Object)
{{!}}-
{{!}}rejected
{{!}}userData is invalid
{{!}}'malformed data object provided in userData property'
{{!}}-
{{!}}}

===endChat===

Ends the chat session with the chat server via GES or with the service configured under transport section.

====Example====
<source lang="javascript">
oMyPlugin.command('WebChatService.endChat').done(function(e){

// WebChatService ended a chat successfully

}).fail(function(e){

// WebChatService failed to end chat
});
</source>

====Resolutions====

{{{!}}
{{!}}-
!Status
!When
!Returns
{{!}}-
{{!}}resolved
{{!}}Active session is ended successfully
{{!}}(AJAX Response Object)
{{!}}-
{{!}}rejected
{{!}}No chat session is currently active
{{!}}'There is no active chat session'
{{!}}-
{{!}}}

===sendMessage===

Sends a message from the client to the chat session.

====Example====
<source lang="javascript">
oMyPlugin.command('WebChatService.sendMessage', {message: 'hi'}).done(function(e){

// WebChatService sent a message successfully

}).fail(function(e){

// WebChatService failed to send a message
});
</source>

====Options====
{{{!}}
{{!}}-
!Option
!Type
!Description
{{!}}-
{{!}}message
{{!}}string
{{!}}The message you want to send
{{!}}-
{{!}}}

====Resolutions====

{{{!}}
{{!}}-
!Status
!When
!Returns
{{!}}-
{{!}}resolved
{{!}}Message is successfully sent
{{!}}(AJAX Response Object)
{{!}}-
{{!}}rejected
{{!}}No message text provided
{{!}}'No message text provided'
{{!}}-
{{!}}rejected
{{!}}No chat session is currently active
{{!}}'There is no active chat session'
{{!}}-
{{!}}rejected
{{!}}AJAX exception occurs
{{!}}(AJAX Response Object)
{{!}}-
{{!}}}

===sendCustomNotice===

Sends a custom notice from the client to the chat server. This request is used to deliver any custom notification between a custom client application and a custom agent desktop. Neither Genesys Widgets, nor Workspace, uses this out of the box.

====Example====

<source lang="javascript">
oMyPlugin.command('WebChatService.sendCustomNotice', {message: 'bye'}).done(function(e){

// WebChatService sent a custom message successfully

}).fail(function(e){

// WebChatService failed to send a custom message
});
</source>

====Options====

{{{!}}
{{!}}-
!Option
!Type
!Description
{{!}}-
{{!}}message
{{!}}string
{{!}}A message you want to send along with the custom notice
{{!}}-
{{!}}}

====Resolutions====
{{{!}}
{{!}}-
!Status
!When
!Returns
!Introduced/Updated
{{!}}-
{{!}}resolved
{{!}}Message is successfully sent
{{!}}(AJAX Response Object)
{{!}}
{{!}}-
{{!}}rejected
{{!}}AJAX exception occurs
{{!}}(AJAX Response Object)
{{!}}
{{!}}-
{{!}}rejected
{{!}}The server doesn't support receiving custom notices
{{!}}This transport doesn't support sendCustomNotice command.
{{!}}9.0.008.04
{{!}}-
{{!}}}

===sendTyping===

Sends a "''Customer typing''" notification to the chat session. A visual indication will be shown to the agent.

====Example====

<source lang="javascript">
oMyPlugin.command('WebChatService.sendTyping').done(function(e){

// WebChatService sent typing successfully

}).fail(function(e){

// WebChatService failed to send typing
});
</source>

====Options====

{{{!}}
{{!}}-
!Option
!Type
!Description
{{!}}-
{{!}}Message
{{!}}String
{{!}}The message you want to send along with the typing notification
{{!}}-
{{!}}}

====Resolutions====

{{{!}}
{{!}}-
!Status
!When
!Returns
{{!}}-
{{!}}resolved
{{!}}AJAX request is successful
{{!}}(AJAX Response Object)
{{!}}-
{{!}}rejected
{{!}}AJAX exception occurs
{{!}}(AJAX Response Object)
{{!}}-
{{!}}rejected
{{!}}No chat session is currently active
{{!}}'There is no active chat session'
{{!}}-
{{!}}}

{{AnchorDiv|sfm}}
===sendFilteredMessage===

Sends a message along with a regular expression to match the message and hide it from the client. Useful for sending codes and tokens through the WebChat interface to the Agent Desktop.

{{NoteFormat|Filters are now automatically stored and recalled on chat restore for the duration of the session.}}

====Example====

<source lang="javascript">
oMyPlugin.command('WebChatService.sendFilteredMessage', {

message: 'filtered message',
regex: /[a-zA-Z]/

}).done(function(e){

// WebChatService sent filtered message successfully

}).fail(function(e){

// WebChatService failed to send filtered message
});
</source>

====Options====

{{{!}}
{{!}}-
!Option
!Type
!Description
{{!}}-
{{!}}message
{{!}}string
{{!}}Message you want to send but don't want to appear in the transcript
{{!}}-
{{!}}regex
{{!}}RegExp
{{!}}Regular expression to match the message
{{!}}-
{{!}}}

====Resolutions====
{{{!}}
{{!}}-
!Status
!When
!Returns
{{!}}-
{{!}}resolved
{{!}}There is an active session
{{!}}n/a
{{!}}-
{{!}}rejected
{{!}}No chat session is currently active
{{!}}'No active chat session'
{{!}}-
{{!}}}

{{AnchorDiv|ap}}
===addPrefilter===

Adds a new pre-filter regular expression to the pre-filter list. Any messages matched using the pre-filters will not be shown in the transcript

{{NoteFormat|Filters are now automatically stored and recalled on chat restore for the duration of the session.}}

====Example====

<source lang="javascript">
oMyPlugin.command('WebChatService.addPrefilter', {filters: /[a-zA-Z]/}).done(function(e){

// WebChatService added filter successfully
// e == Object of registered prefilters

}).fail(function(e){

// WebChatService failed to add filter
});
</source>

====Options====

{{{!}}
{{!}}-
!Option
!Type
!Description
{{!}}-
{{!}}filters
{{!}}RegExp or Array of RegExp
{{!}}Regular Expression(s) to add to the prefilter list
{{!}}-
{{!}}}

====Resolutions====
{{{!}}
{{!}}-
!Status
!When
!Returns
{{!}}-
{{!}}resolved
{{!}}Valid filters are provided
{{!}}Array of all registered prefilters.
{{!}}-
{{!}}rejected
{{!}}Invalid or missing filters provided
{{!}}'Missing or invalid filters provided. Please provide a regular expression or an array of regular expressions.'
{{!}}-
{{!}}}

===updateUserData===

Updates the userData properties associated with the chat session. If this command is called before a chat session starts, it will update the internal userData object and will be sent when a chat session starts. If this command is called after a chat session starts, a request to the server will be made to update the userData on the server associated with the chat session.

====Example====

<source lang="javascript">
oMyPlugin.command('WebChatService.updateUserData', {firstname: 'Joe'}).done(function(e){

// WebChatService updated user data successfully

}).fail(function(e){

// WebChatService failed to update user data
});
</source>

====Options====

{{{!}}
{{!}}-
!Option
!Type
!Description
{{!}}-
{{!}}n/a
{{!}}object
{{!}}userData object you want to send to the server for this active session
{{!}}-
{{!}}}

====Resolutions====

{{{!}}
{{!}}-
!Status
!When
!Returns
!Introduced/Updated
{{!}}-
{{!}}resolved
{{!}}Session is active and userData is successfully sent
{{!}}(AJAX Response Object)
{{!}}
{{!}}-
{{!}}rejected
{{!}}Session is active and AJAX exception occurs
{{!}}(AJAX Response Object)
{{!}}
{{!}}-
{{!}}resolved
{{!}}Session is not active and internal userData object is merged with new userData properties provided
{{!}}The internal userData object that will be sent to the server
{{!}}
{{!}}-
{{!}}rejected
{{!}}Session is active and the server doesn't support updating userData
{{!}}This transport doesn't support updating userData during an active chat session.
{{!}}9.0.008.04
{{!}}-
{{!}}}

===poll===

Internal use only. Starts polling for new messages.

====Example====

<source lang="javascript">
oMyPlugin.command('WebChatService.poll').done(function(e){

// WebChatService started polling successfully

}).fail(function(e){

// WebChatService failed to start polling
});
</source>

====Resolutions====

{{{!}}
{{!}}-
!Status
!When
!Returns
!Introduced/Updated
{{!}}-
{{!}}resolved
{{!}}There is an active session
{{!}}n/a
{{!}}
{{!}}-
{{!}}rejected
{{!}}WebChatService isn't calling this command
{{!}}'Access Denied to private command. Only WebChatService is allowed to invoke this command.'
{{!}}
{{!}}-
{{!}}rejected
{{!}}No chat session is currently active
{{!}}'previous poll has not finished.'
{{!}}
{{!}}-
{{!}}rejected
{{!}}The server doesn't support polling
{{!}}'This transport doesn't support polling.'
{{!}}9.0.008.04
{{!}}-
{{!}}}

===startPoll===

Starts automatic polling for new messages.

====Example====

<source lang="javascript">
oMyPlugin.command('WebChatService.startPoll').done(function(e){

// WebChatService started polling successfully

}).fail(function(e){

// WebChatService failed to start polling
});
</source>

====Resolutions====

{{{!}}
{{!}}-
!Status
!When
!Returns
!Introduced / Updated
{{!}}-
{{!}}resolved
{{!}}There is an active session
{{!}}n/a
{{!}}
{{!}}-
{{!}}rejected
{{!}}No chat session is currently active
{{!}}No active chat session
{{!}}
{{!}}-
{{!}}rejected
{{!}}The server doesn't support polling
{{!}}This transport doesn't support polling
{{!}}9.0.008.04
{{!}}-
{{!}}}

===stopPoll===

Stops automatic polling for new messages.

====Example====

<source lang="javascript">
oMyPlugin.command('WebChatService.stopPoll').done(function(e){

// WebChatService stopped polling successfully

}).fail(function(e){

// WebChatService failed to stop polling
});
</source>

====Resolutions====

{{{!}}
{{!}}-
!Status
!When
!Returns
!Introduced / Updated
{{!}}-
{{!}}resolved
{{!}}There is an active session
{{!}}n/a
{{!}}
{{!}}-
{{!}}rejected
{{!}}No chat session is currently active
{{!}}No active chat session
{{!}}
{{!}}-
{{!}}rejected
{{!}}The server doesn't support polling
{{!}}This transport doesn't support polling
{{!}}9.0.008.04
{{!}}-
{{!}}}

===resetPollExceptions===

Resets the poll exception count to 0. pollExceptionLimit is set in the configuration.

====Example====

<source lang="javascript">
oMyPlugin.command('WebChatService.resetPollExceptions').done(function(e){

// WebChatService reset polling successfully

}).fail(function(e){

// WebChatService failed to reset polling
});
</source>

====Resolutions====

{{{!}}
{{!}}-
!Status
!When
!Returns
!Introduced / Updated
{{!}}-
{{!}}resolved
{{!}}Always
{{!}}n/a
{{!}}
{{!}}-
{{!}}rejected
{{!}}The server doesn't support polling
{{!}}This transport doesn't support resetPollExceptions command.
{{!}}9.0.008.04
{{!}}-
{{!}}}

===restore===

Internal use only. You should not invoke this manually unless you are using Async mode.

====Example====

<source lang="javascript">
oMyPlugin.command('WebChatService.restore').done(function(e){

// WebChatService restored successfully

}).fail(function(e){

// WebChatService failed to restore
});
</source>

====Options====

{{{!}}
{{!}}-
!Option
!Type
!Description
!Accepted Values
!Introduced / Updated
{{!}}-
{{!}}sessionData
{{!}}string
{{!}}The session data that is needed to restore the WebChat in Async mode. It is a JWT token string value. Applicable only when using WebChat with Genesys Engage v3 API. For more information, see the “Genesys Engage v3” tab in the “Options” table in {{Link-SomewhereInThisVersion|manual=SDK|topic=WebChatService-combined|anchor=options|display text=configuration options}}.
{{!}}(JWT string token)
{{!}}9.0.008.04
{{!}}-
{{!}}}

====Resolutions====

{{{!}}
{{!}}-
!Status
!When
!Returns
!Introduced / Updated
{{!}}-
{{!}}resolved
{{!}}Session has been found
{{!}}n/a
{{!}}
{{!}}-
{{!}}rejected
{{!}}Session cannot be found
{{!}}n/a
{{!}}
{{!}}-
{{!}}rejected
{{!}}Restoring chat session is in progress
{{!}}Already restoring. Ignoring request.
{{!}}9.0.002.06
{{!}}-
{{!}}rejected
{{!}}Chat session is already active
{{!}}Chat session is already active, ignoring restore command.
{{!}}9.0.002.06
{{!}}-
{{!}}rejected
{{!}}Trying restore chat session manually
{{!}}Access Denied to private command. Only WebChatService is allowed to invoke this command in Non-Async mode.
{{!}}9.0.002.06
{{!}}-
{{!}}}

===getTranscript===

Fetches an array of all messages in the chat session.

{{NoteFormat|1=For more information on the fields included in JSON response, see {{#Widget:ExtLink|link=https://docs.genesys.com/Documentation/GMS/latest/API/APIResponses#Digital_Channels_Chat_V2_Response_Format|displaytext=Digital Channels Chat V2 Response Format}}.|2=}}

====Example====

<source lang="javascript">
oMyPlugin.command('WebChatService.getTranscript').done(function(e){

// WebChatService got transcript successfully
// e == Object with an array of messages

}).fail(function(e){

// WebChatService failed to get transcript
});
</source>

====Resolutions====

{{{!}}
{{!}}-
!Status
!When
!Returns
{{!}}-
{{!}}resolved
{{!}}Always
{{!}}Object with an array of messages
{{!}}-
{{!}}}

===getAgents===

Return a list of agents currently participating in the chat. Includes agent metadata.

====Example====

<source lang="javascript">
oMyPlugin.command('WebChatService.getAgents').done(function(e){

// WebChatService got agents successfully
// e == Object with agents information in chat

}).fail(function(e){

// WebChatService failed to get agents
});
</source>

====Resolutions====

{{{!}}
{{!}}-
!Status
!When
!Returns
{{!}}-
{{!}}resolved
{{!}}Always
{{!}}(Object List) {name: (String), connected: (Boolean), supervisor: (Boolean), connectedTime: (int time),disconnectedTime: (int time)}
{{!}}-
{{!}}}

===getStats===

Returns stats on chat session including start time, end time, duration, and list of agents.

====Example====

<source lang="javascript">
oMyPlugin.command('WebChatService.getStats').done(function(e){

// WebChatService got stats successfully
// e == Object with chat session stats

}).fail(function(e){

// WebChatService failed to get stats
});
</source>

====Resolutions====

{{{!}}
{{!}}-
!Status
!When
!Returns
{{!}}-
{{!}}resolved
{{!}}Always
{{!}}{agents: (Object), startTime: (int time), endTime: (int time), duration: (int time)}
{{!}}-
{{!}}}

===sendFile===

'''[Introduced: 9.0.008.04]'''

Sends the file from the client machine to the agent.

====Example====

<source lang="javascript">
oMyPlugin.command('WebChatService.sendFile', {files: $('<input/>').attr('type', 'file') /* Only works on UI, can not dynamically change */ }).done(function(e){

// WebChatService sent file successfully

}).fail(function(e){

// WebChatService failed to send file
});
</source>

====Options====

{{{!}}
{{!}}-
!Option
!Type
!Description
{{!}}-
{{!}}files
{{!}}File
{{!}}A reference to a file input element (for example <input type=“file”/>)
{{!}}-
{{!}}}

====Resolutions====

{{{!}}
{{!}}-
!Status
!When
!Returns
{{!}}-
{{!}}resolved
{{!}}The file sent is a valid type and size
{{!}}(AJAX Response Object)
{{!}}-
{{!}}rejected
{{!}}The file sent is an invalid type
{{!}}(AJAX Response Object)
{{!}}-
{{!}}rejected
{{!}}The number of uploads is exceeded
{{!}}(AJAX Response Object)
{{!}}-
{{!}}rejected
{{!}}The file size exceeds the limit
{{!}}(AJAX Response Object)
{{!}}-
{{!}}rejected
{{!}}The file size is too large or an unknown error occurs
{{!}}(AJAX Response Object)
{{!}}-
{{!}}rejected
{{!}}The server doesn't support file uploads
{{!}}This transport doesn't support file uploads
{{!}}-
{{!}}}

===downloadFile===

====Downloads the file to the client machine. Example====
<source lang="javascript">
oMyPlugin.command('WebChatService.downloadFile', {fileId: '1', fileName: 'myfile.txt'}).done(function(e){

// WebChatService sent file successfully

}).fail(function(e){

// WebChatService failed to send file
});
</source>

====Options====
{{{!}}
{{!}}-
!Option
!Type
!Description
{{!}}-
{{!}}field
{{!}}string
{{!}}This is the id of the file to be downloaded from the session
{{!}}-
{{!}}}

====Resolutions====

{{{!}}
{{!}}-
!Status
!When
!Returns
{{!}}-
{{!}}resolved
{{!}}The file is downloaded successfully
{{!}}n/a
{{!}}-
{{!}}}

===getSessionData===

'''[Introduced: 9.0.002.06]'''

Retrieves the active session data at any time.

====Example====

<source lang="javascript">
oMyPlugin.command('WebChatService.getSessionData')
</source>

====Resolutions====

{{{!}}
{{!}}-
!Status
!When
!Returns
!Introduced / Updated
{{!}}-
{{!}}resolved
{{!}}Always, when using Chat via GMS API. For more information, see the 'GMS' tab in the 'Options' table in {{Link-SomewhereInThisVersion|manual=SDK|topic=WebChatService-combined|anchor=options|display text=configuration options}}.
{{!}}{secureKey: (string), sessionID: (number/string), alias: (number/string), userId: (number/string)}
{{!}}
{{!}}-
{{!}}resolved
{{!}}Always, when using Chat via Genesys Engage v3 API. For more information, see the 'Genesys Engage v3' tab in the 'Options' table in {{Link-SomewhereInThisVersion|manual=SDK|topic=WebChatService-combined|anchor=options|display text=configuration options}}.
{{!}}{participantId: (string), sessionId: {string), token: (string), transportId: (string)}
{{!}}9.0.008.04
{{!}}-
{{!}}rejected
{{!}}Never
{{!}}undefined
{{!}}
{{!}}-
{{!}}}

===fetchHistory===

'''[Introduced: 9.0.008.04]'''

This applies only in Asynchronous mode to fetch older chat messages. It does not fetch all of the messages at once; rather a certain number of messages are fetched every time this command is called. Response data will be available in the {{Link-SomewhereInThisVersion|manual=SDK|topic=WebChatService-combined|anchor=events|display text=messageReceived}} event.

====Example====

<source lang="javascript">
oMyPlugin.command('WebChatService.fetchHistory')
</source>

====Resolutions====

{{{!}}
{{!}}-
!Status
!When
!Returns
{{!}}-
{{!}}resolved
{{!}}Old messages are retrieved
{{!}}(AJAX Response Object)
{{!}}-
{{!}}rejected
{{!}}Request fails
{{!}}(AJAX Response Object)
{{!}}-
{{!}}rejected
{{!}}Asynchronous mode is not enabled
{{!}}Fetching history messages applies only to Asynchronous chat
{{!}}-
{{!}}rejected
{{!}}All messages are received
{{!}}No more messages to fetch
{{!}}-
{{!}}}

===registerTypingPreviewInput===

Selects an HTML input to watch for key events. Used to trigger startTyping and stopTyping automatically.

====Example====

<source lang="javascript">
oMyPlugin.command('WebChatService.registerTypingPreviewInput', {input: $('input') }).done(function(e){

// WebChatService registered input area successfully

}).fail(function(e){

// WebChatService failed to register typing preview
});
</source>

====Options====

{{{!}}
{{!}}-
!Option
!Type
!Description
{{!}}-
{{!}}input
{{!}}HTML Reference
{{!}}An HTML reference to a text or textarea input
{{!}}-
{{!}}}

====Resolutions====

{{{!}}
{{!}}-
!Status
!When
!Returns
{{!}}-
{{!}}resolved
{{!}}Valid HTML input reference is provided
{{!}}n/a
{{!}}-
{{!}}rejected
{{!}}Invalid or missing HTML input reference
{{!}}'Invalid value provided for the 'input' property. An HTML element reference to a textarea or text input is required.'
{{!}}-
{{!}}}

===registerPreProcessor===

Registers a function that receives the message object, allowing you to manipulate the values before it is rendered in the transcript.

====Example====
<syntaxhighlight lang="javascript">
oMyPlugin.command('WebChatService.registerPreProcessor', {preprocessor: function(message){
message.text = message.text + ' some preprocessing text';
return message;
} }).done(function(e){
// WebChatService registered preprocessor function
// e == function that was registered
}).fail(function(e){
// WebChatService failed to register function
});
</syntaxhighlight><br />

====Options====
{{{!}} class="wikitable"
!Option
!Type
!Description
{{!}}-
{{!}}preprocessor
{{!}}function
{{!}}The preprocessor function you want to register.
{{!}}}

====Resolutions====
{{{!}} class="wikitable"
!Status
!When
!Returns
{{!}}-
{{!}}resolved
{{!}}A valid preprocessor function is provided and is registered
{{!}}The registered preprocessor function.
{{!}}-
{{!}}rejected
{{!}}An invalid preprocessor function is provided
{{!}}No preprocessor function provided. Type provided was '<DATATYPE>'.<br />
{{!}}}
<br />
|Status=No
}}{{Section
|sectionHeading=API events
|anchor=events
|alignment=Vertical
|structuredtext=Once you've registered your plugin on the bus, you can subscribe to and listen for published events. Here's how to use the global bus object to register a new plugin on the bus.

{{NoteFormat|The global bus object is a debugging tool. When implementing Widgets on your own site, do not use the global bus object to register your custom plugins. Instead, see {{Link-SomewhereInThisVersion|manual=SDK|topic=GWCBusExtensions|display text=Genesys Widgets Extensions}} for more information about extending Genesys Widgets.|1}}

<source lang="javascript">var oMyPlugin = window._genesys.widgets.bus.registerPlugin('MyPlugin');

oMyPlugin.subscribe('WebChatService.ready', function(e){});</source>

{{{!}} class="wikitable"
!Name
!Description
!Data
!Introduced/updated
{{!}}-
{{!}}ready
{{!}}WebChatService is initialized and ready to accept commands.
{{!}}n/a
{{!}}
{{!}}-
{{!}}restored
{{!}}Chat session has been restored after page navigation or refresh. In Asynchronous mode, this event includes data indicating whether a chat session has been restored in Async mode or not.
{{!}}{async: (boolean)}
{{!}}9.0.002.06
{{!}}-
{{!}}restoreTimeout
{{!}}Chat session restoration attempted was denied after user navigated away from originating website for longer than the time limit: default 60 seconds.
{{!}}n/a
{{!}}
{{!}}-
{{!}}restoreFailed
{{!}}Could not restore chat session after page navigation or refresh.
{{!}}n/a
{{!}}
{{!}}-
{{!}}restoredOffline
{{!}}Chat session was restored normally but chat server is offline. This means no messages can come through. When chat server is comes back online, 'chatServerBackOnline' is published.
{{!}}n/a
{{!}}
{{!}}-
{{!}}messageReceived
{{!}}A new message has been received from the server. Includes text messages, status messages, notices, and other message types.
{{!}}{originalMessages: (object), messages: (array of objects), restoring: (boolean), sessionData: (object)}
{{!}}9.0.002.06
{{!}}-
{{!}}error
{{!}}An error occurred between the client and the server.
{{!}}(AJAX Response)
{{!}}
{{!}}-
{{!}}started
{{!}}Chat session has successfully started.
{{!}}(AJAX Response containing session data)
{{!}}
{{!}}-
{{!}}ended
{{!}}Chat session has successfully ended.
{{!}}n/a
{{!}}
{{!}}-
{{!}}agentTypingStarted
{{!}}Agents has started typing a new message.
{{!}}(AJAX Response)
{{!}}
{{!}}-
{{!}}agentTypingStopped
{{!}}Agent has stopped typing.
{{!}}(AJAX Response)
{{!}}
{{!}}-
{{!}}pollingStarted
{{!}}Chat server automatic polling has started.
{{!}}n/a
{{!}}
{{!}}-
{{!}}pollingStopped
{{!}}Chat server automatic polling has stopped.
{{!}}n/a
{{!}}
{{!}}-
{{!}}clientConnected
{{!}}Indicates the user has been connected to the chat session.
{{!}}{message: (object), agents: (object), numAgentsConnected: (number)}
{{!}}
{{!}}-
{{!}}clientDisconnected
{{!}}Indicates the user has been disconnected form the chat session.
{{!}}{message: (object), agents: (object), numAgentsConnected: (number)}
{{!}}
{{!}}-
{{!}}agentConnected
{{!}}Indicates an agent has connected to the chat.
{{!}}{message: (object), agents: (object), numAgentsConnected: (number)}
{{!}}
{{!}}-
{{!}}agentDisconnected
{{!}}Indicates an agent has disconnected from the chat.
{{!}}{message: (object), agents: (object), numAgentsConnected: (number)}
{{!}}
{{!}}-
{{!}}supervisorConnected
{{!}}Indicates a supervisor has connected to the chat.
{{!}}{message: (object), agents: (object), numAgentsConnected: (number)}
{{!}}
{{!}}-
{{!}}supervisorDisconnected
{{!}}Indicates a supervisor has disconnected from the chat.
{{!}}{message: (object), agents: (object), numAgentsConnected: (number)}
{{!}}
{{!}}-
{{!}}botConnected
{{!}}Indicates a bot has connected to the chat.
{{NoteFormat|This event is applicable only when using {{Link-SomewhereInThisVersion|manual=SDK|topic=WebChatService-combined|anchor=v2|display text=v2 API}}.|}}
{{!}}{message: (object), agents: (object), numAgentsConnected: (number)}
{{!}}9.0.014.13
{{!}}-
{{!}}botDisconnected
{{!}}Indicates a bot has disconnected from the chat.
{{NoteFormat|This event is applicable only when using {{Link-SomewhereInThisVersion|manual=SDK|topic=WebChatService-combined|anchor=v2|display text=v2 API}}.|}}
{{!}}{message: (object), agents: (object), numAgentsConnected: (number)}
{{!}}9.0.014.13
{{!}}-
{{!}}clientTypingStarted
{{!}}The user has started typing. Sends an event to the agent.
{{!}}n/a
{{!}}
{{!}}-
{{!}}clientTypingStopped
{{!}}After a user stops typing, a countdown begins. When the countdown completes, the typing notification will clear for the agent.
{{!}}n/a
{{!}}
{{!}}-
{{!}}disconnected
{{!}}Cannot reach servers. No connection. Either the user is offline or the server is offline.
{{!}}n/a
{{!}}
{{!}}-
{{!}}reconnected
{{!}}Connection restored. This event is only published after 'disconnected'.
{{!}}n/a
{{!}}
{{!}}-
{{!}}chatServerWentOffline
{{!}}Chat server has gone offline but chat session has not ended. New messages are temporarily unavailable. This event is published only after the configuration option 'pollExceptionLimit' has been exceeded. Default limit is 5 poll exceptions. 'restoredOffline' is an alternate to this event that is used only when the chat server is down while trying to restore your chat session. The reason for having two events is to allow for separate handling of both scenarios. {{NoteFormat|This event is applicable only when using {{Link-SomewhereInThisVersion|manual=SDK|topic=WebChatService-combined|anchor=v2|display text=v2 API}}.|}}
{{!}}n/a
{{!}}
{{!}}-
{{!}}chatServerBackOnline
{{!}}Chat server had come back online after going offline. This will only be published after 'chatServerWentOffline'.
{{NoteFormat|This event is applicable only when using {{Link-SomewhereInThisVersion|manual=SDK|topic=WebChatService-combined|anchor=v2|display text=v2 API}}.|}}
{{!}}n/a
{{!}}
{{!}}-
{{!}}connectionPending
{{!}}If there is a connection problem and WebChatService is trying to reconnect, this event will be published. Published before 'chatServerWentOffline'.
{{NoteFormat|This event is applicable only when using {{Link-SomewhereInThisVersion|manual=SDK|topic=WebChatService-combined|anchor=v2|display text=v2 API}}.|}}
{{!}}n/a
{{!}}
{{!}}-
{{!}}connectionRestored
{{!}}Is published when the connection has be reestablished. Publishes at the same time as 'chatServerBackOnline'.
{{!}}n/a
{{!}}
{{!}}-
{{!}}}
|Status=No
}}
}}

WID/Current/Developer/GWCCookies

2020-10-29T15:40:03Z

Chrissyforrest: Published

{{Article
|Standalone=No
|DisplayName=Cookies
|TocName=Cookies
|Context=Learn which session cookies are used by Genesys Widgets to restore chat sessions, track the state of the UI, store a customer's decisions, and more.
|ComingSoon=No
|Platform=GenesysEngage-cloud
|Role=Administrator, Developer
|Section={{Section
|sectionHeading=Overview
|anchor=Overview
|alignment=Vertical
|structuredtext====Purpose===
Genesys Widgets uses cookies to store non-sensitive data in the browser. The end-user's browser must allow cookies for Genesys Widgets to operate properly. Each cookie is required, and without the ability to read and write these cookies, Genesys Widgets features will not function properly.

===Cookie creation===
All cookies start with the prefix "'''_genesys.widgets'''" to easily identify them. By default, Genesys Widgets cookies are created in a way that allows the cookies to be read across sub-domains by setting the "domain" attribute in the cookie options. We derive the proper domain value by parsing the host site's domain and extracting it.{{NoteFormat|Genesys Widgets never stores Personally Identifiable Information (PII) in its cookies.|}}

===Duration===
All cookies used by Genesys Widgets are created as session cookies and will be deleted when the user's browser is fully closed.
===Sub-domains===
Normally, cookies cannot be transferred between sub-domains of a website unless they are configured to do so. Genesys Widgets automatically detects the domain of the host site and configures all cookies to be transferable between sub-domains. For example, you could start a chat on '''www.testsite.com''' and restore that chat session on '''store.testsite.com''', '''support.testsite.com''', or '''portal.testsite.com'''.
===Cookie support in test environments===
Genesys Widgets uses special cookies that persist across sub-domains. This is a critical feature for plugins like WebChat that need to restore an active chat session while navigating around a website. The side effect of using this type of cookie is they won't work when using test environment domain names such as "localhost" or an IP address. You must use a fully-qualified domain name (FQDN) such as "localhost.com" or any other variant that can be identified as a domain name. Cookies will also fail to work if you run the test site as an HTML file path directly in the browser.

One workaround is to update your system's '''hosts''' file to create an FQDN alias for "localhost", your test environment's name, or an IP address.

'''Example'''
127.0.0.1 localhost
127.0.0.1 localhost.com
A fully-qualified domain name (FQDN) such as "localhost.com" or any other variant that can be identified as a domain name is not mandatory, but it is recommended. This way, the cookies will also work when using test environment domain names such as "localhost" or an IP address.

The following is a list of cookies used by Genesys Widgets.
|Status=No
}}{{Section
|sectionHeading=App
|alignment=Vertical
|structuredtext=<br />
{{{!}} class="wikitable"
!Cookie Name
!Purpose
{{!}}-
{{!}}_genesys.widgets.app.autoLoadList
{{!}}Contains a list of active plugin names that are updated based on the usage of widgets during the {{Link-SomewhereInThisVersion|manual=Developer|topic=GWCDeployment|anchor=DeployingGenesysWidgetslazyloading|display text=lazy loading}} deployment method. This is to ensure that a widget is auto-loaded during a page refresh or page navigation when there is an active session associated with it.
{{!}}}
|Status=No
}}{{Section
|sectionHeading=Console
|alignment=Vertical
|structuredtext=<br />
{{{!}} class="wikitable"
!Cookie Name
!Purpose
{{!}}-
{{!}}_genesys.widgets.console.session
{{!}}Contains the active Console plugin open/close state.
{{!}}-
{{!}}_genesys.widgets.console.commandPlugin
{{!}}Contains the selected plugin name from the Commands section.
{{!}}-
{{!}}_genesys.widgets.console.command
{{!}}Contains the selected command to run from the Commands section.
{{!}}-
{{!}}_genesys.widgets.console.eventPlugin
{{!}}Contains the selected plugin from the Events section to listen for events.
{{!}}-
{{!}}_genesys.widgets.console.event
{{!}}Contains the selected event type to listen against, from the Events section.
{{!}}-
{{!}}_genesys.widgets.console.optionsArea
{{!}}Contains the command options to send when executing a command.
{{!}}-
{{!}}_genesys.widgets.console.activeSubscriptions
{{!}}Contains the list of all active event subscriptions listening via the Console plugin.
{{!}}-
{{!}}_genesys.widgets.console.windowPosition
{{!}}Contains the position of the Console plugin on the screen.
{{!}}}
|Status=No
}}{{Section
|sectionHeading=WebChat
|alignment=Vertical
|structuredtext=<br />
{{{!}} class="wikitable"
!Cookie Name
!Purpose
{{!}}-
{{!}}_genesys.widgets.webchat.state.open
{{!}}Contains the WebChat Widget open or close state for internal tracking purposes.
{{!}}-
{{!}}_genesys.widgets.webchat.state.keys
{{!}}Can contain encrypted keys related to the current active chat session.
{{!}}-
{{!}}_genesys.widgets.webchat.state.ping
{{!}}Contains the time at which the last successful request was made to the server.
{{!}}-
{{!}}_genesys.widgets.webchat.metaData
{{!}}Contains all the {{Link-SomewhereInThisVersion|manual=SDK|topic=WebChat-combined#metadata|display text=Metadata}} details related to the current active chat session.
{{!}}-
{{!}}_genesys.widgets.webchat.state.index
{{!}}Contains the last unique Message ID for internal tracking purposes.
{{!}}-
{{!}}_genesys.widgets.webchat.state.filters
{{!}}Contains any prefilters that were added using WebChatService plugin commands {{Link-SomewhereInThisVersion|manual=SDK|topic=WebChatService-combined#ap|display text=addPrefilter}} or {{Link-SomewhereInThisVersion|manual=SDK|topic=WebChatService-combined#sfm|display text=sendFilteredMessage}}.
{{!}}-
{{!}}_genesys.widgets.webchat.state.session
{{!}}Contains the unique Session ID related to the current active chat session. It is used to restore the active chat session during scenarios like page refresh or page navigation.
{{!}}-
{{!}}_genesys.widgets.webchat.state.minimized
{{!}}Contains the WebChat Widget minimized or maximized state for internal tracking purposes.
{{!}}-
{{!}}_genesys.widgets.webchat.autoInvite.disabled
{{!}}Contains a value that disables or enables the WebChat autoInvite feature. It is dynamically updated based on the user's response to the initial WebChat invite.
{{!}}-
{{!}}_genesys.widgets.webchat.state.unreadMessages
{{!}}Tracks the number of unread messages during an active chat session, when WebChat is minimized. It is cleared whenever the WebChat Widget is maximized by the user to read the new messages.
{{!}}-
{{!}}_genesys.widgets.webchat.state.lastMessageCountRead
{{!}}Contains the number of messages that are read during an active chat session that calculates the number of unread messages when WebChat is minimized. It is automatically cleared whenever the WebChat Widget is maximized or closed/ended.
{{!}}-
{{!}}_genesys.widgets.webchat.state.asyncUnreadMessageCount
{{!}}Keeps track of the number of unread messages related to an Async Chat, when WebChat is minimized. It is cleared whenever the WebChat Widget is maximized by the user to read the new messages.
{{!}}-
{{!}}_genesys.widgets.webchat.state.pureengage-v3-rest.session
{{!}}Used only with Genesys Engage V3 API. It contains the Session ID related to the current active chat session. It is used to restore the active chat session during scenarios like page refresh or page navigation.
{{!}}-
{{!}}_genesys.widgets.webchat.state.pureengage-v3-rest.keys
{{!}}Used only with Genesys Engage V3 API, containing the encrypted keys related to the current active chat session.
{{!}}-
{{!}}_genesys.widgets.webchat.state.pureengage-v3-rest.index
{{!}}Used only with Genesys Engage V3 API, containing the last unique message ID for internal tracking purposes.
{{!}}-
{{!}}_genesys.widgets.webchat.state.pureengage-v3-rest.open
{{!}}Used only with Genesys Engage V3 API, containing the WebChat Widget open or close state for internal tracking purposes.
{{!}}-
{{!}}_genesys.widgets.webchat.state.purecloud-v2-sockets.JWtoken
{{!}}Used only with Genesys Cloud V2 API, containing the JWT token related to the current active chat session.
{{!}}-
{{!}}_genesys.widgets.webchat.state.purecloud-v2-sockets.ConversationID
{{!}}Used only with Genesys Cloud V2 API, containing the active conversation ID related to the current chat session.
{{!}}-
{{!}}_genesys.widgets.webchat.state.purecloud-v2-sockets.MemberID
{{!}}Used only with Genesys Cloud V2 API, containing the user ID of the WebChat Widget related to the current active chat session.
{{!}}-
{{!}}_genesys.widgets.webchat.state.purecloud-v2-sockets.WS_URL
{{!}}Used only with Genesys Cloud V2 API, containing the WebSocket event stream URI for listening to new incoming messages.
{{!}}-
{{!}}_genesys.widgets.webchat.state.purecloud-v2-sockets.LastMsgId
{{!}}Used only with Genesys Cloud V2 API, containing the last unique ID of the message sent in the WebChat Widget.
{{!}}}
|Status=No
}}
}}

File:WebChat-screenshot-with-cobrowse-corrected.png

2020-10-28T17:40:44Z

Chrissyforrest:

WID/Current/Developer/GWCDeployment

2020-10-27T21:27:07Z

Chrissyforrest: Published

{{Article
|Standalone=No
|DisplayName=Genesys Widgets Deployment Guide
|TocName=Genesys Widgets Deployment Guide
|Context=This guide provides the steps required to instrument your website with Genesys Widgets.
|ComingSoon=No
|Platform=GenesysCloud, GenesysEngage-cloud
|Role=Developer
|Section={{Section
|sectionHeading=Audience
|anchor=Audience
|alignment=Vertical
|structuredtext=This document is for website developers who are in charge of website code. You must have knowledge of HTML, JavaScript, and CSS.
|Status=No
}}{{Section
|sectionHeading=How can I deploy Genesys Widgets?
|anchor=HowcanIdeployGenesysWidgets
|alignment=Vertical
|structuredtext=There are two deployment methods available:

*{{Link-SomewhereInThisManual|topic=GWCDeployment|anchor=lazy|display text=Lazy loading}}— The recommended method, lazy loading breaks the JavaScript bundle apart into individual plugin files and loads them into the page only as you need them. This is the preferred method of deploying Genesys Widgets.

*{{Link-SomewhereInThisManual|topic=GWCDeployment|anchor=all|display text=All-in-one}} (deprecated) —The all-in-one method is the "classic" method of deploying Genesys Widgets. In this method, you have one JavaScript file and one CSS file that contain all plugins and resources.

{{AnchorDiv|lazy}}
|Status=No
}}{{Section
|sectionHeading=Deploying Genesys Widgets (lazy loading)
|anchor=DeployingGenesysWidgetslazyloading
|alignment=Vertical
|structuredtext={{NoteFormat|Lazy loading is the recommended method for Widgets. The ({{Link-SomewhereInThisManual|topic=GWCDeployment|anchor=all|display text=all-in-one}}) method is deprecated.|}}
===Files used===

*'''widgets/cxbus.min.js'''
*'''widgets/plugins/widgets-core.min.js'''
*'''widgets/plugins/*.*'''

A good starting point is the following script:

<source lang="javascript">

<script src="widgets/cxbus.min.js"
onload="javascript:CXBus.configure({debug:true,pluginsPath:
'build/plugins/'});CXBus.loadFile('path/to/widgets.config.js')
.done(function(){CXBus.loadPlugin('widgets-core')});"></script>

</source>

This script does the following:

#Loads '''cxbus.min.js'''. This makes the global CXBus instance available.
#Configures CXBus to turn on debug logging and set the path to the Widgets plugin folder.
#Loads your configuration file, '''widgets.config.js'''. (This is an imaginary file. You must create it).
#Loads '''widgets-core''', the core Genesys Widgets library.

Use this script as a starting point and customize it as needed.

Remember that your configuration can be defined inline on the page or loaded in as a separate file (as shown in this script).

{{NoteFormat|Whichever method you choose, you must ensure your configuration is in the page before you load '''widgets-core'''. Otherwise, '''widgets-core''' cannot read the configuration.}}

{{NoteFormat|Refer to {{Link-SomewhereInThisManual|topic=GWCConfig|display text=Configuring Genesys Widgets}} for help.|}}

===On-demand lazy loading===

Genesys Widgets is designed to load plugins into the page on-demand as you use the product. For example, if you call the command '''WebChat.open''', CXBus fetches the '''webchat.min.js''' plugin from the '''plugins/''' folder and loads it into the page. Any WebChat command triggers it to load. Likewise, WebChat calls WebChatService commands, thus CXBus loads '''webchatservice.min.js''' into the page as well.

===Preloading plugins===

In some cases, you might not want to load plugins on-demand, or the demand is to load them at startup. A good example is SideBar. You probably want this plugin to appear on the screen immediately so the customer can use it. To make this possible, you can specify which plugins you want to preload at startup in your configuration.

<source lang="javascript">

_genesys.widgets.main.preload = [

"sidebar"
];

</source>

You may specify as many plugins as you want in the preload list. The plugins load in order after you load Widgets Core.

All plugin names are lower-case. Please refer to the file names in the '''plugins/''' folder. For example, to preload '''webchat.min.js''', specify <tt>webchat</tt>, the first part of the file name.

You may find other plugins or features of plugins that necessitate preloading.

{{AnchorDiv|all}}
|Status=No
}}{{Section
|sectionHeading=Deploying Genesys Widgets (all-in-one)
|anchor=DeployingGenesysWidgetsallinone
|alignment=Vertical
|structuredtext={{NoteFormat|1=Lazy loading is the recommended method for Widgets. The ({{Link-SomewhereInThisManual|topic=GWCDeployment|anchor=all|display text=all-in-one}}) method is deprecated.|2=}}
===Files Used===

*'''widgets/widgets.min.css'''
*'''widgets/widgets.min.js'''

A good starting point is the following script:

<source lang="javascript">
<script src-"widgets/widgets.config.js"></script>
<script src="widgets/widgets.min.js"></script>
<link id="genesys-widgets-styles" data-origID="genesys-widgets-styles" data-origID="genesys-widgets-styles" data-origID="genesys-widgets-styles" data-origID="genesys-widgets-styles" data-origID="genesys-widgets-styles" data-origID="genesys-widgets-styles" data-origID="genesys-widgets-styles" data-origID="genesys-widgets-styles" data-origID="genesys-widgets-styles" href="http://www.yourhost.com/path/to/widgets.min.css" type="text/css" rel="stylesheet"/>
</source>

First, you must define your configuration for Genesys Widgets. You can do this inline on the page by using a ''script'' tag, or you can store it in a separate file and load it in before '''widgets.min.js'''. In the script example above, we assume your configuration is stored in another file. You must create the '''widgets.config.js''' file for this script to function properly.

{{NoteFormat|Whichever method you choose, you must ensure your configuration is in the page before you load '''widgets.min.js'''. Otherwise, '''widgets.min.js''' cannot read the configuration.}}

{{NoteFormat|Refer to {{Link-SomewhereInThisManual|topic=GWCConfig|display text=Configuring Genesys Widgets}} for help.|}}

{{AnchorDiv|alternative}}
==Alternative deployment script==

To simplify the deployment process while using tools like Google Tag Manager, you can use below script to embed Widgets.

<source lang="javascript">
<script>
var widgetBaseUrl = 'https://apps.mypurecloud.ie/widgets/9.0/',
widgetScriptElement = document.createElement('script');

widgetScriptElement.setAttribute('src', widgetBaseUrl + 'cxbus.min.js');

widgetScriptElement.addEventListener('load', function () {

CXBus.configure({debug: false, pluginsPath: widgetBaseUrl + 'plugins/'});
CXBus.loadPlugin('widgets-core');
});

document.head.append(widgetScriptElement);
</script>
</source>

{{AnchorDiv|CDN}}
|Status=No
}}{{Section
|sectionHeading=Releases hosted on Content Delivery Network (CDN)
|anchor=ReleaseshostedonContentDeliveryNetworkCDN
|alignment=Vertical
|structuredtext=Genesys Widgets are now available over CDN, providing optimized load times and instant access to new releases.

<pre>
https://apps.mypurecloud.com/widgets/<version>/<filename>
</pre>

Note that <version> and <filename> are placeholders.

===<filename>===
This value varies based on the deployment method you choose.

{{NoteFormat|In the case where a CDN URL that you are trying to access is '''not found''', it means that either the release or the file you are looking for is not yet available.|2}}

===<version>===
version can take one of the following 3 values.

*9.0 - (Major) - A version that is company-wide or
*9.0.xxx - (Major).(Minor) - Minor version is product specific and is tied to each Widget’s iteration or
*9.0.xxx.xx - (Major).(Minor).(Release candidate) - Specific release version

For all the available released versions, refer to the [https://docs.genesys.com/Documentation/PSAAS/Public/RN/GW Widgets Release Notes].

===Choose region===
Widgets is available in a number of regions worldwide as shown below. Please choose the nearest or appropriate region URL based on where you are located.

{{{!}} border="1"
{{!}}-
!Region
!URL
{{!}}-
{{!}}North America (East)
{{!}}<nowiki>https://apps.mypurecloud.com/widgets/{version}/{path/to/file}</nowiki>
{{!}}-
{{!}}North America (West)
{{!}}<nowiki>https://apps.usw2.pure.cloud/widgets/{version}/{path/to/file}</nowiki>
{{!}}-
{{!}}North America (Canada)
{{!}}<nowiki>https://apps.cac1.pure.cloud/widgets/{version}/{path/to/file}</nowiki>
{{!}}-
{{!}}Australia or New Zealand
{{!}}<nowiki>https://apps.mypurecloud.com.au/widgets/{version}/{path/to/file}</nowiki>
{{!}}-
{{!}}EU (Ireland)
{{!}}<nowiki>https://apps.mypurecloud.ie/widgets/{version}/{path/to/file}</nowiki>
{{!}}-
{{!}}EU (Frankfurt)
{{!}}<nowiki>https://apps.mypurecloud.de/widgets/{version}/{path/to/file}</nowiki>
{{!}}-
{{!}}UK (London)
{{!}}<nowiki>https://apps.euw2.pure.cloud/widgets/{version}/{path/to/file}</nowiki>
{{!}}-
{{!}}Japan
{{!}}<nowiki>https://apps.mypurecloud.jp/widgets/{version}/{path/to/file}</nowiki>
{{!}}-
{{!}}Seoul
{{!}}<nowiki>https://apps.apne2.pure.cloud/widgets/{version}/{path/to/file}</nowiki>
{{!}}}

===Using Genesys Widgets CDN with versions===
Starting in the 9.0.006.02 release, all the released versions are accessible from the Genesys CDN URL. The sections below explain how to access the latest available released version or a specific released version using Genesys CDN.

To get the latest released version under the 9.0 family: https://apps.mypurecloud.com/widgets/9.0/widgets.min.js

To get the last available released version under a specific (Major).(Minor) version (this also includes any hot fixes for that release): <nowiki>https://apps.mypurecloud.com/widgets/</nowiki>'''9.0.xxx'''/widgets.min.js

'''Example:''' <nowiki>https://apps.mypurecloud.com/widgets/</nowiki>'''9.0.006'''/widgets.min.js

To get a specific release/hot-fix version: <nowiki>https://apps.mypurecloud.com/widgets/</nowiki>'''9.0.xxx.xx'''/widgets.min.js

'''Example:''' <nowiki>https://apps.mypurecloud.com/widgets/</nowiki>'''9.0.006.02'''/widgets.min.js{{NoteFormat|Note that all older versions of Genesys Widgets may not be available in the CDN. All the released versions are available only starting with the 9.0.006.02 version.}}

===Versioning examples with scenarios===
When a new release version comes out, it is available under all the 3 different CDN URLs below. In this example, if 9.0.006.01 is the first ever release announced, then it is available under the following CDN URLs.

*/9.0/
*/9.0.006/
*/9.0.006.01/

When 9.0.007.04 is released, it is available under /9.0/ but '''not''' under /9.0.006/ or /9.0.006.01/. Instead, /9.0.007/ and /9.0.007.04/ CDN URLs are created and this release is available under them:

*/9.0/
*/9.0.007/
*/9.0.007.04/

If a hot fix (such as 9.0.006.02) is released after 9.0.007.04 is released, then the hot fix is available under the following CDN URLs:

*/9.0.006/
*/9.0.006.02/

If a hot fix (such as 9.0.007.05) is released before announcing any new release, then it is available under the following CDN URLs:

*/9.0/
*/9.0.007/
*/9.0.007.05/

===Deployment methods===

====Lazy loading====
'''Recommended approach:''' When using the lazy loading method, the base Genesys CDN URL must be prefixed in the {{Link-SomewhereInThisManual|topic=GWCDeployment|anchor=lazy|display text=lazy loading deployment script}}. The <filenames> value is not needed in this scenario because they are auto-loaded from the base CDN configured. Here is what the deployment script looks like when using 9.0.006.02 release:

<source lang="javascript">
<script src="https://apps.mypurecloud.com/widgets/9.0.006.02/cxbus.min.js" onload="javascript:CXBus.configure({debug:true,pluginsPath:
'https://apps.mypurecloud.com/widgets/9.0.006.02/plugins/'});
CXBus.loadFile('path/to/widgets.config.js').done(function()
{CXBus.loadPlugin('widgets-core')});"></script>

</source>

====All-in-one====
'''Legacy approach (deprecated):''' When using the all-in-one deployment method, the values are the files mentioned in the {{Link-SomewhereInThisManual|topic=GWCDeployment|anchor=all|display text=all-in-one}} section. For example, if you would like to use widgets.min.js and widgets.min.css under 9.0.006.02 release, CDN URLs will look like this:

<pre>
https://apps.mypurecloud.com/widgets/9.0.006.02/widgets.min.js
https://apps.mypurecloud.com/widgets/9.0.006.02/widgets.min.css
</pre>

<br />
|Status=No
}}{{Section
|sectionHeading=Checking Widgets Version
|alignment=Vertical
|structuredtext='''CXBus.command("App.info");'''

Prints out the debug header with version information.

'''window._genesys.widgets.common.data("version");'''

Returns the version number directly, as a string.

<br />
|Status=No
}}
}}

WID/HIW

2020-10-27T21:17:40Z

Chrissyforrest: Published

{{HIW
|DisplayName=How Widgets works
|TocName=How Widgets works
|Context=Learn how Genesys Widgets works.
|ComingSoon=No
|Platform=GenesysEngage-cloud
|Role=Developer
|featurename=Widgets
|ShortDescription=Genesys Widgets is a set of APIs that provides specific types of user interface elements—normally referred to as ''widgets''—and the services to drive them, enabling you to enhance your website with chat or callback, or your own customized contact center functionality.
|overviewtext=Modern contact centers need more than voice channels to keep up with their customers. Whether it's a chat session or screen sharing—or even if it's just a matter of scheduling a callback—digital channels and other modern customer support functions are a necessity for providing a unified customer journey.

Genesys Widgets is a set of APIs that provides specific types of user interface elements—normally referred to as ''widgets''—and the services to drive them, enabling you to enhance your website with chat or callback, or your own customized contact center functionality.

[[File:Webchat main new.jpg|750x750px]]
|featureoverview=Genesys Widgets is built on top of the {{Link-AnywhereElse|product=WID|version=Current|manual=SDK|topic=GWCBusAPIOverview|display text=CXBus}} messaging bus. CXBus uses the {{#Widget:ExtLink|link=https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern|displaytext=publish–subscribe pattern}} to facilitate communication between the Widgets components, all of which are ''plugins'' that can both ''publish'' events on the bus and ''subscribe'' to the events they are interested in.

With the help of the Widgets-Core plugins, CXBus makes it possible to combine the logic implemented by user interface plugins, service plugins, and utility plugins into cohesive products that can provide chat sessions, schedule callbacks, and so on.
[[File:Widgets-architecture.png|center|600x600px]]
<br />
===CXBus===
This messaging bus allows you to create your own plugins with a namespaced API consisting of commands, events, and a data model. CXBus also loads your plugins and resources—either manually or automatically. Every other component in Genesys Widgets is a CXBus plugin. In addition to creating your own plugins for use on the bus, you can use CXBus to manually call plugin commands, subscribe to events, or read data.
===Widgets-Core===
These plugins make up the Widgets framework. All of the other plugins depend on them:

*{{Link-AnywhereElse|product=WID|version=Current|manual=SDK|topic=App-combined|display text=App}} (main parent controller for Genesys Widgets)
*{{Link-AnywhereElse|product=WID|version=Current|manual=SDK|topic=Common|display text=Common}}
*{{Link-AnywhereElse|product=WID|version=Current|manual=SDK|topic=Overlay-combined|display text=Overlay}}
*{{Link-AnywhereElse|product=WID|version=Current|manual=SDK|topic=Toaster-combined|display text=Toaster}}
*{{Link-AnywhereElse|product=WID|version=Current|manual=SDK|topic=WindowManager-combined|display text=WindowManager}}

===Service plugins===
These handle the network connections to Genesys channels. UI plugins use their services to communicate with the server indirectly. They can also be used independently to develop your own UI plugins.

*{{Link-AnywhereElse|product=WID|version=Current|manual=SDK|topic=CallbackService-combined|display text=CallbackService}}
*{{Link-AnywhereElse|product=WID|version=Current|manual=SDK|topic=StatsService-combined|display text=StatsService}}
*{{Link-AnywhereElse|product=WID|version=Current|manual=SDK|topic=WebChatService-combined|display text=WebChatService}}

===UI plugins===
Also known as ''Widgets'':

*{{Link-AnywhereElse|product=WID|version=Current|manual=SDK|topic=Calendar-combined|display text=Calendar}}
*{{Link-AnywhereElse|product=WID|version=Current|manual=SDK|topic=Callback-combined|display text=Callback}}
*{{Link-AnywhereElse|product=WID|version=Current|manual=SDK|topic=CallUs-combined|display text=CallUs}}
*{{Link-AnywhereElse|product=WID|version=Current|manual=SDK|topic=ChannelSelector-combined|display text=ChannelSelector}}
*{{Link-AnywhereElse|product=WID|version=Current|manual=SDK|topic=Console-combined|display text=Console}}
*{{Link-AnywhereElse|product=WID|version=Current|manual=SDK|topic=SideBar-combined|display text=SideBar}}
*{{Link-AnywhereElse|product=WID|version=Current|manual=SDK|topic=WebChat-combined|display text=WebChat}}

===Bridge plugins===
The {{Link-AnywhereElse|product=WID|version=Current|manual=SDK|topic=Engagement-combined|display text=Engage}} plugin interfaces Genesys Widgets with other products.

===Modules===
These are standalone bits of code or data that can be loaded-into plugins directly. WebChatService has both a version 1 and a version 2 controller. The proper controller module is loaded at runtime, based on your configuration options.
|HIWSection={{HIWSection
|HIWSectionHeading=Related stuff
|HIWSectionAlignment=Vertical
|HIWSectionGif=No
|HIWSectionText=*{{Link-AnywhereElse|product=WID|version=Current|manual=Developer|display text=Widgets Developer's Guide}}
*{{Link-AnywhereElse|product=WID|version=Current|manual=SDK|display text=Widgets API Reference}}
*{{#Widget:ExtLink|link=https://docs.genesys.com/Documentation/PSAAS/Public/RN/GW|displaytext=Genesys Widgets Release Notes}}
}}{{HIWSection
|HIWSectionHeading=How to use Genesys Widgets
|HIWSectionAlignment=Vertical
|HIWSectionGif=No
|HIWSectionText=Read the {{Link-AnywhereElse|product=WID|version=Current|manual=Developer|topic=GWCDeployment|display text=Get started}} article.
}}
|advanced=No
}}

WID/Current/SDK/Engagement-combined

2020-10-27T20:52:55Z

Chrissyforrest: Published

{{Article
|Standalone=No
|DisplayName=Engage
|TocName=Engage
|Context=Learn how to use the Genesys Engage plugin to integrate any Engage solution with Genesys Widgets.
|ComingSoon=No
|Platform=GenesysEngage-cloud
|Role=Developer
|Section={{Section
|sectionHeading=Overview
|anchor=overview
|alignment=Vertical
|structuredtext=[[File:Desktop_Engage_Offer_Overlay_View_with_Text_on_left_v1.png|center|frameless|675x675px]]
The Genesys Engage plugin is generic and contains commands that automate customer engagement within Genesys Widgets. Starting with version {{#Widget:ExtLink|link=https://docs.genesys.com/Documentation/PSAAS/Public/RN/GW#Nov292019|displaytext=9.0.015.11}}, the Engage plugin includes Offers, which allows a customer to view a product or promotion on a page. It comes with many display modes and rendering options, such as overlay/toaster mode with text or image-only layouts, or both.
[[File:Engage Invite Dark v2.png|center|frameless|525x525px]]
===Usage===
Use the Engage plugin to show either an invite or an offer via the following methods:

*Calling the {{Link-SomewhereInThisVersion|manual=SDK|topic=Engagement-combined|anchor=invite|display text=Engage.invite}} command
*Calling the {{Link-SomewhereInThisVersion|manual=SDK|topic=Engagement-combined|anchor=offer|display text=Engage.offer}} command

===Namespaces===
The Engage plugin uses the following namespaces.
{{{!}} class="wikitable"
!Type
!Namespace
{{!}}-
{{!}}i18n - {{Link-SomewhereInThisVersion|manual=SDK|topic=Engagement-combined|anchor=localize|display text=Localization}}
{{!}}Engage
{{!}}-
{{!}}CXBus - {{Link-SomewhereInThisVersion|manual=SDK|topic=Engagement-combined|anchor=commands|display text=API commands}} & {{Link-SomewhereInThisVersion|manual=SDK|topic=Engagement-combined|anchor=events|display text=API events}}
{{!}}Engage
{{!}}-
{{!}}CSS
{{!}}.cx-engage
{{!}}}

===Screenshots===
'''Engage Invite'''

[[File:Engage_Invite_Mobile_Dark_theme_v1.png|150x150px|Mobile mode Engage Invite view with dark theme]]
[[File:Engage_Invite_Mobile_Light_theme_v1.png|150x150px|Mobile mode Engage Invite view with light theme]]

'''Engage Offer'''

[[File:Desktop_Engage_Offer_toaster_mode.png|150x150px|Desktop Toast view with both image and text]]
[[File:Desktop_Engage_Offer_modal_overlay_view_with_text_on_top.png|150x150px|Desktop Modal Overlay view with text on top]]
[[File:Desktop_Engage_Offer_overlay_view_with_text_at_bottom.png|150x150px|Desktop Overlay view with text at bottom]]
[[File:Desktop_Engage_Offer_Toast_view_with_text_content_on_right.png|150x150px|Desktop Toast view with text content on right side]]
[[File:Desktop_Engage_Offer_Toast_view_with_text_content_on_left.png|150x150px|Desktop Toast view with text content on left side]]
[[File:Desktop_Engage_Offer_overlay_view_-_Right_text_v1.png|150x150px|Desktop Overlay view with text on right side]]
[[File:Desktop_Engage_Offer_modal_Overlay_View_with_Text_on_left.png|150x150px|Desktop Modal Overlay view with text on left side]]
[[File:Mobile_Engage_Offer_inserted_onto_the_top_of_a_webpage.png|150x150px|Mobile Offer inserted onto the top of a web page]]
[[File:Mobile_mode_Engage_Offer_view_in_modal_overlay_with_background_greyed_out_v1.png|150x150px|Mobile Offer view in modal overlay with background area grayed out]]
[[File:Mobile_mode_Engage_Offer_view_in_modal_overlay_v1.png|150x150px|Mobile Offer view in modal overlay]]
|Status=No
}}{{Section
|sectionHeading=Configuration
|anchor=config
|alignment=Vertical
|structuredtext=The Genesys Engage plugin doesn't have any configuration options.
|Status=No
}}{{Section
|sectionHeading=Localization
|anchor=localize
|alignment=Vertical
|structuredtext=The Genesys Engage plugin doesn't have any localization options.
|Status=No
}}{{Section
|sectionHeading=API commands
|anchor=commands
|alignment=Vertical
|structuredtext=Once you've registered your plugin on the bus, you can call commands on other registered plugins. Here's how to use the global bus object to register a new plugin on the bus.

{{NoteFormat|The global bus object is a debugging tool. When implementing Widgets on your own site, do not use the global bus object to register your custom plugins. Instead, see {{Link-SomewhereInThisVersion|manual=SDK|topic=GWCBusExtensions|display text=Genesys Widgets extensions}} for more information about extending Genesys Widgets.|1}}

<source lang="javascript">var oMyPlugin = window._genesys.widgets.bus.registerPlugin('MyPlugin');

oMyPlugin.command('Engage.invite');</source>
{{AnchorDiv|invite}}
===invite===
Opens the Engage Widget and renders the text based on the options provided. If no options are provided, the widget doesn't open.

===Example===
<source lang="javascript">oMyPlugin.command('Engage.invite', {
'type':'toast',
'timeout':3000,
'title':'Engage Title',
'ariaTitle':'Engage Invite',
'body':'Engage invite body content',
'accept':'Yes',
'decline':'No, thanks',
'ariaAccept':'Yes',
'ariaDecline':'No, thanks',
'ariaClose':'Close',
'command': 'WebChat.open',
'options':{'proactive': true, 'userData': {'category': 'shoes'}}
});

oMyPlugin.command('Engage.invite',{
'type':'toast',
'timeout':3000,
'force': true,
'title':'Engage Title',
'ariaTitle':'Engage Invite',
'body':'Engage invite body content',
'accept':'Yes',
'decline':'No, thanks',
'ariaAccept':'Yes',
'ariaDecline':'No, thanks',
'ariaClose':'Close'
}).done(function(response){

// Act upon the received response code

switch(response){
case 'accepted':oMyPlugin.command('WebChat.open');
break;
case 'declined': break;
case 'closed': break;
case 'timeout': break;
}

});
</source>

===Options===
{{{!}} class="wikitable"
!Option
!Type
!Description
!Accepted Values
!Default
!Introduced/Updated
{{!}}-
{{!}}type
{{!}}string
{{!}}Widget display type.
{{!}}toast
{{!}}
{{!}}
{{!}}-
{{!}}timeout
{{!}}number
{{!}}Timeout integer in milliseconds.
{{!}}n/a
{{!}}
{{!}}
{{!}}-
{{!}}title
{{!}}string
{{!}}String for widget title.
{{!}}n/a
{{!}}
{{!}}
{{!}}-
{{!}}ariaTitle
{{!}}string
{{!}}Aria label text for the Engage invite window.
{{!}}n/a
{{!}}
{{!}}9.0.015.04
{{!}}-
{{!}}body
{{!}}string
{{!}}String for offer body text.
{{!}}n/a
{{!}}
{{!}}
{{!}}-
{{!}}accept
{{!}}string
{{!}}String for Accept button text.
{{!}}n/a
{{!}}
{{!}}
{{!}}-
{{!}}ariaAccept
{{!}}string
{{!}}Aria label text for the Accept button.
{{!}}n/a
{{!}}
{{!}}9.0.016.10
{{!}}-
{{!}}decline
{{!}}string
{{!}}String for Decline button text.
{{!}}n/a
{{!}}
{{!}}
{{!}}-
{{!}}ariaDecline
{{!}}string
{{!}}Aria label text for the Decline button.
{{!}}n/a
{{!}}
{{!}}9.0.016.10
{{!}}-
{{!}}ariaClose
{{!}}string
{{!}}Aria label text for the Engage Close button.
{{!}}n/a
{{!}}
{{!}}9.0.016.10
{{!}}-
{{!}}command
{{!}}string
{{!}}Command to execute.
{{!}}n/a
{{!}}
{{!}}
{{!}}-
{{!}}options
{{!}}object
{{!}}Options related to the command provided.
{{!}}n/a
{{!}}
{{!}}
{{!}}-
{{!}}priority
{{!}}number
{{!}}Replace the active lower priority Engage invite with the higher priority Engage invite.
{{!}}n/a
{{!}}0
{{!}}9.0.015.11
{{!}}-
{{!}}force
{{!}}boolean
{{!}}Replace the active Engage invite with the new Engage invite irrespective of priorities.
{{!}}n/a
{{!}}false
{{!}}9.0.015.11
{{!}}-
{{!}}}

===Resolutions===
{{{!}} class="wikitable"
!Status
!When
!Returns
{{!}}-
{{!}}resolved
{{!}}When engage invite is accepted by user.
{{!}}accepted
{{!}}-
{{!}}resolved
{{!}}When engage invite is declined by user.
{{!}}declined
{{!}}-
{{!}}resolved
{{!}}When engage invite widget is closed by user.
{{!}}closed
{{!}}-
{{!}}resolved
{{!}}When engage invite widget closes due to timeout.
{{!}}timeout
{{!}}-
{{!}}}
{{AnchorDiv|offer}}
===offer===
Opens a widget for a product offer using the data sent through the command options provided below. The widget can include both rendering options and the actual data that needs to be displayed in the Offer Widget. If no options are provided, the widget will not open.

===Example===
<source lang="javascript">
oMyPlugin.command('Engage.offer', {

mode:'overlay',
modal:true,
layout:'leftText',
title: 'GRAB WHAT YOU NEED!!',
ariaTitle: 'Offers',
headline:'We Got All!',
description:'Get free NextDay delivery on orders of $35 or more. Start shopping now!',

cta:{
text:'Join',
url:'https://www.genesys.com',
target:'_blank'
},

image:{
src:'https://picsum.photos/id/237/300/300',
alt:'Alternate Text for Image'
},

styles:{
closeButton:{
'color':'red'
}
},
ariaCTA:'Join',
ariaClose:'Close Offer'
});
</source>
===Options===
{{{!}} class="wikitable"
!Option
!Type
!Description
!Accepted values
!Default
!Introduced/Updated
{{!}}-
{{!}}mode
{{!}}string
{{!}}The display type of the Offer widget.
{{!}}overlay, toaster
{{!}}toaster
{{!}}9.0.015.04
{{!}}-
{{!}}modal
{{!}}boolean
{{!}}Applicable only when mode is 'overlay'. A smokescreen will be shown in the background of overlay modal window. This window can be dismissed by clicking anywhere in the smokescreen area.
{{!}}n/a
{{!}}false
{{!}}9.0.015.04
{{!}}-
{{!}}layout
{{!}}string
{{!}}Additional layout options are supported for all modes.
{{!}}minimal, leftText, rightText, topText, bottomText
{{!}}leftText
{{!}}9.0.015.04
{{!}}-
{{!}}headline
{{!}}string
{{!}}The Offer title header text.
{{!}}n/a
{{!}}n/a
{{!}}9.0.015.04
{{!}}-
{{!}}ariaTitle
{{!}}string
{{!}}Aria label text for the Offer window.
{{!}}n/a
{{!}}n/a
{{!}}9.0.015.04
{{!}}-
{{!}}description
{{!}}string
{{!}}The Offer body description text.
{{!}}n/a
{{!}}n/a
{{!}}9.0.015.04
{{!}}-
{{!}}cta
{{!}}object
{{!}}An object containing HTML attributes and/or CXBus commands for the CTA (call to action) button.
{{!}}n/a
{{!}}n/a
{{!}}9.0.015.04
{{!}}-
{{!}}cta.text
{{!}}string
{{!}}The CTA button text.
{{!}}n/a
{{!}}n/a
{{!}}9.0.015.04
{{!}}-
{{!}}cta.url
{{!}}string
{{!}}The URL string for the CTA button.
Note: The URL must be properly defined with the complete Protocol URL Address. For example, https://www.genesys.com.
{{!}}_blank, _parent, _self, _top, framename
{{!}}n/a
{{!}}9.0.015.04
{{!}}-
{{!}}cta.target
{{!}}string
{{!}}Specifies where the URL is opened.
{{!}}n/a
{{!}}n/a
{{!}}9.0.015.04
{{!}}-
{{!}}cta.command
{{!}}string
{{!}}A CXBus command to execute.
{{!}}n/a
{{!}}n/a
{{!}}9.0.015.04
{{!}}-
{{!}}cta.commandOptions
{{!}}string
{{!}}Options related to CXBUs command.
{{!}}n/a
{{!}}n/a
{{!}}9.0.015.04
{{!}}-
{{!}}image
{{!}}object
{{!}}An object containing image tag attributes.
{{!}}n/a
{{!}}n/a
{{!}}9.0.015.04
{{!}}-
{{!}}image.src
{{!}}string
{{!}}The URL of the image.
{{!}}n/a
{{!}}n/a
{{!}}9.0.015.04
{{!}}-
{{!}}image.alt
{{!}}string
{{!}}Alternate text for the image.
{{!}}n/a
{{!}}n/a
{{!}}9.0.015.04
{{!}}-
{{!}}image.title
{{!}}string
{{!}}To indicate the screen reader user whether the image opens the URL in a new window.
{{!}}n/a
{{!}}n/a
{{!}}9.0.016.10
{{!}}-
{{!}}insertAfter
{{!}}string
{{!}}Applicable only in mobile mode. An ID or class name of an HTML selector from the host page. The offer will be inserted after this element. Precede the value mentioned here with the standard Class ('.') and ID selector ('#') character.
{{!}}n/a
{{!}}n/a
{{!}}9.0.015.04
{{!}}-
{{!}}insertBefore
{{!}}string
{{!}}Applicable only in mobile mode. An ID or class name of an HTML selector from the host page. The offer will be inserted before this element. Precede the value mentioned here with the standard Class ('.') and ID selector ('#') character.
{{!}}n/a
{{!}}n/a
{{!}}9.0.015.04
{{!}}-
{{!}}insertInto
{{!}}string
{{!}}Applicable only in mobile mode. An ID or class name of an HTML selector from the host page. The offer will be appended inside this element. Precede the value mentioned here with the standard Class ('.') and ID selector ('#') character.
{{!}}n/a
{{!}}n/a
{{!}}9.0.015.04
{{!}}-
{{!}}styles
{{!}}object
{{!}}An object containing styles for the offer content.
{{!}}n/a
{{!}}n/a
{{!}}9.0.015.04
{{!}}-
{{!}}styles.closeButton
{{!}}object
{{!}}An object containing styles for the close button.
{{!}}n/a
{{!}}n/a
{{!}}9.0.015.04
{{!}}-
{{!}}styles.closeButton.color
{{!}}string
{{!}}The color of the close button.
{{!}}n/a
{{!}}n/a
{{!}}9.0.015.04
{{!}}-
{{!}}styles.closeButton.opacity
{{!}}number
{{!}}The CSS 'opacity' property for the close button.
{{!}}n/a
{{!}}n/a
{{!}}9.0.015.04
{{!}}-
{{!}}styles.overlay
{{!}}object
{{!}}An object containing styles for the overlay container.
{{!}}n/a
{{!}}n/a
{{!}}9.0.015.04
{{!}}-
{{!}}styles.overlay.top
{{!}}string
{{!}}The CSS 'top' property for the overlay container.
{{!}}n/a
{{!}}n/a
{{!}}9.0.015.04
{{!}}-
{{!}}styles.overlay.right
{{!}}string
{{!}}The CSS 'right' property for the overlay container.
{{!}}n/a
{{!}}n/a
{{!}}9.0.015.04
{{!}}-
{{!}}styles.overlay.bottom
{{!}}string
{{!}}The CSS 'bottom' property for the overlay container.
{{!}}n/a
{{!}}n/a
{{!}}9.0.015.04
{{!}}-
{{!}}styles.overlay.left
{{!}}string
{{!}}The CSS 'left' property for the overlay container.
Note: When all the position values are provided, the order of precedence will be top, right, bottom, and left.
{{!}}n/a
{{!}}n/a
{{!}}9.0.015.04
{{!}}-
{{!}}styles.overlay.center
{{!}}boolean
{{!}}Aligns the overlay container to the center of the screen.
{{!}}n/a
{{!}}true
{{!}}9.0.015.04
{{!}}-
{{!}}styles.offer
{{!}}object
{{!}}An object containing styles for the Offer window.
{{!}}n/a
{{!}}n/a
{{!}}9.0.015.04
{{!}}-
{{!}}styles.offer.backgroundColor
{{!}}string
{{!}}The background color of the offer.
{{!}}n/a
{{!}}n/a
{{!}}9.0.015.04
{{!}}-
{{!}}styles.offer.color
{{!}}string
{{!}}The text color of the offer.
{{!}}n/a
{{!}}n/a
{{!}}9.0.015.04
{{!}}-
{{!}}styles.offer.padding
{{!}}string
{{!}}The padding for the offer container.
{{!}}n/a
{{!}}0
{{!}}9.0.015.04
{{!}}-
{{!}}styles.title
{{!}}object
{{!}}An object containing styles for the title.
{{!}}n/a
{{!}}n/a
{{!}}9.0.015.04
{{!}}-
{{!}}styles.title.font
{{!}}string
{{!}}The CSS 'font' property for the title.
{{!}}n/a
{{!}}n/a
{{!}}9.0.015.04
{{!}}-
{{!}}styles.title.textAlign
{{!}}string
{{!}}The CSS 'text-align' property for the title.
{{!}}n/a
{{!}}n/a
{{!}}9.0.015.04
{{!}}-
{{!}}styles.headline
{{!}}object
{{!}}An object containing styles for the header text.
{{!}}n/a
{{!}}n/a
{{!}}9.0.015.04
{{!}}-
{{!}}styles.headline.font
{{!}}string
{{!}}The CSS 'font' property for the header text.
{{!}}n/a
{{!}}n/a
{{!}}9.0.015.04
{{!}}-
{{!}}styles.headline.textAlign
{{!}}string
{{!}}The CSS 'text-align' property for the header text.
{{!}}n/a
{{!}}n/a
{{!}}9.0.015.04
{{!}}-
{{!}}styles.description
{{!}}object
{{!}}An object containing styles for the offer description text.
{{!}}n/a
{{!}}n/a
{{!}}9.0.015.04
{{!}}-
{{!}}styles.description.font
{{!}}string
{{!}}The CSS 'font' property for the description text.
{{!}}n/a
{{!}}n/a
{{!}}9.0.015.04
{{!}}-
{{!}}styles.description.textAlign
{{!}}string
{{!}}The CSS 'text-align' property for the description text.
{{!}}n/a
{{!}}n/a
{{!}}9.0.015.04
{{!}}-
{{!}}styles.ctaButton
{{!}}object
{{!}}An object containing styles for call to action button in the offer window.
{{!}}n/a
{{!}}n/a
{{!}}9.0.015.04
{{!}}-
{{!}}styles.ctaButton.font
{{!}}string
{{!}}The CSS 'font' property for the text in CTA button.
{{!}}n/a
{{!}}n/a
{{!}}9.0.015.04
{{!}}-
{{!}}styles.ctaButton.textAlign
{{!}}string
{{!}}The CSS 'text-align' property for the text in CTA button.
{{!}}n/a
{{!}}n/a
{{!}}9.0.015.04
{{!}}-
{{!}}styles.ctaButton.background
{{!}}string
{{!}}The CSS 'background' property for the CTA button.
{{!}}n/a
{{!}}n/a
{{!}}9.0.015.04
{{!}}-
{{!}}styles.ctaButton.color
{{!}}string
{{!}}The CSS 'color' property for the text in CTA button.
{{!}}n/a
{{!}}n/a
{{!}}9.0.015.04
{{!}}-
{{!}}styles.ctaButton.fontSize
{{!}}string
{{!}}The CSS 'font-size' property for the text in CTA button.
{{!}}n/a
{{!}}n/a
{{!}}9.0.015.04
{{!}}-
{{!}}ariaCTA
{{!}}string
{{!}}Aria label text for the Offer CTA button.
{{!}}n/a
{{!}}n/a
{{!}}9.0.016.10
{{!}}-
{{!}}ariaClose
{{!}}string
{{!}}Aria label text for the Offer Close button.
{{!}}n/a
{{!}}n/a
{{!}}9.0.016.10
{{!}}-
{{!}}priority
{{!}}number
{{!}}Replace the active lower priority Engage Offer with the higher priority Engage Offer.
{{!}}n/a
{{!}}0
{{!}}9.0.015.11
{{!}}-
{{!}}force
{{!}}boolean
{{!}}Replace the active Engage Offer with the new Engage Offer irrespective of priorities.
{{!}}n/a
{{!}}false
{{!}}9.0.015.11
{{!}}-
{{!}}}
|Status=No
}}{{Section
|sectionHeading=API events
|anchor=events
|alignment=Vertical
|structuredtext=Once you've {{Link-SomewhereInThisVersion|manual=SDK|topic=GWCBusAPIOverview|anchor=regplugin|display text=registered your plugin on the bus}}, you can subscribe to and listen for published events. Here's how to use the global bus object to register a new plugin on the bus.

{{NoteFormat|The global bus object is a debugging tool. When implementing widgets on your own site, do not use the global bus object to register your custom plugins. Instead, see {{Link-AnywhereElse|product=WID|version=Current|manual=SDK|topic=GWCBusExtensions}} for more information about extending Genesys Widgets.|1}}
<source lang="javascript">
var oMyPlugin = window._genesys.widgets.bus.registerPlugin('MyPlugin');

oMyPlugin.subscribe('Engage.ready', function(e){});
</source>
{{{!}} class="wikitable"
!Name
!Description
!Data
!Introduced/Updated
{{!}}-
{{!}}ready
{{!}}The Engage widget is initialized and ready to accept commands on the bus.
{{!}}n/a
{{!}}
{{!}}-
{{!}}opened
{{!}}The Engage widget opens.
Note: Applicable only to Engage.offer command
{{!}}{{Link-SomewhereInThisVersion|manual=SDK|topic=Engagement-combined|anchor=metadata|display text=Metadata}}
{{!}}9.0.015.04
{{!}}-
{{!}}CTA
{{!}}When the user clicks the CTA button in the Engage widget.
Note: Applicable only to Engage.offer command
{{!}}{{Link-SomewhereInThisVersion|manual=SDK|topic=Engagement-combined|anchor=metadata|display text=Metadata}}
{{!}}9.0.015.04
{{!}}-
{{!}}hover
{{!}}When the user first hovers over the Engage widget.
Note: Applicable only to Engage.offer command
{{!}}{{Link-SomewhereInThisVersion|manual=SDK|topic=Engagement-combined|anchor=metadata|display text=Metadata}}
{{!}}9.0.015.04
{{!}}-
{{!}}dismissed
{{!}}When the user closes the Engage widget by clicking the Close button.
Note: Applicable only to Engage.offer command
{{!}}{{Link-SomewhereInThisVersion|manual=SDK|topic=Engagement-combined|anchor=metadata|display text=Metadata}}
{{!}}9.0.015.04
{{!}}-
{{!}}closed
{{!}}The Engage widget closes.
Note: Applicable only to Engage.offer command
{{!}}{{Link-SomewhereInThisVersion|manual=SDK|topic=Engagement-combined|anchor=metadata|display text=Metadata}}
{{!}}9.0.015.04
{{!}}}
{{NoteFormat|Applicable only for Engage.offer command.|1}}
===Interaction Lifecycle===
Every offer interaction has a sequence of events we describe as the ''Interaction Lifecycle''. These events track progress and user choices from the beginning of an interaction (opening Offers), to the end (closing Offers), and every step in between.

The following events comprise the Interaction Lifecycle:
<source lang="javascript">ready
opened
CTA
hover
dismissed
closed</source>
===Lifecycle scenarios===
An Interaction Lifecycle can vary based on each user's intent and experience with the Offer widget. Here are several sequences of events in the lifecycle that correspond to different scenarios.

The user opened the Offer widget but changed their mind and closed it without seeing the offer details:
<source lang="LANGUAGE">ready -> opened -> dismissed -> closed
</source>
The user opened the Offer widget, hovered over the offer details, and then closed it:
<source lang="LANGUAGE">ready -> opened -> hover -> dismissed -> closed
</source>
The user opened the Offer widget and clicked on the button, which triggers CTA:
<source lang="LANGUAGE">ready -> opened -> CTA -> closed
</source>
{{NoteFormat|For a list of all Offer events, see {{Link-SomewhereInThisVersion|manual=SDK|topic=Engagement-combined|anchor=events|display text=API events}}.|2}}
|Status=No
}}{{Section
|sectionHeading=Metadata
|anchor=metadata
|alignment=Vertical
|structuredtext=Each event in the Interaction Lifecycle includes the following block of metadata. By default, all values are set to false. As the user progresses through the lifecycle of an Offer Engage interaction, these values are updated.

The metadata block contains Boolean state flags, timestamps, and elapsed times. These values can be used to track and identify trends or issues with interactions. During runtime, the metadata can help you offer a smart and dynamic experience to your users.
===Reference===
{{{!}} class="wikitable"
!Name
!Type
!Description
!Introduced/Updated
{{!}}-
{{!}}opened
{{!}}integer (timestamp)
{{!}}Timestamp indicating when the offer was opened.
{{!}}9.0.015.04
{{!}}-
{{!}}closed
{{!}}integer (timestamp)
{{!}}Timestamp indicating when the offer was closed.
{{!}}9.0.015.04
{{!}}-
{{!}}dismissed
{{!}}integer (timestamp)
{{!}}Timestamp indicating when the user dismissed the offer by clicking the close button.
{{!}}9.0.015.04
{{!}}-
{{!}}triggeredCTA
{{!}}integer (timestamp)
{{!}}Timestamp indicating when the CTA was triggered.
{{!}}9.0.015.04
{{!}}-
{{!}}timeBeforeCTA
{{!}}integer (milliseconds)
{{!}}Total time in milliseconds from when the user opened the offer to when the CTA is triggered.
{{!}}9.0.015.04
{{!}}-
{{!}}timeFirstHover
{{!}}integer (timestamp)
{{!}}Timestamp indicating when the user first hovered over the offer.
{{!}}9.0.015.04
{{!}}-
{{!}}timeBeforeHover
{{!}}integer (milliseconds)
{{!}}Total time in milliseconds from when the user opened the offer to when the user first hovered over the offer.
{{!}}9.0.015.04
{{!}}-
{{!}}timeElapsedHover
{{!}}integer (milliseconds)
{{!}}Total time in milliseconds when the user hovered over the offer.
{{!}}9.0.015.04
{{!}}-
{{!}}elementClicked
{{!}}string
{{!}}Name of CTA element that was clicked.
{{!}}9.0.015.04
{{!}}}
|Status=No
}}
}}

WID/Current/SDK/App-combined

2020-10-27T18:51:59Z

Chrissyforrest: Published

{{Article
|Standalone=No
|DisplayName=App
|TocName=App
|Context=Learn how to control your widgets.
|ComingSoon=No
|Platform=GenesysEngage-cloud
|Role=Developer
|Section={{Section
|sectionHeading=Overview
|alignment=Vertical
|structuredtext=App is the main controller for Genesys Widgets and has no UI. It controls all startup routines, global configurations, and extensions, and it executes the onReady event and distributes changes to theme, language, mobile mode, and other application-wide effects.
===Usage===
App's main interface is its configuration. You set all global defaults using the window._genesys.widgets.main property.
App also has a few commands you can use to change the language and theme.
===Customization===
App itself cannot be customized, but its configuration options affect all widgets.
===Mobile Support===
App has built-in mobile detection and can automatically notify all widgets to switch to mobile mode. You can also control this manually.
|Status=No
}}{{Section
|sectionHeading=Configuration
|anchor=config
|alignment=Vertical
|structuredtext====Description===
App uses the configuration property '_genesys.widgets.main'. App controls the Genesys Widgets product as a whole, handling themes, languages, and mobile devices.

===Example===
<pre>
window._genesys.widgets = {

main: {
theme: 'dark',
themes: {

dark: 'cx-theme-dark',
light: 'cx-theme-light',
blue: 'cx-theme-blue',
red: 'cx-theme-red'
},
lang: 'en',
i18n: 'i18n.json',
mobileMode: 'auto',
mobileModeBreakpoint: 600,
debug: true,
header: {'Authorization': 'value'},
cookieOptions: {
secure: true,
domain: 'genesys.com',
path: '/',
sameSite: 'Strict'
}
},
onReady: function(){

// Do something on Widgets ready
}
}

</pre>
===Options===
{{{!}} class="wikitable"
!Name
!Type
!Description
!Default
!Required
!Introduced/Updated
{{!}}-
{{!}}main.themes
{{!}}object
{{!}}An object list containing the CSS classname for each theme. The property names are used to select the theme in the 'theme' property, for example {dark:'cx-theme-dark', light:'cx-theme-light', 'red':'cx-theme-red', 'blue':'cx-theme-blue'}.
Where 'dark' and 'light' are the built-in themes provided in Genesys Widgets and 'red' and 'blue' are example custom theme names you may create on your own. {{NoteFormat|It is not necessary to define the 'dark' and 'light' theme as shown in this example. It is included to help show how the formatting works. Whatever you put in this object will be merged with the default themes object internally.|}}
{{!}}{dark: 'cx-theme-dark', light: 'cx-theme-light'}
{{!}}n/a
{{!}}
{{!}}-
{{!}}main.theme
{{!}}string
{{!}}Selects the theme to apply to Genesys Widgets from the 'themes' object. Uses the property name of the theme. for example using the example from 'themes' above, possible values for this could be 'dark', 'light', 'red', 'blue'.
{{!}}dark
{{!}}n/a
{{!}}
{{!}}-
{{!}}main.lang
{{!}}string
{{!}}Select the language to use from the 'i18n' language pack. Language codes are selected by the customer. Any language code format can be used as long as this property matches one of the language codes in your i18n language pack. For more information about localization, see {{Link-AnywhereElse|product=WID|version=Current|manual=Developer|topic=GWCInternat|display text=localization}}.
{{!}}en
{{!}}n/a
{{!}}
{{!}}-
{{!}}main.i18n
{{!}}URL string or JSON
{{!}}Either a path to a remote i18n.json language pack file or an inline JSON language pack definition. For more information about language packs, see {{Link-AnywhereElse|product=WID|version=Current|manual=Developer|topic=GWCInternat|display text=localization}}.
{{!}}en
{{!}}Default English language strings are built into each widget and are displayed by default. Defining this i18n language pack overrides the built-in strings.
{{!}}n/a
{{!}}
{{!}}-
{{!}}main.header
{{!}}object
{{!}}An object containing a key value pair for the authorization header.
{{!}}n/a
{{!}}n/a
{{!}}9.0.002.06
{{!}}-
{{!}}{{AnchorDiv|MP}}main.preload
{{!}}array
{{!}}(For use with lazy loading only) A list of plugins you want pre-loaded at startup. You may want certain plugins, such as SideBar, to be shown on screen as soon as possible; to do so, you may add 'sidebar' to this preload plugins array so it will be loaded after Widgets starts up. The names you add to the list must match the first part of the plugin filename you wish to load. Example: 'sidebar' will load 'sidebar.min.js' from the 'plugins/' folder. All filenames are lowercase.{{NoteFormat|This preload array is intended for use when running widgets in lazy loading mode. You may also use this to pre-load your own custom-made plugins.|}}
{{!}}none
{{!}}When lazy loading Widgets
{{!}}
{{!}}-
{{!}}main.mobileMode
{{!}}boolean/string
{{!}}Mobile Mode setting.
true = Force Mobile Mode on all devices. false = Disable Mobile Mode completely. 'auto' = Genesys Widgets Automatically switches between Mobile and Desktop Modes using the 'mobileModeBreakpoint' property and UserAgent detection.
{{!}}auto
{{!}}n/a
{{!}}
{{!}}-
{{!}}main.timeFormat
{{!}}number/string
{{!}}This sets the time format for the timestamps. It can be 12 or 24.
{{!}}12
{{!}}n/a
{{!}}
{{!}}-
{{!}}main.mobileModeBreakpoint
{{!}}number
{{!}}The breakpoint width in pixels where Genesys Widgets will switch to Mobile Mode. Breakpoint checked at startup only.
{{!}}600
{{!}}n/a
{{!}}
{{!}}-
{{!}}main.debug
{{!}}boolean
{{!}}Enable debug logging from the bus to appear in the browser console.
{{!}}false
{{!}}n/a
{{!}}
{{!}}-
{{!}}main.customStylesheetID
{{!}}string
{{!}}The HTML ID of a <style> tag that contains CSS overrides, custom themes, or other custom CSS intended for Genesys Widgets. On startup, Widgets will move this <style> tag to the end of the document so that 1:1 CSS class overrides apply correctly.
{{!}}n/a
{{!}}n/a
{{!}}
{{!}}-
{{!}}main.downloadGoogleFont
{{!}}boolean
{{!}} By default, Genesys Widgets downloads and uses the Google font 'Roboto'. to disable this download, set value false.{{!}}true
{{!}}n/a
{{!}}
{{!}}-
{{!}}main.deploymentID
{{!}}string
{{!}}The string used to customize cookie names so that multiple Widgets deployments can run in the same domain.
{{!}}n/a
{{!}}n/a
{{!}}9.0.006.02
{{!}}-
{{!}}main.cookieOptions
{{!}}object
{{!}}An object containing cookie attributes that applies globally to all Widgets. The following cookie attributes are supported:

# 'secure' - Either true or false, indicating if the cookie transmission requires a secure protocol (https).
# 'domain' - A string indicating a valid domain where the cookie should be visible.
# 'path' - A string indicating the path where the cookie is visible.
# 'expires' - Specifies the number of days, either from time of creation or from a date instance, until the cookie is to be removed. 'domain' and 'path' can be used to make cookies compatible with environments that use a non FQDN URL, such as an intranet hostname. However, the domain should only be manually set in production if the automated values are causing problems. Otherwise, rely on the automated domain and path.
# 'sameSite' - This maps to the cookie SameSite attribute allowing the cookie to be restricted to a first-party or same-site context. It can take any of the supported values that [https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite SameSite] attribute takes. {{NoteFormat|The values are automatically set by Widgets to support cross-sub-domain cookies. Modifying these options overrides the automated values and might break cross-sub-domain cookie support if not properly set.

For usage, please refer to the above example|}}
{{!}}{sameSite:'Strict'}
{{!}}n/a
{{!}}9.0.017.01
{{!}}-
{{!}}onReady
{{!}}function
{{!}}A callback function that is invoked when the Widgets are ready and initialized with the configuration provided.
{{!}}none
{{!}}n/a
{{!}}
{{!}}-
{{!}}}
|Status=No
}}{{Section
|sectionHeading=Localization
|alignment=Vertical
|structuredtext=No localization options.
|Status=No
}}{{Section
|sectionHeading=API Commands
|alignment=Vertical
|structuredtext=Once you've registered your plugin on the bus, you can call commands on other registered plugins. Here's how to use the global bus object to register a new plugin on the bus.

{{NoteFormat|The global bus object is a debugging tool. When implementing Widgets on your own site, do not use the global bus object to register your custom plugins. Instead, see {{Link-SomewhereInThisManual|topic=GWCBusExtensions|display text=Widgets Extensions}} for more information about extending Genesys Widgets.|1}}

<source lang="javascript">var oMyPlugin = window._genesys.widgets.bus.registerPlugin('MyPlugin');

oMyPlugin.command('App.themeDemo');</source>
===setTheme===
Sets the theme for Genesys Widgets from the list of registered themes. Default themes are 'light' and 'dark'. You can register as many new themes as you need.

====Example====
<source lang="javascript">
oMyPlugin.command('App.setTheme', {theme: 'light'}).done(function(e){

// App set theme successfully

}).fail(function(e){

// App failed to set theme
});
</source>

<br />
====Options====

{{{!}} class="wikitable"
{{!}}-
!{{!}}Option
!{{!}}Type
!{{!}}Description
{{!}}-
{{!}}{{!}}theme
{{!}}{{!}}string
{{!}}{{!}}Name of the theme you want to use. This name is specified in window._genesys.main.themes. Default themes are 'light' and 'dark'.
{{!}}}

====Resolutions====

{{{!}} class="wikitable"
{{!}}-
!{{!}}Status
!{{!}}When
!{{!}}Returns
{{!}}-
{{!}}{{!}}resolved
{{!}}{{!}}Theme exists and is successfully changed
{{!}}{{!}}The name of the theme that was chosen, for example 'light'.
{{!}}-
{{!}}{{!}}rejected
{{!}}{{!}}Theme does not exist
{{!}}{{!}}'Invalid theme specified'.
{{!}}}
===getTheme===
Get the CSS classname for the currently selected theme.

====Example====
<source lang="javascript">
oMyPlugin.command('App.getTheme').done(function(e){

// App got theme successfully
// e == CSS classname for current theme

}).fail(function(e){

// App failed to get theme
});
</source>

<br />
====Resolutions====

{{{!}} class="wikitable"
{{!}}-
!{{!}}Status
!{{!}}When
!{{!}}Returns
{{!}}-
{{!}}{{!}}resolved
{{!}}{{!}}Always
{{!}}{{!}}CSS classname for the currently selected theme. e.g. 'cx-theme-light'
{{!}}-
{{!}}{{!}}rejected
{{!}}{{!}}Never
{{!}}{{!}} n/a
{{!}}}

===reTheme===
Accepts an HTML reference (either string or jQuery wrapped set) and applies the proper CSS Theme Classname to that HTML and returns it back. When widgets receive the 'theme' event from App, they pass-in their UI containers into App.reTheme to have the old theme classname stripped and new classname applied.

====Example====
<source lang="javascript">
oMyPlugin.command('App.reTheme', {html: '<div>Test Theme</div>'}).done(function(e){

// App set theme successfully

}).fail(function(e){

// App failed to set theme
});
</source>
====Options====

{{{!}} class="wikitable"
{{!}}-
!{{!}}Option
!{{!}}Type
!{{!}}Description
{{!}}-
{{!}}{{!}}html
{{!}}{{!}}string or jQuery Wrapped Set
{{!}}{{!}}HTML string or jQuery Wrapped Set you want to have modified.
{{!}}}

====Resolutions====

{{{!}} class="wikitable"
{{!}}-
!{{!}}Status
!{{!}}When
!{{!}}Returns
{{!}}-
{{!}}{{!}}resolved
{{!}}{{!}}HTML is provided and theme is updated
{{!}}{{!}}HTML that was passed-in and modified
{{!}}-
{{!}}{{!}}rejected
{{!}}{{!}}No HTML is provided
{{!}}{{!}}'No HTML provided by [plugin name]'
{{!}}}
===themeDemo===
Start an automated demo of each theme. All registered themes will be applied with a default delay between themes of 2 seconds. You can override this delay. This command is useful for comparing themes or testing themes with official or custom widgets.

====Example====
<source lang="javascript">
oMyPlugin.command('App.themeDemo', {delay: 1000}).done(function(e){

// App demo successfully started

}).fail(function(e){

// App failed to start demo
});
</source>

<br />
====Options====

{{{!}} class="wikitable"
{{!}}-
!{{!}}Option
!{{!}}Type
!{{!}}Description
{{!}}-
{{!}}{{!}}delay
{{!}}{{!}}number
{{!}}{{!}}Number of milliseconds between theme changes. Default value is 2000 milliseconds.
{{!}}}

====Resolutions====

{{{!}} class="wikitable"
{{!}}-
!{{!}}Status
!{{!}}When
!{{!}}Returns
{{!}}-
{{!}}{{!}}resolved
{{!}}{{!}}Always
{{!}}{{!}} n/a
{{!}}-
{{!}}{{!}}rejected
{{!}}{{!}}Never
{{!}}{{!}} n/a
{{!}}}

===setLanguage===
Changes the language

====Example====
<source lang="javascript">
oMyPlugin.command('App.setLanguage', {lang: 'eng'}).done(function(e){

// App set language successfully started

}).fail(function(e){

// App failed to set language
});
</source>

<br />
====Options====

{{{!}} class="wikitable"
{{!}}-
!{{!}}Option
!{{!}}Type
!{{!}}Description
{{!}}-
{{!}}{{!}}lang
{{!}}{{!}}string
{{!}}{{!}}Change the language of Genesys Widgets. Switches all strings in Widgets to selected language.
{{!}}}

====Resolutions====

{{{!}} class="wikitable"
{{!}}-
!{{!}}Status
!{{!}}When
!{{!}}Returns
{{!}}-
{{!}}{{!}}resolved
{{!}}{{!}}Language successfully changed
{{!}}{{!}} n/a
{{!}}-
{{!}}{{!}}rejected
{{!}}{{!}}No language code is provided
{{!}}{{!}}No language code provided
{{!}}-
{{!}}{{!}}rejected
{{!}}{{!}}No matching language code is specified in your language pack
{{!}}{{!}}No matching language code found in language pack
{{!}}}

===closeAll===
Publishes the 'App.closeAll' event that requests all widgets to close.

====Example====
<source lang="javascript">
oMyPlugin.command('App.closeAll').done(function(e){

// App closed all successfully

}).fail(function(e){

// App failed to close all
});
</source>

====Resolutions====
{{{!}} class="wikitable"
{{!}}-
!{{!}}Status
!{{!}}When
!{{!}}Returns
{{!}}-
{{!}}{{!}}resolved
{{!}}{{!}}Always
{{!}}{{!}} n/a
{{!}}-
{{!}}{{!}}rejected
{{!}}{{!}}Never
{{!}}{{!}} n/a
{{!}}}

===updateAJAXHeader===
'''Introduced: 9.0.002.06'''

Updates the Authorization header.

====Example====
_genesys.widgets.bus.command('App.updateAJAXHeader', {header:

{'Authorization': 'value'}

});

====Resolutions====
{{{!}} class="wikitable"
!Status
!When
!Returns
{{!}}-
{{!}}resolved
{{!}}Header is updated
{{!}}n/a
{{!}}-
{{!}}rejected
{{!}}Never
{{!}}No request header found
{{!}}}

===removeAJAXHeader===
'''Introduced: 9.0.002.06'''

Removes the set Authorization header.

====Example====
_genesys.widgets.bus.command('App.removeAJAXHeader');

====Resolutions====
{{{!}} class="wikitable"
!Status
!When
!Returns
{{!}}-
{{!}}resolved
{{!}}Always
{{!}}n/a
{{!}}}

===registerExtension===
'''Introduced: 9.0.002.06'''

Allows you to register and initialize new extensions at runtime instead of predefining extensions before Genesys Widgets starts up.

====Options====
{{{!}} class="wikitable"
!Option
!Type
!Description
{{!}}-
{{!}}undefined
{{!}}function
{{!}}Your extension function. Receives the following arguments: $ (jQuery), CXBus, Common
{{!}}}

====Resolutions====
{{{!}} class="wikitable"
!Status
!When
!Returns
{{!}}-
{{!}}resolved
{{!}}Valid 'extension' object provided
{{!}}n/a
{{!}}-
{{!}}rejected
{{!}}Invalid 'extension' option provided
{{!}}n/a
{{!}}}

===registerAutoLoad===
(For use with lazy loading only) Allows you to register a plugin into the {{Link-SomewhereInThisVersion|manual=SDK|topic=App-combined|anchor=MP|display text=preload plugins array}} so that it can be pre-loaded at the startup rather than lazy loading later. This can be useful when there is an active session maintained by your Widget and you would like to show it immediately at startup during page refresh or navigating across pages.
<source lang="javascript">Note: This command is intended for use when running widgets in lazy loading mode.
You may also use this to register and pre-load your own custom-made plugins.</source>

====Options====
{{{!}} class="wikitable"
!Option
!Type
!Description
{{!}}-
{{!}}name
{{!}}string
{{!}}The name of the plugin that needs to be registered for auto loading.
{{!}}}

====Resolutions====
{{{!}} class="wikitable"
!Status
!When
!Returns
{{!}}-
{{!}}resolved
{{!}}A plugin is added into the preload list
{{!}}n/a
{{!}}-
{{!}}rejected
{{!}}Never
{{!}}n/a
{{!}}}

===deregisterAutoLoad===
(For use with lazy loading only) Allows you to de-register a plugin from the {{Link-SomewhereInThisVersion|manual=SDK|topic=App-combined|anchor=MP|display text=preload plugins array}} so that it will not be pre-loaded at startup. This can be useful when there is no more active session maintained by your Widget and you don't want to show it on the screen immediately at startup.
<source lang="javascript">Note: This command is intended for use when running widgets in lazy loading mode.
You may also use this to de-register your own custom-made plugins.</source>

====Options====
{{{!}} class="wikitable"
!Option
!Type
!Description
{{!}}-
{{!}}name
{{!}}string
{{!}}The name of the plugin that needs to be de-registered from auto loading.
{{!}}}

====Resolutions====
{{{!}} class="wikitable"
!Status
!When
!Returns
{{!}}-
{{!}}resolved
{{!}}A plugin is removed from the preload list
{{!}}n/a
{{!}}-
{{!}}rejected
{{!}}Never
{{!}}n/a
{{!}}}
<br />
|Status=No
}}{{Section
|sectionHeading=API Events
|alignment=Vertical
|structuredtext=Once you've registered your plugin on the bus, you can subscribe to and listen for published events. Here's how to use the global bus object to register a new plugin on the bus.

{{NoteFormat|The global bus object is a debugging tool. When implementing Widgets on your own site, do not use the global bus object to register your custom plugins. Instead, see {{Link-SomewhereInThisManual|topic=GWCBusExtensions|display text=Widgets Extensions}} for more information about extending Genesys Widgets.|1}}

<source lang="javascript">var oMyPlugin = window._genesys.widgets.bus.registerPlugin('MyPlugin');

oMyPlugin.subscribe('App.ready', function(e){});</source>
{{{!}} class="wikitable"
{{!}}-
!{{!}}Name
!{{!}}Description
!{{!}}Data
{{!}}-
{{!}}{{!}}ready
{{!}}{{!}}CallUs is initialized and ready to accept commands.
{{!}}{{!}}
{{!}}-
{{!}}{{!}}i18n
{{!}}{{!}}Published when the language for Genesys Widgets is changed or is being set for the first time.
{{!}}{{!}}'(language code)'
{{!}}-
{{!}}{{!}}theme
{{!}}{{!}}Published when the theme for Genesys Widgets is changed or is being set for the first time.
{{!}}{{!}}{theme: '(theme CSS classname)'}
{{!}}-
{{!}}{{!}}timeFormat
{{!}}{{!}}Published when the time format for Genesys Widgets is changed or is being set for the first time.
{{!}}{{!}}{timeFormat: iTimeFormat}
{{!}}}
|Status=No
}}
}}

WID/Current/SDK/GWCBusAPIOverview

2020-10-27T18:49:38Z

Chrissyforrest: Published

{{Article
|Standalone=No
|DisplayName=Widgets Bus API overview
|TocName=Widgets Bus API overview
|Context=Learn about the bus that all widgets components are built on.
|ComingSoon=No
|Platform=GenesysEngage-cloud
|Role=Developer
|Section={{Section
|sectionHeading=Overview
|anchor=Overview
|alignment=Vertical
|structuredtext=Genesys Widgets is built on top of the CXBus messaging bus. CXBus uses the {{#Widget:ExtLink|link=https://en.wikipedia.org/wiki/Publish–subscribe_pattern|displaytext=publish-subscribe}} model to facilitate communication between the Widgets components, all of which are ''plugins'' that can both ''publish'' events on the bus and ''subscribe'' to the events they are interested in.

With the help of the Widgets-Core plugins, CXBus makes it possible to combine the logic implemented by user interface plugins, service plugins, and utility plugins into cohesive products that can provide chat sessions, schedule callbacks, and so on.

Publications and subscriptions are loosely bound so that you can publish and subscribe to any event without that event explicitly being available. This allows for plugins to lazy load into the bus or provide conditional logic in your plugins so they can wait for other plugins to be available.

CXBus events and commands are executed asynchronously using deferred methods and promises. This allows for better performance and standardized Pass/Fail handling for all commands. Command promises are not resolved until the command is finished, including any nested asynchronous commands that command may invoke. This gives you assurance that the command completed successfully and the timing of your follow-up action will occur at the right time. As for permissions, CXBus provides metadata in every command call including which plugin called the command and at what time. This allows for plugins to selectively allow/deny invocation of commands.

You can use three methods to access the Bus:

*Global access
*Genesys Widgets onReady callback
*Extensions

===Global access===
====QuickBus====
<tt>window._genesys.widgets.bus</tt><br />For quick access to call commands on the bus, you can access the '''QuickBus''' instance after Genesys Widgets loads. QuickBus is a CXBus plugin that is exposed globally for your convenience. Typical use cases for using QuickBus are for debugging or calling a command when a link or button is clicked. Instead of creating your own plugin, you can use QuickBus to add the click handler inline in your HTML.<br />Example:
<source lang="javascript">
<a href="#" onclick="_genesys.widgets.bus.command('WebChat.open');">Open WebChat</a>
</source>
====Global CXBus====
CXBus is available as a global instance named "CXBus" (or window.CXBus). Unlike QuickBus, this is not a plugin but CXBus itself.
<br />CXBus has been updated to include a "command" method that allows you to execute a command directly from the CXBus instance.
<br />Example:
<source lang="javascript">
CXBus.command("WebChat.open");
</source>You can use this, like QuickBus, for debugging or setting up click events.
===Genesys Widgets onReady callback===
Genesys Widgets provides an "onReady" callback function that you can define in your configuration. This will be triggered after Genesys Widgets initializes. QuickBus is provided as an argument in this function, but you may also access CXBus globally in your function.

<source lang="javascript">
window._genesys.widgets.onReady = function(QuickBus){

// Use the QuickBus plugin provided here to interface with the bus
// QuickBus is analogous to window._genesys.widgets.bus
};
</source>
===Extensions===
You can define your own plugins/widgets that interface with Genesys Widgets. For more information, please see {{Link-SomewhereInThisVersion|manual=SDK|topic=GWCBusExtensions|display text=Genesys Widgets extensions}}.
|Status=No
}}{{Section
|sectionHeading=CXBus Reference
|anchor=CXBusReference
|alignment=Vertical
|structuredtext=The CXBus instance is exposed globally (window.CXBus) and has several methods available:

*CXBus.command
*CXBus.configure
*CXBus.loadFile
*CXBus.loadPlugin
*CXBus.registerPlugin

===CXBus.command===
Calls a command on the bus under the namespace "CXBus". Use this to quickly and easily call commands without needing to generate a unique plugin interface object first.
====Example====
<source lang="javascript">
CXBus.command("WebChat.open", {});
</source>
====Arguments====

{{{!}} class="wikitable"
{{!}}-
!{{!}}Name
!{{!}}Type
!{{!}}Description
{{!}}-
{{!}}{{!}}Command name
{{!}}{{!}}string
{{!}}{{!}}The name of the command you wish to execute.
{{!}}-
{{!}}{{!}}Command options
{{!}}{{!}}object
{{!}}{{!}}Optional: You may pass an object containing properties that the command will accept. Refer to the documentation on each command to see what options are available.
{{!}}}

====Returns====
Always returns a promise. You can define done(), fail(), or always() callbacks for every command.
===CXBus.configure===
Allows you to change configuration options for CXBus.
====Example====
<source lang="javascript">
CXBus.configure({debug: true, pluginsPath: "/js/widgets/plugins/"});
</source>
====Arguments====

{{{!}} class="wikitable"
{{!}}-
!{{!}}Name
!{{!}}Type
!{{!}}Description
{{!}}-
{{!}}{{!}}Configuration options
{{!}}{{!}}object
{{!}}{{!}}An object containing properties, similar to command options. In this object you can change configuration options for CXBus.
{{!}}}

====Configuration options====
{{{!}} class="wikitable"
{{!}}-
!{{!}}Name
!{{!}}Type
!{{!}}Description
{{!}}-
{{!}}{{!}}debug
{{!}}{{!}}boolean
{{!}}{{!}}Enable or disable CXBus logging in the javascript console. Set to '''true''' to enable; set to '''false''' to disable. Default value is '''false'''.
{{!}}-
{{!}}{{!}}pluginsPath
{{!}}{{!}}string
{{!}}{{!}}The location of the Genesys Widgets "plugins" folder.
'''Example''': "/js/widgets/plugins/"
The default value here is "". This configuration option is used for lazy loading plugin files. Be sure to configure this option when using Genesys Widgets in lazy loading mode.
{{!}}-
{{!}}{{!}}pluginMap
{{!}}{{!}}object
{{!}}{{!}}Used to change the target JS file for each plugin or to add a new plugin.

'''Example''':
{sendmessage: "<nowiki>https://www.yoursite.com/plugins/custom-sendmessage.js</nowiki>"}
CXBus will automatically lazy load plugins defined in this object when something tries to call a command on that plugin.

For instance, if SendMessage.open is called and '''SendMessage''' isn't loaded, CXBus will fetch it from the default "plugins/" folder. If you want to load a different '''SendMessage''' widget, you can override the default URL of the JS file associated with "sendmessage".

You can also prevent a plugin from loading by mapping it to '''false'''.

'''Example''':
{sendmessage: false}{{NoteFormat|
* Any number of plugins can be included in this object.
* Only works when using the lazy-loading method of initializing Widgets.
*Not intended to be used to load different versions of Genesys Widgets plugins.}}
{{!}}}

====Returns====
This method returns nothing.
===CXBus.loadFile===
Loads any javascript file.
====Example====
<source lang="javascript">
CXBus.loadFile("/js/widgets/plugins/webchat.min.js");
</source>
====Arguments====

{{{!}} class="wikitable"
{{!}}-
!{{!}}Name
!{{!}}Type
!{{!}}Description
{{!}}-
{{!}}{{!}}File path
{{!}}{{!}}string
{{!}}{{!}}Loads a javascript file based on the file path specified.
{{!}}}

====Returns====
Always returns a promise. You can define done(), fail(), or always() callbacks.
When the file loads successfully, done() will be triggered.
When the file fails to load, fail() will be triggered.
===CXBus.loadPlugin===
Loads a plugin file from the configured "plugins" folder.
====Example====
<source lang="javascript">
CXBus.loadPlugin("webchat");
</source>
====Arguments====

{{{!}} class="wikitable"
{{!}}-
!{{!}}Name
!{{!}}Type
!{{!}}Description
{{!}}-
{{!}}{{!}}Plugin name
{{!}}{{!}}string
{{!}}{{!}}Loads a plugin from the "plugins" folder by name (configured by the "pluginsPath" option). Plugin names match their CXBus namespaces but are lowercase. <br />Example: To load WebChat, use "webchat". <br />You can refer to the files inside the "plugins" folder as well. The first part of the file name will be the name you use with this function. <br />Example: Use "webchat" to load "webchat.min.js".
{{!}}}

====Returns====
Always returns a promise. You can define done(), fail(), or always() callbacks.
When the plugin loads successfully, done() will be triggered.
When the plugin fails to load, fail() will be triggered.
===CXBus.registerPlugin===
Registers a new plugin namespace on the bus and returns a plugin interface object. You will use the plugin interface object to publish, subscribe, call commands, and perform other CXBus functions.
====Example====
<source lang="javascript">
var oMyNewPlugin = CXBus.registerPlugin("MyNewPlugin");
</source>
====Arguments====

{{{!}} class="wikitable"
{{!}}-
!{{!}}Name
!{{!}}Type
!{{!}}Description
{{!}}-
{{!}}{{!}}CXBus plugin namespace
{{!}}{{!}}string
{{!}}{{!}}The namespace you want to reserve for your plugin.
{{!}}}

====Returns====
If the namespace is not already taken, it will return a CXBus plugin interface object configured with the selected namespace.
If the namespace is already taken, it will return false.
|Status=No
}}{{Section
|sectionHeading=CXBus Plugin Interface Reference
|anchor=CXBusPluginInterfaceReference
|alignment=Vertical
|structuredtext=When you register a plugin using CXBus.registerPlugin(), it returns a CXBus Plugin Interface Object. This object contains many methods that allow you to interact with other plugins on the bus.

Let's start with the assumption that we've created the below plugin interface:

<source lang="javascript">
var oMyNewPlugin = CXBus.registerPlugin("MyNewPlugin");
</source>

===oMyNewPlugin.registerCommand===
Allows you to register a new command on the bus for other plugins to use.
====Example====
<source lang="javascript">
oMyNewPlugin.registerCommand("test", function(e){

console.log("'MyNewPlugin.test' command was called", e)

e.deferred.resolve();
});
</source>
====Arguments====
{{{!}}
{{!}}-
!Name
!Type
!Description
{{!}}-
{{!}}Command name
{{!}}string
{{!}}The name you want for this command. When other plugins call your command, they must specify the namespace as well.<br />Example: "test" is called on the bus as "MyNewPlugin.test".
{{!}}-
{{!}}Command function
{{!}}function
{{!}}The command function that is executed when the command is called. This function is provided an '''Event Object''' that contains metadata and any options passed in.
{{!}}-
{{!}}}
====Event object====
{{{!}}
{{!}}-
!Name
!Type
!Description
{{!}}-
{{!}}time
{{!}}number (integer time)
{{!}}The time the command was called.
{{!}}-
{{!}}commander
{{!}}string
{{!}}The name of the plugin that called your command. Example: If your plugin called a command, the value would be "MyNewPlugin". <br /> You can use this information to create plugin-specific logic in your command.
{{!}}-
{{!}}command
{{!}}string
{{!}}The name of this command. Example: "MyNewPlugin.test". <br />This can be useful if you are using the same function for multiple commands and need to identify which command was called.
{{!}}-
{{!}}deferred
{{!}}deferred promise object
{{!}}When a command is called, a promise is generated. You must resolve this promise in your command without exception. Either execute e.deferred.resolve() or e.deferred.reject().<br />You may pass values back through these methods. If you pass a value back inside reject() it will be printed in the console as an error log automatically.
{{!}}-
{{!}}data
{{!}}object
{{!}}This is the object containing command options passed in when the command was called. If no options were passed, this will default to an empty object.
{{!}}-
{{!}}}
====Returns====
Returns true.
===oMyNewPlugin.registerEvents===
Registering events is a formality that allows CXBus to keep a registry of all possible events. You don't need to register events before publishing them, but it's a best practice to always register events.
====Example====
<source lang="javascript">
oMyNewPlugin.registerEvents(["ready", "testEvent"]);
</source>
====Arguments====
{{{!}}
{{!}}-
!Name
!Type
!Description
{{!}}-
{{!}}Event name array
{{!}}array
{{!}}An array of event names.
{{!}}-
{{!}}}
====Returns====
Returns true if at least one value event was included in the array.
Returns false if no events are included in the array or no array is passed in.
===oMyNewPlugin.subscribe===

Subscribes your plugin to an event on the bus with a callback function. When the event is published, the callback function is executed. You can subscribe to any event, even if the event does not exist. This allows for binding events that may come in the future.

====Example====
<source lang="javascript">
oMyNewPlugin.subscribe("WebChat.opened", function(e){

// e = Event Object. Contains metadata and attached data
//
// Example Event Object data:
//
// e.time == 1532017560154
// e.event == "WebChat.opened"
// e.publisher == "WebChat"
});
</source>
====Arguments====
{{{!}}
{{!}}-
!Name
!Type
!Description
{{!}}-
{{!}}Event name
{{!}}string
{{!}}The name of the event you want to subscribe to. Must include the plugin's namespace.
{{!}}-
{{!}}Callback function
{{!}}function
{{!}}A function to execute when the event is published. An Event Object is passed into this function that gives you access to metadata and attached data.
{{!}}-
{{!}}}
====Event object====
{{{!}}
{{!}}-
!Name
!Type
!Description
{{!}}-
{{!}}time
{{!}}number (integer time)
{{!}}The time the event was published.
{{!}}-
{{!}}event
{{!}}string
{{!}}The name of the event, including namespace. That can be useful if you are using the same function to handle multiple events.
{{!}}-
{{!}}publisher
{{!}}string
{{!}}The namespace of the plugin that published the event.
{{!}}-
{{!}}}
====Returns====
Returns the name of the event back to you if the subscription was successful.
Returns false if you did not specify an event and/or a callback function.
===oMyNewPlugin.publish===
Publishes an event on the bus under your plugin's namespace.
====Example====
<source lang="javascript">
// Publishes the event "MyNewPlugin.testEvent" with attached data {test: "123"}
oMyNewPlugin.publish("testEvent", {test: "123"});
</source>
====Arguments====
{{{!}}
{{!}}-
!Name
!Type
!Description
{{!}}-
{{!}}Event name
{{!}}string
{{!}}The name of the event you want to publish. Do not include the plugin namespace.
{{!}}-
{{!}}Attached data
{{!}}object
{{!}}An object of arbitrary properties you can attach to your event.
{{!}}-
{{!}}}
====Returns====
Always returns true.
===oMyNewPlugin.republish===
A special method of publishing intended for one-off events like "ready". In some cases, an event will fire only once. If a plugin is loaded at a later time that needs to subscribe to this event, it will never get it because it will never be published again. To solve this problem, the "republish" method will automatically republish an event to new subscribers as soon as they subscribe to it.

In Genesys Widgets, every plugin publishes a "ready" event. This event is published using "republish" so that any plugin loaded and/or initialized after can still receive the event.

It is important that you only use "republish" for events that publish once. Using republish multiple times for the same event can cause unwanted behavior.

Genesys Widgets plugins all publish a "ready" event. This is not related to the CXBus plugin interface object's "ready()" method. Calling oMyNewPlugin.ready() will not publish any events.
====Example====
<source lang="javascript">
oMyNewPlugin.republish("ready", {...});
</source>
====Arguments====
{{{!}}
{{!}}-
!Name
!Type
!Description
{{!}}-
{{!}}Event name
{{!}}string
{{!}}The name of the event you want to have republished. Do not include the plugin namespace.
{{!}}-
{{!}}Attached data
{{!}}object
{{!}}An object of arbitrary properties you can attach to your event.
{{!}}-
{{!}}}
====Returns====
Always returns true.
===oMyNewPlugin.publishDirect===
A slight variation on "publish", this method will only publish an event on the bus if it has subscribers. The intention of this method is to avoid spamming the logs with events that no plugins are listening to. In particular, if you have an event that publishes frequently or on an interval, "publishDirect" may be used to minimize its impact on logs in the console.
====Example====
<source lang="javascript">
oMyNewPlugin.publishDirect("poll", {...});
</source>
====Arguments====
{{{!}}
{{!}}-
!Name
!Type
!Description
{{!}}-
{{!}}Event name
{{!}}string
{{!}}The name of the event you want to have republished. Do not include the plugin namespace.
{{!}}-
{{!}}Attached data
{{!}}object
{{!}}An object of arbitrary properties you can attach to your event.
{{!}}-
{{!}}}
====Returns====
Always returns true.
===oMyNewPlugin.command===
Have your plugin call a command on the bus.
====Example====
<source lang="javascript">
oMyNewPlugin.command("WebChat.open", {...}).done(function(e){

// If command succeeds
// e == any returned data

}).fail(function(e){

// If command fails
// e == any returned data

}).always(function(){

// Always executed
});
</source>
====Arguments====
{{{!}}
{{!}}-
!Name
!Type
!Description
{{!}}-
{{!}}Command name
{{!}}string
{{!}}Name of the command you wish to call.
{{!}}-
{{!}}Command options
{{!}}string
{{!}}Optional: An object containing properties the command will use in its execution. Refer to plugin references for a list of options available for each command.
{{!}}-
{{!}}}
====Returns====
Always returns a promise. You can define done(), fail(), or always() callbacks for every command.
===oMyNewPlugin.before===
Allows you to interrupt a registered command on the bus with your own "before" function. You may modify the command options before they're passed to the command, you may trigger some action before the command is executed, or you can cancel the command before it executes.

You may specify more than one "before" function for a command. If you do, they will be executed in a chain where the output of the previous function becomes the input for the next function.
You cannot remove "before" functions once they have been added.
====Example====
<source lang="javascript">
oMyNewPlugin.before("WebChat.open", function(oData){

// oData == the options passed into the command call
// e.g. if this command is called: oMyPlugin.command("WebChat.open", {form: {firstname: "Mike"
// then oData will == {form: {firstname: "Mike"
// You must return oData back, or an empty object {} for execution to continue.
// If you return false|undefined|null or don't return anything, execution of the command will be stopped
return oData;
});
</source>

====Arguments====
{{{!}}
{{!}}-
!Name
!Type
!Description
{{!}}-
{{!}}Command name
{{!}}string
{{!}}Name of the function you want to interrupt with your "before" function.
{{!}}-
{{!}}"before" function
{{!}}function
{{!}}A function that accepts command options (oData in above example). If you want the command to continue executing, you must return the oData object. If you want to cancel the command, return '''false''' or '''undefined''' or don't return anything. You may modify the contents of oData before it is sent to the command. This allows you to override command options or add on dynamic options depending on external conditions.
{{!}}-
{{!}}}
====Returns====
Returns true when you pass a properly formatted command name (e.g. "PluginName.commandName").
Returns false when you pass an improperly formatted command name.
===oMyNewPlugin.registry===
Returns the CXBus Registry lookup table.
====Example====
<source lang="javascript">
oMyNewPlugin.registry();
</source>
====Arguments====
No arguments.
====Returns====
Returns the internal CXBus registry that tracks all plugins, their commands, and their events.
<br />
Registry Structure Example:
<source lang="javascript">
{
"Plugin1": {

commands: ["command1", "command2"],
events: ["event1", "event2"]
},

"Plugin2": {

commands: ["command1", "command2"],
events: ["event1", "event2"]
}
}
</source>

===oMyNewPlugin.subscribers===
Returns a list of events and their subscribers.
====Example====
<source lang="javascript">
oMyNewPlugin.subscribers();
</source>
====Arguments====
No arguments.
====Returns====
Returns an object identifying a list of events being subscribed to, and a list of plugin names subscribed to each event.

Example of WebChatService's subscribers:
<source lang="javascript">

// Format {"eventname": ["subscriber1", "subscriber2"]}

{
"WebChatService.agentConnected":["WebChat"],
"WebChatService.agentDisconnected":["WebChat"],
"WebChatService.ready":[],
"WebChatService.started":["WebChat"],
"WebChatService.restored":["WebChat"],
"WebChatService.clientDisconnected":[],
"WebChatService.clientConnected":[],
"WebChatService.messageReceived":["WebChat"],
"WebChatService.error":["WebChat"],
"WebChatService.restoreTimeout":["WebChat"],
"WebChatService.restoreFailed":["WebChat"],
"WebChatService.ended":["WebChat"],
"WebChatService.agentTypingStarted":["WebChat"],
"WebChatService.agentTypingStopped":["WebChat"],
"WebChatService.restoredOffline":["WebChat"],
"WebChatService.chatServerWentOffline":["WebChat"],
"WebChatService.chatServerBackOnline":["WebChat"],
"WebChatService.disconnected":["WebChat"],
"WebChatService.reconnected":["WebChat"]
}
</source>

===oMyNewPlugin.namespace===
Returns your plugin's namespace.
====Example====
<source lang="javascript">
oMyNewPlugin.namespace();
</source>
====Arguments====
No arguments.
====Returns====
Returns your plugin's namespace. If your plugin's namespace is "MyNewPlugin", it will return "MyNewPlugin".
===oMyNewPlugin.ready===
Marks your plugin as ready to have its commands called. This method is required to be called for all plugins. You should call this method after all your commands are registered, initialization code is finished, and configuration has completed. Failure to call this method will result in your commands being unexecutable.
====Example====
<source lang="javascript">
oMyNewPlugin.ready();
</source>
====Arguments====
No arguments.
====Returns====
Returns nothing.
|Status=No
}}
}}

WID/Current/SDK/GWCBusExtensions

2020-10-27T18:46:39Z

Chrissyforrest: Published

{{Article
|Standalone=No
|DisplayName=Genesys Widgets extensions
|TocName=Genesys Widgets extensions
|Context=Learn how to create your own plugins and widgets.
|ComingSoon=No
|Platform=GenesysEngage-cloud
|Role=Developer
|Section={{Section
|sectionHeading=Overview
|alignment=Vertical
|structuredtext=Genesys Widgets allows you to create your own plugins and widgets. These extensions are an easy way to define your own functionality, while using the same resources as the core Genesys Widgets.
|Status=No
}}{{Section
|sectionHeading=Defining extensions
|alignment=Vertical
|structuredtext=Extensions are defined at runtime before Genesys Widgets loads. You can define them inline or include extensions in separate files, either grouped or separated.

{{NoteFormat|Define/include your extensions after your Genesys Widgets configuration object but before you include the Genesys Widgets JavaScript package.|}}

<source lang="javascript">
<script>

if(!window._genesys.widgets.extensions){

window._genesys.widgets.extensions = {};
}

window._genesys.widgets.extensions["TestExtension"] = function($, CXBus, Common){

var oTestExtension = CXBus.registerPlugin("TestExtension");

oTestExtension.subscribe("WebChat.opened", function(e){});

oTestExtension.publish("ready");

oTestExtension.command("WebChat.open").done(function(e){

// Handle success return state

}).fail(function(e){

// Handle failure return state
});

oTestExtension.registerCommand("demo", function(e){

// Command execution here
});
};

</script>
</source>

Make sure that the "extensions" object exists and always include this at the top of your extension definition.

<source lang="javascript">
if(!window._genesys.widgets.extensions){

window._genesys.widgets.extensions = {};
}
</source>

Create a new named property inside the "extensions" object and define it as a function.
When Genesys Widgets initializes it will step through each extension and invoke each function, initializing them.
Genesys Widgets will share resources as arguments. These include: jQuery, {{Link-SomewhereInThisVersion|manual=SDK|topic=GWCBusAPIOverview|display text=CXBus}}, and the {{Link-SomewhereInThisVersion|manual=SDK|topic=Common|display text=Common}} UI utilities.

<source lang="javascript">
window._genesys.widgets.extensions["TestExtension"] = function($, CXBus, Common){};
</source>
|Status=No
}}{{Section
|sectionHeading=Creating a new CXBus plugin
|alignment=Vertical
|structuredtext=Inside the extension function is where you create a new CXBus plugin. You can use this CXBus plugin to interface with other Genesys Widgets. You can add your own UI controller logic in here or simply use the extension to connect an existing UI controller to the bus (for example, share its API over the bus and coordinate actions with events).

Registering a new plugin on the bus creates a new, unique namespace for all your events and commands.
In this example, the namespace "cx.plugin.TestExtension" is created:

<source lang="javascript">
var oTestExtension = CXBus.registerPlugin("TestExtension");
</source>

{{NoteFormat|When referring to other namespaces, like "cx.plugin.TestExtension", it is not necessary to include the "cx.plugin." prefix. It is optional and implied. You can subscribe to events or call commands using the full or truncated namespace.|}}
|Status=No
}}{{Section
|sectionHeading=Use cases
|alignment=Vertical
|structuredtext=Extensions are like any other Genesys Widget. You can publish, subscribe, call commands, or register your own commands on the bus. You can interface with other widgets on the bus for more complex interactions. The following examples demonstrate how you can make extensions work for you.
===Example: subscribing to an event===
<source lang="javascript">
oTestExtension.subscribe("WebChat.opened", function(e){});
</source>

===Example: publishing an event===
Publishes the event "TestExtension.ready" on the bus.

<source lang="javascript">
oTestExtension.publish("ready", {arbitrary data to include});
</source>
===Example: calling a command===
Commands are deferred functions. You must handle their return states asynchronously.

<source lang="javascript">
oTestExtension.command("WebChat.open", {any options required}).done(function(e){

// Handle success return state
// "e", the event object, is a standard CXBus format
// Any return data will be available under e.data

}).fail(function(e){

// Handle failure return state
// "e", the event object, may contain an error message, warning, or AJAX response object
});
</source>
===Example: registering a command===
Creates a new command under your namespace that you or other widgets can call.

"e", the event object, is a standard CXBus format

*e.data = options passed into command when being called.
*e.commander = the namespace of the widget that called this command.
*e.command = the name of the command being called.
*e.time = timestamp when the command was called.
*e.deferred = the deferred promise created for this command call. You MUST always resolve or reject this promise using e.deferred.resolve() or e.deferred.reject(). You may pass any arbitrary data into either resolution state.

<source lang="javascript">
oTestExtension.registerCommand("demo", function(e){

// Command execution here
});
</source>
===Example: using the 'before()' method===
Allows you to set up an interrupt that is executed before a command every time that command is called.
With this feature, you can link execution of a command with other logic, modify command options before they're used, or cancel execution of a command.

You can specify multiple "before" functions for a single command. They will be executed in order with the output of one providing the input to the next. If one of the functions does not return an object, execution will stop and the command will be cancelled.

<source lang="javascript">
oTestExtension.before("WebChat.open", function(oData){

// oData == the options passed into the command call
// e.g. if this command is called: oMyPlugin.command("WebChat.open", {form: {firstname: "Mike"}});
// then oData will == {form: {firstname: "Mike"}}

// You must return oData back, or an empty object {} for execution to continue.
// If you return false|undefined|null, execution of the command will be stopped
return oData;
});
</source>
|Status=No
}}
}}

WID/Current/SDK/WebChat-combined

2020-10-27T18:40:43Z

Chrissyforrest: Published

{{Article
|Standalone=No
|DisplayName=WebChat
|TocName=WebChat
|Context=Learn how to enable live chats between customers and agents.
|ComingSoon=No
|Platform=GenesysEngage-cloud
|Role=Developer
|Section={{Section
|sectionHeading=Overview
|anchor=overview
|alignment=Horizontal
|Media=Image
|image=WebChat-Main-new.PNG
|structuredtext=The WebChat Widget allows a customer to start a live chat with a customer service agent. The UI appears within the page and follows the customer as they traverse your website. Other features include minimize/maximize, auto-reconnect, and a built-in invite feature.
===Usage===
You can launch WebChat manually by using the following methods:

*Call the '''WebChat.open''' {{Link-SomewhereInThisVersion|manual=SDK|topic=WebChat-combined|anchor=commands|display text=command}}
*Configure {{Link-SomewhereInThisVersion|manual=SDK|topic=ChannelSelector-combined}} to show WebChat as a channel
*Enable the built-in launcher button for WebChat that appears on the right side of the screen
*Create your own custom button or link to open WebChat (using the '''WebChat.open''' {{Link-SomewhereInThisVersion|manual=SDK|topic=WebChat-combined|anchor=commands|display text=command}})

===Customization===
You can customize and {{Link-AnywhereElse|product=WID|version=Current|manual=Developer|topic=GWCInternat|display text=localize}} all of the static text shown in the WebChat Widget by adding entries to your {{Link-SomewhereInThisVersion|manual=SDK|topic=WebChat-combined|anchor=config|display text=configuration}} and {{Link-SomewhereInThisVersion|manual=SDK|topic=WebChat-combined|anchor=localize|display text=localization}} options.

WebChat supports themes. You can create and register your own themes for Genesys Widgets.

<br />
|structuredtextwide====Namespace===
The WebChat plugin has the following namespaces tied to each of the following types:
{{{!}} class="wikitable" style="width: auto;"
{{!}}-
!{{!}}Type
!{{!}}Namespace
{{!}}-
{{!}}{{!}}{{Link-SomewhereInThisVersion|manual=SDK|topic=WebChat-combined|anchor=config|display text=Configuration}}
{{!}}{{!}}webchat
{{!}}-
{{!}}{{!}}i18n—{{Link-SomewhereInThisVersion|manual=SDK|topic=WebChat-combined|anchor=localize|display text=Localization}}
{{!}}{{!}}webchat
{{!}}-
{{!}}{{!}}CXBus—{{Link-SomewhereInThisVersion|manual=SDK|topic=WebChat-combined|anchor=commands|display text=API commands}} & {{Link-SomewhereInThisVersion|manual=SDK|topic=WebChat-combined|anchor=events|display text=API events}}
{{!}}{{!}}WebChat
{{!}}-
{{!}}{{!}}CSS
{{!}}{{!}}.cx-webchat
{{!}}}
===Mobile support===
WebChat supports both desktop and mobile devices. Like all Genesys Widgets, there are two main modes: Desktop & Mobile. Desktop is employed for monitors, laptops, and tablets. Mobile is employed for smartphones. When a smartphone is detected, WebChat switches to special full-screen templates that are optimized for both portrait and landscape orientations.

Switching between desktop and mobile mode is done automatically by default. You may configure Genesys Widgets to switch between Desktop and Mobile mode manually if necessary.
===Screenshots===
'''Dark theme'''

[[File:WebChat_Form_Desktop_Dark.png|150x150px]]
[[File:WebChat_Form_Portrait_Dark.png|150x150px]]
[[File:WebChat_Form_Landscape_Dark.png|150x150px]]
[[File:WebChat_Transcript_Desktop_Dark-without-cobrowse.PNG|201x201px]]
[[File:WebChat Transcript Portrait Dark-without-cobrowse.png|267x267px]]
[[File:WebChat Transcript Landscape Dark without-cobrowse.png|150x150px]]

'''Light theme'''

[[File:WebChat_Form_Desktop_Light.png||150x150px]]
[[File:WebChat_Form_Portrait_light.png|150x150px]]
[[File:WebChat_Form_Landscape_light.png|150x150px]]
[[File:WebChat_Transcript_Desktop_light-without-cobrowse.PNG|202x202px]]
[[File:WebChat Transcript Portrait Light without cobrowse.png|267x267px]]
[[File:WebChat Transcript Landscape Light without cobrowse.png|150x150px]]
|Status=No
}}{{Section
|sectionHeading=Configuration
|anchor=config
|alignment=Vertical
|structuredtext=WebChat and WebChatService share the '''_genesys.widgets.webchat''' configuration namespace. WebChat has UI options while WebChatService has connection options.
{{AnchorDiv|example}}
===Example===

<pre>
window._genesys.widgets.webchat = {

apikey: 'n3eNkgLLgLKXREBMYjGm6lygOHHOK8VA',
dataURL: 'https://api.genesyscloud.com/gms-chat/2/chat',
userData: {},
emojis: true,
uploadsEnabled: false,
confirmFormCloseEnabled: true,
actionsMenu: true,
maxMessageLength: 140,

autoInvite: {

enabled: false,
timeToInviteSeconds: 10,
inviteTimeoutSeconds: 30
},

chatButton: {

enabled: true,
template: '<div class="cx-widget cx-webchat-chat-button cx-side-button" role="button"
tabindex="0" data-message="ChatButton" data-gcb-service-node="true"><span class="cx-icon" data-icon="chat">
</span><span class="i18n cx-chat-button-label" data-message="ChatButton"></span></div>',
effect: 'fade',
openDelay: 1000,
effectDuration: 300,
hideDuringInvite: true
},

minimizeOnMobileRestore: false,

ariaIdleAlertIntervals:[50,25,10],

ariaCharRemainingIntervals:[75, 25, 10]
};
</pre>{{AnchorDiv|options}}
===Options===

{{{!}} class="wikitable"
{{!}}-
!{{!}}Name
!{{!}}Type
!{{!}}Description
!{{!}}Default
!{{!}}Required
!{{!}}Introduced/Updated
{{!}}-
{{!}}{{!}}emojis
{{!}}{{!}}boolean
{{!}}{{!}}Enable/disable Emoji menu inside chat message input. Emojis are supported using unicode characters and the list includes ☺ U+263A (smile), 👍 U+1F44D (thumbs up) and ☹ U+2639 (sad).
{{!}}{{!}}false
{{!}}{{!}}n/a
{{!}}{{!}}
{{!}}-
{{!}}{{!}}form
{{!}}{{!}}object
{{!}}{{!}}A JSON object containing a custom registration form definition. The JSON definition placed here becomes the default registration form layout for WebChat. See {{Link-SomewhereInThisVersion|manual=SDK|topic=WebChat-combined|anchor=ccrf|display text=Customizable Chat Registration Form}}.
{{!}}{{!}}A basic registration form is defined internally by default
{{!}}{{!}}n/a
{{!}}{{!}}
{{!}}-
{{!}}{{!}}uploadsEnabled
{{!}}{{!}}boolean
{{!}}{{!}}Show/Hide the Send File button. The button will be shown if the value is set to true.
{{!}}{{!}}false
{{!}}{{!}}n/a
{{!}}{{!}}
{{!}}-
{{!}}{{!}}confirmFormCloseEnabled
{{!}}{{!}}boolean
{{!}}{{!}}Enable or disable displaying a confirmation message before closing WebChat if information has been entered into the registration form.
{{!}}{{!}}true
{{!}}{{!}}n/a
{{!}}{{!}}
{{!}}-
{{!}}{{!}}timeFormat
{{!}}{{!}}number/string
{{!}}{{!}}This sets the time format for the timestamps in this widget. It can be 12 or 24.
{{!}}{{!}}12
{{!}}{{!}}false
{{!}}{{!}}
{{!}}-
{{!}}{{!}}actionsMenu
{{!}}{{!}}boolean
{{!}}{{!}}Enable/disable actions menu next to chat message input.
{{!}}{{!}}true
{{!}}{{!}}n/a
{{!}}{{!}}
{{!}}-
{{!}}{{!}}maxMessageLength
{{!}}{{!}}number
{{!}}{{!}}Set a character limit that the user can input into the message area during a chat. When max is reached, user cannot type any more.
{{!}}{{!}}500
{{!}}{{!}}n/a
{{!}}{{!}}
{{!}}-
{{!}}{{!}}charCountEnabled
{{!}}{{!}}boolean
{{!}}{{!}}Show/Hide the number of characters remaining in the input message area while the user is typing.
{{!}}{{!}}false
{{!}}{{!}}n/a
{{!}}{{!}}
{{!}}-
{{!}}{{!}}autoInvite.enabled
{{!}}{{!}}boolean
{{!}}{{!}}Enable/disable auto-invite feature. Automatically invites user to chat after user idles on page for preset time.{{NoteFormat|When running Widgets in lazy load mode, this option requires that you {{Link-SomewhereInThisVersion|manual=SDK|topic=App-combined|anchor=MP|display text=pre-load}} the WebChat plugin. |1}}
{{!}}{{!}}false
{{!}}{{!}}n/a
{{!}}{{!}}
{{!}}-
{{!}}{{!}}autoInvite.timeToInviteSeconds
{{!}}{{!}}number
{{!}}{{!}}Number of seconds of idle time before inviting customer to chat.
{{!}}{{!}}5
{{!}}{{!}}n/a
{{!}}{{!}}
{{!}}-
{{!}}{{!}}autoInvite.inviteTimeoutSeconds
{{!}}{{!}}number
{{!}}{{!}}Number of seconds to wait, after showing invite, before closing chat invite.
{{!}}{{!}}30
{{!}}{{!}}n/a
{{!}}{{!}}
{{!}}-
{{!}}{{!}}chatButton.enabled
{{!}}{{!}}boolean
{{!}}{{!}}Enable/disable chat button on screen.{{NoteFormat|When running Widgets in lazy load mode, this option requires that you {{Link-SomewhereInThisVersion|manual=SDK|topic=App-combined|anchor=MP|display text=pre-load}} the WebChat plugin. |1}}
{{!}}{{!}}false
{{!}}{{!}}n/a
{{!}}{{!}}
{{!}}-
{{!}}{{!}}chatButton.template
{{!}}{{!}}string
{{!}}{{!}}Custom HTML string template for chat button.
{{!}}{{!}}<source lang="javascript"><div class="cx-widget cx-webchat-chat-button
cx-side-button" role="button" tabindex="0"
data-message="ChatButton"
data-gcb-service-node="true"><span
class="cx-icon" data-icon="chat">
</span><span class="i18n cx-chat-button-label"
data-message="ChatButton"></span></div>
</source>
{{!}}{{!}}n/a
{{!}}{{!}}
{{!}}-
{{!}}{{!}}chatButton.effect
{{!}}{{!}}string
{{!}}{{!}}Type of animation effect when revealing chat button. 'slide' or 'fade'.
{{!}}{{!}}fade
{{!}}{{!}}n/a
{{!}}{{!}}
{{!}}-
{{!}}{{!}}chatButton.openDelay
{{!}}{{!}}number
{{!}}{{!}}Number of milliseconds before displaying chat button on screen.
{{!}}{{!}}1000
{{!}}{{!}}n/a
{{!}}{{!}}
{{!}}-
{{!}}{{!}}chatButton.effectDuration
{{!}}{{!}}number
{{!}}{{!}}Length of animation effect in milliseconds.
{{!}}{{!}}300
{{!}}{{!}}n/a
{{!}}{{!}}
{{!}}-
{{!}}{{!}}chatButton.hideDuringInvite
{{!}}{{!}}boolean
{{!}}{{!}}When the auto-invite feature is activated, hides the chat button. When invite is dismissed, reveals the chat button again.
{{!}}{{!}}true
{{!}}{{!}}n/a
{{!}}{{!}}
{{!}}-
{{!}}{{!}}ariaIdleAlertIntervals
{{!}}{{!}}array/boolean
{{!}}{{!}}An array containing the intervals as a percentage at which the screen reader will announce the remaining idle time. By default, it is enabled with the following time intervals, and it is customizable according to the user's needs. Configuring a value of 'false' will let the screen reader call out idle time for every change.
{{!}}{{!}}[100, 75, 50, 25, 10]
{{!}}{{!}}n/a
{{!}}{{!}}9.0.016.11
{{!}}-
{{!}}{{!}}ariaCharRemainingIntervals
{{!}}{{!}}array/boolean
{{!}}{{!}}An array containing the intervals as a percentage at which the screen reader will announce the remaining characters when the user inputs text into the message area. By default, it is enabled with the following intervals, and it is customizable according to the user needs. Configuring a value of 'false' will let the screen reader call out remaining characters for every change.
{{!}}{{!}}[50, 25, 10]
{{!}}{{!}}n/a
{{!}}{{!}}9.0.016.11
{{!}}}
|Status=No
}}{{Section
|sectionHeading=Localization
|anchor=localize
|alignment=Vertical
|structuredtext=You can define string key names and values to match the system messages that are received from the chat server. If a customer system message is received as '''SYS001''' in the message body, Webchat checks to determine if any keys match in the language pack, and then replaces the message body accordingly. '''SYS001''' is an example format. There are no format restrictions on custom message keys. The purpose of this feature is to allow localization for the User Interface and Server to be kept in the same file.

===Special values for localization===

You can inject the <tt><%Agent%></tt> special value. When used, the agent's name is rendered in its place at runtime.

===Error handling===

Customers can define their own error messages in the '''Errors''' section found in the above Webchat Localization. If no error messages are defined, default error messages are used.

{{NoteFormat|For information on how to set up localization, refer to {{Link-AnywhereElse|product=WID|version=Current|manual=Developer|topic=GWCInternat|display text=Localize widgets and services}}.|1}}
===Usage===

You must use the ''webchat'' namespace for defining localization strings for the WebChat plugin in your i18n JSON file.

The following example shows how to define new strings for the '''en''' (English) language. You can use any language codes you wish; there is no standard format. When selecting the active language in your configuration, you must match one of the language codes defined in your i18n JSON file. Please note that you must only define a language code once in your i18n JSON file. Inside each language object you should define new strings for each widget.

===Inactivity messages===

If Chat Server is configured to end the chat session after a certain idle time, it may send several warning messages to the client to inform them and prompt them to act. Chat Server can be configured to show a first warning, a second warning, and a final notice when it ends the chat session. By default, WebChat will display the warning message text as it is received from the server. If you wish to localize these methods on the client side instead, follow these steps:

The first warning can be localized by setting the string 'IdleMessage1'.

The second warning can be localized by setting the string 'IdleMessage2'.

The final notice can be localized by setting the string 'IdleMessageClose'.

{{NoteFormat|If Chat Server ever allows more than two idle warning messages, you can localize them by incrementing the integer value in the string name (e.g. 'IdleMessage3', 'IdleMessage4', and so on).|2}}

===Default i18n JSON===

<source lang="javascript">
{
"en": {
"webchat": {
"ChatButton": "Chat",
"ChatStarted": "Chat Started",
"ChatEnded": "Chat Ended",
"AgentNameDefault": "Agent",
"AgentConnected": "<%Agent%> Connected",
"AgentDisconnected": "<%Agent%> Disconnected",
"BotNameDefault": "Bot",
"BotConnected": "<%Bot%> Connected",
"BotDisconnected": "<%Bot%> Disconnected",
"SupervisorNameDefault": "Supervisor",
"SupervisorConnected": "<%Agent%> Connected",
"SupervisorDisconnected": "<%Agent%> Disconnected",
"AgentTyping": "...",
"AriaAgentTyping": "Agent is typing",
"AgentUnavailable": "Sorry. There are no agents available. Please try later.",
"ChatTitle": "Live Chat",
"ChatEnd": "X",
"ChatClose": "X",
"ChatMinimize": "Min",
"ChatFormFirstName": "First Name",
"ChatFormLastName": "Last Name",
"ChatFormNickname": "Nickname",
"ChatFormEmail": "Email",
"ChatFormSubject": "Subject",
"ChatFormPlaceholderFirstName": "Required",
"ChatFormPlaceholderLastName": "Required",
"ChatFormPlaceholderNickname": "Optional",
"ChatFormPlaceholderEmail": "Optional",
"ChatFormPlaceholderSubject": "Optional",
"ChatFormSubmit": "Start Chat",
"AriaChatFormSubmit": "Start Chat",
"ChatFormCancel": "Cancel",
"AriaChatFormCancel": "Cancel",
"ChatFormClose": "Close",
"ChatInputPlaceholder": "Type your message here",
"ChatInputSend": "Send",
"AriaChatInputSend": "Send",
"ChatEndQuestion": "Are you sure you want to end this chat session?",
"ChatEndCancel": "Cancel",
"ChatEndConfirm": "End chat",
"AriaChatEndCancel": "Cancel",
"AriaChatEndConfirm": "End chat",
"ConfirmCloseWindow": "Are you sure you want to close chat?",
"ConfirmCloseCancel": "Cancel",
"ConfirmCloseConfirm": "Close",
"AriaConfirmCloseCancel": "Cancel",
"AriaConfirmCloseConfirm": "Close",
"ActionsDownload": "Download transcript",
"ActionsEmail": "Email transcript",
"ActionsPrint": "Print transcript",
"ActionsSendFile": "Attach Files",
"AriaActionsSendFileTitle": "Opens a file upload dialog",
"ActionsEmoji": "Send Emoji",
"ActionsVideo": "Invite to Video Chat",
"ActionsTransfer": "Transfer",
"ActionsInvite": "Invite",
"InstructionsTransfer": "Open this link on another device to transfer your chat session</br></br><%link%>",
"InstructionsInvite": "Share this link with another person to add them to this chat session</br></br><%link%>",
"InviteTitle": "Need help?",
"InviteBody": "Let us know if we can help out.",
"InviteReject": "No thanks",
"InviteAccept": "Start chat",
"AriaInviteAccept": "Start chat",
"AriaInviteReject": "No thanks",
"ChatError": "There was a problem starting the chat session. Please retry.",
"ChatErrorButton": "OK",
"AriaChatErrorButton": "OK",
"ChatErrorPrimaryButton": "Yes",
"ChatErrorDefaultButton": "No",
"AriaChatErrorPrimaryButton": "Yes",
"AriaChatErrorDefaultButton": "No",
"DownloadButton": "Download",
"AriaDownloadButton": "Download",
"FileSent": "has sent:",
"FileTransferRetry": "Retry",
"AriaFileTransferRetry": "Retry",
"FileTransferError": "OK",
"AriaFileTransferError": "OK",
"FileTransferCancel": "Cancel",
"AriaFileTransferCancel": "Cancel",
"RestoreTimeoutTitle": "Chat ended",
"RestoreTimeoutBody": "Your previous chat session has timed out. Would you like to start a new one?",
"RestoreTimeoutReject": "No thanks",
"RestoreTimeoutAccept": "Start chat",
"AriaRestoreTimeoutAccept": "Start chat",
"AriaRestoreTimeoutReject": "No thanks",
"EndConfirmBody": "Would you really like to end your chat session?",
"EndConfirmAccept": "End chat",
"EndConfirmReject": "Cancel",
"AriaEndConfirmAccept": "End chat",
"AriaEndConfirmReject": "Cancel",
"SurveyOfferQuestion": "Would you like to participate in a survey?",
"ShowSurveyAccept": "Yes",
"ShowSurveyReject": "No",
"AriaShowSurveyAccept": "Yes",
"AriaShowSurveyReject": "No",
"UnreadMessagesTitle": "unread",
"AriaYouSaid": "You said",
"AriaSaid": "said",
"AriaSystemSaid": "System said",
"AriaWindowLabel": "Live Chat Window",
"AriaMinimize": "Live Chat Minimize",
"AriaMaximize": "Live Chat Maximize",
"AriaClose": "Live Chat Close",
"AriaEmojiStatusOpen": "Emoji picker dialog is opened",
"AriaEmojiStatusClose": "Emoji picker dialog is closed",
"AriaEmoji": "emoji",
"AriaCharRemaining": "Characters remaining",
"AriaMessageInput": "Message box",
"AsyncChatEnd": "End Chat",
"AsyncChatClose": "Close Window",
"AriaAsyncChatEnd": "End Chat",
"AriaAsyncChatClose": "Close Window",
"DayLabels": [
"Sun",
"Mon",
"Tue",
"Wed",
"Thur",
"Fri",
"Sat"
],
"MonthLabels": [
"Jan",
"Feb",
"Mar",
"Apr",
"May",
"Jun",
"Jul",
"Aug",
"Sept",
"Oct",
"Nov",
"Dec"
],
"todayLabel": "Today",
"Errors": {
"102": "First name is required.",
"103": "Last name is required.",
"161": "Please enter your name.",
"201": "The file could not be sent.<br/><strong><p class='filename' title='<%FilenameFull%>'>'<%FilenameTruncated%>'</p></strong><p class='cx-advice'>The maximum number of attached files would be exceeded (<%MaxFilesAllowed%>).</p>",
"202": "The file could not be sent.<br/><strong><p class='filename' title='<%FilenameFull%>'>'<%FilenameTruncated%>'</p></strong><p class='cx-advice'>Upload limit and/or maximum number of attachments would be exceeded (<%MaxAttachmentsSize%>).</p>",
"203": "The file could not be sent.<br/><strong><p class='filename' title='<%FilenameFull%>'>'<%FilenameTruncated%>'</p></strong><p class='cx-advice'>File type is not allowed.</p>",
"204": "We're sorry but your message is too long. Please write a shorter message.",
"240": "We're sorry but we cannot start a new chat at this time. Please try again later.",
"364": "Invalid email address.",
"401": "We're sorry but we are not able to authorize the chat session. Would you like to start a new chat?",
"404": "We're sorry but we cannot find your previous chat session. Would you like to start a new chat?",
"500": "We're sorry, an unexpected error occurred with the service. Would you like to close and start a new Chat?",
"503": "We're sorry, the service is currently unavailable or busy. Would you like to close and start a new Chat again?",
"ChatUnavailable": "We're sorry but we cannot start a new chat at this time. Please try again later.",
"CriticalFault": "Your chat session has ended unexpectedly due to an unknown issue. We apologize for the inconvenience.",
"StartFailed": "There was an issue starting your chat session. Please verify your connection and that you submitted all required information properly, then try again.",
"MessageFailed": "Your message was not received successfully. Please try again.",
"RestoreFailed": "We're sorry but we were unable to restore your chat session due to an unknown error.",
"TransferFailed": "Unable to transfer chat at this time. Please try again later.",
"FileTransferSizeError": "The file could not be sent.<br/><strong><p class='filename' title='<%FilenameFull%>'>'<%FilenameTruncated%>'</p></strong><p class='cx-advice'>File size is larger than the allowed size (<%MaxSizePerFile%>).</p>",
"InviteFailed": "Unable to generate invite at this time. Please try again later.",
"ChatServerWentOffline": "Messages are currently taking longer than normal to get through. We're sorry for the delay.",
"RestoredOffline": "Messages are currently taking longer than normal to get through. We're sorry for the delay.",
"Disconnected": "<div style='text-align:center'>Connection lost</div>",
"Reconnected": "<div style='text-align:center'>Connection restored</div>",
"FileSendFailed": "The file could not be sent.<br/><strong><p class='filename' title='<%FilenameFull%>'><%FilenameTruncated%></p></strong><p class='cx-advice'>There was an unexpected disconnection. Try again?</p>",
"Generic": "<div style='text-align:center'>An unexpected error occurred.</div>",
"pureengage-v3-rest-INVALID_FILE_TYPE": "Invalid file type. Only Images are allowed.",
"pureengage-v3-rest-LIMIT_FILE_SIZE": "File size is larger than the allowed size.",
"pureengage-v3-rest-LIMIT_FILE_COUNT": "The maximum number of attached files exceeded the limit.",
"pureengage-v3-rest-INVALID_CONTACT_CENTER": "Invalid x-api-key transport configuration.",
"pureengage-v3-rest-INVALID_ENDPOINT": "Invalid endpoint transport configuration.",
"pureengage-v3-rest-INVALID_NICKNAME": "First Name is required.",
"pureengage-v3-rest-AUTHENTICATION_REQUIRED": "We're sorry but we are not able to authorize the chat session.",
"purecloud-v2-sockets-400": "Sorry, something went wrong. Please verify your connection and that you submitted all required information properly, then try again.",
"purecloud-v2-sockets-500": "We're are sorry, an unexpected error occurred with the service.",
"purecloud-v2-sockets-503": "We're sorry, the service is currently unavailable."
}
}
}
}</source><br />
|Status=No
}}{{Section
|sectionHeading=API commands
|anchor=commands
|alignment=Vertical
|structuredtext=Once you've registered your plugin on the bus, you can call commands on other registered plugins. Here's how to use the global bus object to register a new plugin on the bus.

{{NoteFormat|The global bus object is a debugging tool. When implementing Widgets on your own site, do not use the global bus object to register your custom plugins. Instead, see {{Link-SomewhereInThisVersion|manual=SDK|topic=GWCBusExtensions|display text=Genesys Widgets Extensions}} for more information about extending Genesys Widgets.|1}}

<source lang="javascript">var oMyPlugin = window._genesys.widgets.bus.registerPlugin('MyPlugin');

oMyPlugin.command('WebChat.open');</source>

===configure===

Internal use only. The main App plugin shares configuration settings to widgets using each widget’s configure command. The configure command can only be called once at startup. Calling configure again after startup may result in unpredictable behavior.

===open===

Opens the WebChat UI.

====Example====

<source lang="javascript">
oMyPlugin.command('WebChat.open', {

userData: {},
form: {

autoSubmit: false,
firstname: 'John',
lastname: 'Smith',
email: 'John@mail.com',
subject: 'Customer Satisfaction'
}
formJSON: {...}
markdown: false

}).done(function(e){

// WebChat opened successfully

}).fail(function(e){

// WebChat isn't open or no active chat session
});
</source>

====Options====

{{{!}}
{{!}}-
!Option
!Type
!Description
{{!}}-
{{!}}form
{{!}}object
{{!}}Object containing form data to prefill in the chat entry form and optionally auto-submit the form.
{{!}}-
{{!}}form.autoSubmit
{{!}}boolean
{{!}}Automatically submit the form. Useful for bypassing the entry form step.
{{!}}-
{{!}}form.firstname
{{!}}string
{{!}}Value for the first name entry field.
{{!}}-
{{!}}form.lastname
{{!}}string
{{!}}Value for the last name entry field.
{{!}}-
{{!}}form.email
{{!}}string
{{!}}Value for the email entry field.
{{!}}-
{{!}}form.subject
{{!}}string
{{!}}Value for the subject entry field.
{{!}}-
{{!}}formJSON
{{!}}object
{{!}}An object containing a custom registration form definition. See {{Link-SomewhereInThisVersion|manual=SDK|topic=WebChat-combined|anchor=ccrf|display text=Customizable chat registration form}}.
{{!}}-
{{!}}userData
{{!}}object
{{!}}Object containing arbitrary data that gets sent to the server. Overrides userData set in the webchat configuration object.
{{!}}-
{{!}}async
{{!}}boolean
{{!}}Starts a new chat either in asynchronous or normal mode based on the boolean value. Note that unless {{Link-SomewhereInThisVersion|manual=SDK|topic=WebChat-combined|anchor=example|display text=async static configuration}} is defined, a chat in normal mode will start automatically.
{{!}}-
{{!}}{{!}}markdown
{{!}}{{!}}boolean
{{!}}{{!}}The markdown feature for chat messages.
{{!}}-
{{!}}{{!}}id
{{!}}{{!}}string
{{!}}{{!}}A Unique identifier of a chat session that helps to identify the instance of that session and its associated events. A random value is automatically generated and assigned when no value is passed explicitly.
{{!}}-
{{!}}}

====Resolutions====

{{{!}}
{{!}}-
!Status
!When
!Returns
{{!}}-
{{!}}resolved
{{!}}WebChat is successfully opened
{{!}}n/a
{{!}}-
{{!}}rejected
{{!}}WebChat is already open
{{!}}'already opened'
{{!}}-
{{!}}}

===close===

Closes the WebChat UI.

====Example====

<source lang="javascript">
oMyPlugin.command('WebChat.close').done(function(e){

// WebChat closed successfully

}).fail(function(e){

// WebChat is already closed or no active chat session
});
</source>

====Resolutions====

{{{!}}
{{!}}-
!Status
!When
!Returns
{{!}}-
{{!}}resolved
{{!}}WebChat is successfully closed
{{!}}n/a
{{!}}-
{{!}}rejected
{{!}}WebChat is already closed
{{!}}'already closed'
{{!}}-
{{!}}}

===minimize===

Minimizes or un-minimizes the WebChat UI.

====Example====

<source lang="javascript">
oMyPlugin.command('WebChat.minimize').done(function(e){

// WebChat minimized successfully

}).fail(function(e){

// WebChat ignores command
});
</source>

====Options====

{{{!}}
{{!}}-
!Option
!Type
!Description
{{!}}-
{{!}}minimized
{{!}}boolean
{{!}}Rather than toggling the current minimized state you can specify the minified state directly: true = minimized, false = uniminimized.
{{!}}-
{{!}}}

====Resolutions====

{{{!}}
{{!}}-
!Status
!When
!Returns
{{!}}-
{{!}}resolved
{{!}}Always
{{!}}n/a
{{!}}-
{{!}}rejected
{{!}}Never
{{!}}'Invalid configuration'
{{!}}-
{{!}}}

===endChat===

Starts the '''end chat''' procedure. User may be prompted to confirm.

====Example====

<source lang="javascript">
oMyPlugin.command('WebChat.endChat').done(function(e){

// WebChat ended a chat successfully

}).fail(function(e){

// WebChat has no active chat session
});
</source>

====Resolutions====

{{{!}}
{{!}}-
!Status
!When
!Returns
{{!}}-
{{!}}resolved
{{!}}There is an active chat session to end
{{!}}n/a
{{!}}-
{{!}}rejected
{{!}}There is no active chat session to end
{{!}}'there is no active chat session to end'
{{!}}-
{{!}}}

===invite===

Shows an invitation to chat using the Toaster popup element. The text shown in the invitation can be edited in the localization file.

====Example====

<source lang="javascript">
oMyPlugin.command('WebChat.invite').done(function(e){

// WebChat invited successfully

}).fail(function(e){

// WebChat is already open and will be ignored
});
</source>

====Resolutions====

{{{!}}
{{!}}-
!Status
!When
!Returns
{{!}}-
{{!}}resolved
{{!}}WebChat is closed and the toast element is created successfully
{{!}}n/a
{{!}}-
{{!}}rejected
{{!}}WebChat is already open (prevents inviting a user that is already in a chat)
{{!}}'Chat is already open. Ignoring invite command.'
{{!}}-
{{!}}}

===reInvite===

When an active chat session cannot be restored, this invitation offers to start a new chat for the user. The text shown in the invitation can be edited in the localization file.

====Example====

<source lang="javascript">
oMyPlugin.command('WebChat.reInvite').done(function(e){

// WebChat reinvited successfully

}).fail(function(e){

// WebChat is already open and will be ignored
});
</source>

====Resolutions====

{{{!}}
{{!}}-
!Status
!When
!Returns
{{!}}-
{{!}}resolved
{{!}}WebChat is closed, the config item 'webchat.inviteOnRestoreTimeout' is set, and the toast element is created successfully
{{!}}n/a
{{!}}-
{{!}}rejected
{{!}}WebChat is already open (prevents inviting a user that is already in a chat)
{{!}}'Chat is already open. Ignoring invite command.'
{{!}}-
{{!}}}

===injectMessage===

Injects a custom message into the chat transcript. Useful for extending WebChat functionality with other Genesys products.

====Example====

<source lang="javascript">
oMyPlugin.command('WebChat.injectMessage', {

type: 'text',
name: 'person',
text: 'hello',
custom: false,
bubble:{

fill: '#00FF00',
radius: '4px',
time: false,
name: false,
direction: 'right',
avatar:{

custom: '<div>word</div>',
icon: 'email'
}
}

}).done(function(e){

// WebChat injected a message successfully
// e.data == The message HTML reference (jQuery wrapped set)

}).fail(function(e){

// WebChat isn't open or no active chat
});
</source>

====Options====

{{{!}}
{{!}}-
!Option
!Type
!Description
{{!}}-
{{!}}type
{{!}}string
{{!}}Switch the rendering type of the injected message between text and html.
{{!}}-
{{!}}name
{{!}}string
{{!}}Specify a name label for the message to identify what service or widget has injected the message.
{{!}}-
{{!}}text
{{!}}string
{{!}}The content of the message. Either plain text or HTML.
{{!}}-
{{!}}custom
{{!}}boolean
{{!}}If set to true, the default message template will not be used, allowing you to inject a highly customized HTML block unconstrained by the normal message template.
{{!}}-
{{!}}bubble.fill
{{!}}string of valid CSS color value
{{!}}The content of the message. Either plain text or HTML.
{{!}}-
{{!}}bubble.radius
{{!}}string of valid CSS border radius value
{{!}}The border radius you'd like for the bubble.
{{!}}-
{{!}}bubble.time
{{!}}boolean
{{!}}If you'd like to show the timestamp for the bubble.
{{!}}-
{{!}}bubble.name
{{!}}boolean
{{!}}If you'd like to show the name for the bubble.
{{!}}-
{{!}}bubble.direction
{{!}}string
{{!}}Which direction you want the message bubble to come from.
{{!}}-
{{!}}bubble.avatar.custom
{{!}}string or HTML reference
{{!}}Change the content of the html that would be the avatar for the chat bubble.
{{!}}-
{{!}}bubble.avatar.icon
{{!}}class name
{{!}}Generated common library provided for icon name.
{{!}}-
{{!}}}

====Resolutions====

{{{!}}
{{!}}-
!Status
!When
!Returns
{{!}}-
{{!}}resolved
{{!}}WebChat is open and there is an active chat session
{{!}}An HTML reference (jQuery wrapped set) to the new injected message.
{{!}}-
{{!}}rejected
{{!}}WebChat is not open and/or there was no active chat session
{{!}}'No chat session to inject into'
{{!}}-
{{!}}}

===showChatButton===

Displays the standalone chat button using either the default template and CSS, or customer-defined ones.

====Example====

<source lang="javascript">
oMyPlugin.command('WebChat.showChatButton', {

openDelay: 1000,
duration: 1500

}).done(function(e){

// WebChat shows chat button successfully

}).fail(function(e){

// WebChat button is already visible, side bar is active and overrides the chat button, or chat button is disabled in configuration
});
</source>

====Options====

{{{!}}
{{!}}-
!Option
!Type
!Description
{{!}}-
{{!}}openDelay
{{!}}number
{{!}}Duration in milliseconds to delay showing the chat button on the page.
{{!}}-
{{!}}duration
{{!}}number
{{!}}Duration in milliseconds for the show and hide animation.
{{!}}-
{{!}}}

====Resolutions====

{{{!}}
{{!}}-
!Status
!When
!Returns
{{!}}-
{{!}}resolved
{{!}}The chat button is enabled in the configuration, is currently not visible, and the SideBar plugin is not initialized
{{!}}n/a
{{!}}-
{{!}}rejected
{{!}}The chat button is not enabled in the configuration, or it's already visible, or the SideBar plugin is initialized
{{!}}'Chat button is already visible. Ignoring command.'
{{!}}-
{{!}}rejected
{{!}}The SideBar plugin is active the standalone chat button will be disabled automatically
{{!}}'SideBar is active and overrides the default chat button'
{{!}}-
{{!}}}

===hideChatButton===

Hides the standalone chat button.

====Example====
<source lang="javascript">
oMyPlugin.command('WebChat.hideChatButton', {duration: 1500}).done(function(e){

// WebChat hid chat button successfully

}).fail(function(e){

// WebChat button is already hidden
});
</source>

====Options====
{{{!}}
{{!}}-
!Option
!Type
!Description
{{!}}-
{{!}}duration
{{!}}number
{{!}}Duration in milliseconds for the show and hide animation.
{{!}}-
{{!}}}

====Resolutions====

{{{!}}
{{!}}-
!Status
!When
!Returns
{{!}}-
{{!}}resolved
{{!}}The chat button is currently visible
{{!}}n/a
{{!}}-
{{!}}rejected
{{!}}The chat button is already hidden
{{!}}'Chat button is already hidden. Ignoring command.'
{{!}}-
{{!}}}

===showOverlay===

Opens a slide-down overlay over WebChat's content. You can fill this overlay with content such as disclaimers, articles, and other information.

====Example====

<source lang="javascript">
oMyPlugin.command('WebChat.showOverlay', {

html: '<div>Example text</div>',
hideFooter: false

}).done(function(e){

// WebChat successfully shows overlay

}).fail(function(e){

// WebChat isn't open
});
</source>

====Options====

{{{!}}
{{!}}-
!Option
!Type
!Description
{{!}}-
{{!}}html
{{!}}string or HTML reference
{{!}}The HTML content you want to display in the overlay.
{{!}}-
{{!}}hideFooter
{{!}}boolean
{{!}}Normally the overlay appears between the titlebar and footer bar. Set this to true to have the overlay overlap the footer to gain a bit more vertical space. This should only be used in special cases. For general use, don't set this value.
{{!}}-
{{!}}}

====Resolutions====
{{{!}}
{{!}}-
!Status
!When
!Returns
{{!}}-
{{!}}resolved
{{!}}WebChat is open and the overlay opens
{{!}}
{{!}}-
{{!}}rejected
{{!}}WebChat is not currently open
{{!}}WebChat is not currently open. Ignoring command.
{{!}}-
{{!}}}

===hideOverlay===

Hides the slide-down overlay.

====Example====

<source lang="javascript">
oMyPlugin.command('WebChat.hideOverlay').done(function(e){

// WebChat hid overlay successfully

}).fail(function(e){

// WebChat isn't open
});
</source>

====Resolutions====

{{{!}}
{{!}}-
!Status
!When
!Returns
{{!}}-
{{!}}resolved
{{!}}WebChat is open and the overlay closes
{{!}}
{{!}}-
{{!}}rejected
{{!}}WebChat is not currently open
{{!}}WebChat is not currently open. Ignoring command.
{{!}}-
{{!}}}
|Status=No
}}{{Section
|sectionHeading=API events
|anchor=events
|alignment=Vertical
|structuredtext=Once you've registered your plugin on the bus, you can subscribe to and listen for published events. Here's how to use the global bus object to register a new plugin on the bus.

{{NoteFormat|The global bus object is a debugging tool. When implementing Widgets on your own site, do not use the global bus object to register your custom plugins. Instead, see {{Link-SomewhereInThisVersion|manual=SDK|topic=GWCBusExtensions|display text=Genesys Widgets Extensions}} for more information about extending Genesys Widgets.|1}}

<source lang="javascript">var oMyPlugin = window._genesys.widgets.bus.registerPlugin('MyPlugin');

oMyPlugin.subscribe('WebChat.ready', function(e){});</source>

{{{!}}
{{!}}-
!Name
!Description
!Data
{{!}}-
{{!}}ready
{{!}}WebChat is initialized and ready to accept commands
{{!}}n/a
{{!}}-
{{!}}opened
{{!}}The WebChat widget has appeared on screen
{{!}}n/a
{{!}}-
{{!}}started
{{!}}The WebChat has successfully started.
{{!}}{{Link-SomewhereInThisVersion|manual=SDK|topic=WebChat-combined|anchor=metadata|display text=Metadata}}
{{!}}-
{{!}}submitted
{{!}}The user has submitted the form.
{{!}}{{Link-SomewhereInThisVersion|manual=SDK|topic=WebChat-combined|anchor=metadata|display text=Metadata}}
{{!}}-
{{!}}rejected
{{!}}When the chat session fails to start. Typically due to form validation or network errors.
{{!}}{{Link-SomewhereInThisVersion|manual=SDK|topic=WebChat-combined|anchor=metadata|display text=Metadata}}
{{!}}-
{{!}}completed
{{!}}The Chat session ended after agent is successfully connected to WebChat.
{{!}}{{Link-SomewhereInThisVersion|manual=SDK|topic=WebChat-combined|anchor=metadata|display text=Metadata}}
{{!}}-
{{!}}cancelled
{{!}}The Chat session ended before agent is connected to WebChat.
{{!}}{{Link-SomewhereInThisVersion|manual=SDK|topic=WebChat-combined|anchor=metadata|display text=Metadata}}
{{!}}-
{{!}}closed
{{!}}The WebChat widget has been removed from the screen
{{!}}{{Link-SomewhereInThisVersion|manual=SDK|topic=WebChat-combined|anchor=metadata|display text=Metadata}}
{{!}}-
{{!}}minimized
{{!}}The WebChat widget has been changed to a minimized state
{{!}}n/a
{{!}}-
{{!}}unminimized
{{!}}The WebChat widget has been restored from a minimized state to the standard view
{{!}}n/a
{{!}}-
{{!}}messageAdded
{{!}}When a message is added to the transcript, this event will fire
{{!}}Returns an object containing two properties: 'data' and 'html'. 'data' contains the JSON data for the message, while 'html' contains a reference to the visible message inside the chat transcript.
{{!}}-
{{!}}}
|Status=No
}}{{Section
|sectionHeading=Metadata
|anchor=metadata
|alignment=Vertical
|structuredtext====Interaction Lifecycle===

Every WebChat interaction has a sequence of events we call the ''Interaction Lifecycle''. This is a sequence of events that tracks progress and choices from the beginning of an interaction (opening WebChat), to the end (closing WebChat), and every step in between.

The following events are part of the Interaction Lifecycle:

ready
opened
started
cancelled
submitted
rejected
completed
closed

===Lifecycle scenarios===

An Interaction Lifecycle can vary based on each user's intent and experience with WebChat. Here are several sequences of events in the lifecycle that correspond to different scenarios.

The user opened WebChat but changed their mind and closed it without starting a chat session:
ready -> opened -> cancelled -> closed

The user started a chat session but ended it before an agent connected. Perhaps it was taking too long to reach someone:
ready -> opened -> started -> cancelled -> closed

The user started a chat, but the chat fails to start:
ready -> opened -> started -> submitted -> rejected

The user started a chat, met with an agent, and the session ended normally:
ready -> opened -> started -> submitted -> completed -> closed

{{NoteFormat|For a list of all WebChat events, see {{Link-SomewhereInThisVersion|manual=SDK|topic=WebChat-combined|anchor=events|display text=API events}}.|2}}

===Metadata===

Each event in the Interaction Lifecycle includes the following block of metadata. By default, all values are set to <tt>false</tt>. As the user progresses through the lifecycle of a WebChat interaction, these values will be updated.

The metadata block contains boolean state flags, counters, timestamps, and elapsed times. These values can be used to track and identify trends or issues with chat interactions. During run-time, the metadata can help you offer a smart and dynamic experience to your users.

====Reference====

{{{!}}
{{!}}-
!Name
!Type
!Description
{{!}}-
{{!}}proactive
{{!}}boolean
{{!}}Indicates this chat session was started proactively.
{{!}}-
{{!}}prefilled
{{!}}boolean
{{!}}Indicates the registration form was prefilled with info automatically.
{{!}}-
{{!}}autoSubmitted
{{!}}boolean
{{!}}Indicates the registration form was submitted automatically, usually after being prefilled.
{{!}}-
{{!}}filesUploaded
{{!}}integer
{{!}}Current number of files uploaded during chat session.
{{!}}-
{{!}}numAgents
{{!}}integer
{{!}}Current number of agents that have connected to the chat session.
{{!}}-
{{!}}userMessages
{{!}}integer
{{!}}Current number of messages sent by user.
{{!}}-
{{!}}agentMessages
{{!}}integer
{{!}}Current number of messages sent by agents.
{{!}}-
{{!}}systemMessages
{{!}}integer
{{!}}Current number of system messages received.
{{!}}-
{{!}}errors
{{!}}array/boolean
{{!}}An array of error codes encountered during chat session. If no errors, this value will be false.
{{!}}-
{{!}}form
{{!}}object
{{!}}An object containing the form parameters when the form is submitted.
{{!}}-
{{!}}opened
{{!}}integer (timestamp)
{{!}}Timestamp indicating when WebChat was opened.
{{!}}-
{{!}}started
{{!}}integer (timestamp)
{{!}}Timestamp indicating when chat session started.
{{!}}-
{{!}}cancelled
{{!}}integer (timestamp)
{{!}}Timestamp indicating when the chat session was cancelled. Cancelled refers to when a user ends a chat session before an agent connects.
{{!}}-
{{!}}rejected
{{!}}integer (timestamp)
{{!}}Timestamp indicating when the chat session was rejected. Rejected refers to when a chat session fails to start.
{{!}}-
{{!}}completed
{{!}}integer (timestamp)
{{!}}Timestamp indicating when the chat session ended normally. Completed refers to when a user or agent ends a chat after an agent connected.
{{!}}-
{{!}}closed
{{!}}integer (timestamp)
{{!}}Timestamp indicating when WebChat was closed.
{{!}}-
{{!}}agentReached
{{!}}integer (timestamp)
{{!}}Timestamp indicating when the first agent was reached, if any.
{{!}}-
{{!}}supervisorReached
{{!}}integer (timestamp)
{{!}}Timestamp indicating when the first agent supervisor was reached, if any.
{{!}}-
{{!}}elapsed
{{!}}integer (milliseconds)
{{!}}Total elapsed time in milliseconds from when the user started the chat session to when the chat session ended.
{{!}}-
{{!}}waitingForAgent
{{!}}integer (milliseconds)
{{!}}Total time in milleseconds waiting for an agent from when the user started the chat session to when an agent connected to the session.
{{!}}-
{{!}}id
{{!}}string
{{!}}A Unique identifier of a chat session that helps to identify the instance of that session and its associated events.
{{!}}-
{{!}}}
|Status=No
}}{{Section
|sectionHeading=Customizable chat registration form
|anchor=ccrf
|alignment=Vertical
|structuredtext=WebChat allows you to customize the registration form shown to users prior to starting a session. The following form inputs are currently supported:

*Text
*Select
*Hidden
*Checkbox
*Textarea

Customization is done through a JSON object structure that defines the layout, input type, label, and attributes for each input. You can set the default registration form definition in the '''_genesys.widgets.webchat.form''' {{Link-SomewhereInThisVersion|manual=SDK|topic=WebChat-combined|anchor=config|display text=configuration }} option. Alternately, you can pass a new registration form definition through the <tt>WebChat.open</tt> command:

<source lang="JAVASCRIPT">
_genesys.widgets.bus.command("WebChat.open", {formJSON: oRegFormDef});
</source>

Inputs are rendered as stacked rows with one input and one optional label per row.

===Default example===

The following example is the default JSON object used to render WebChat’s registration form. This is a very simple definition that does not use many properties.

<source lang="JAVASCRIPT">
{
wrapper: "<table></table>",
inputs: [

{
id: "cx_webchat_form_firstname",
name: "firstname",
maxlength: "100",
placeholder: "@i18n:webchat.ChatFormPlaceholderFirstName",
label: "@i18n:webchat.ChatFormFirstName"
},

{
id: "cx_webchat_form_lastname",
name: "lastname",
maxlength: "100",
placeholder: "@i18n:webchat.ChatFormPlaceholderLastName",
label: "@i18n:webchat.ChatFormLastName"
},

{
id: "cx_webchat_form_email",
name: "email",
maxlength: "100",
placeholder: "@i18n:webchat.ChatFormPlaceholderEmail",
label: "@i18n:webchat.ChatFormEmail"
},

{
id: "cx_webchat_form_subject",
name: "subject",
maxlength: "100",
placeholder: "@i18n:webchat.ChatFormPlaceholderSubject",
label: "@i18n:webchat.ChatFormSubject"
}
]
}
</source>

This JSON definition generates the following output:

[[File:WebChat CustomForm 001.png|400px]]

===Properties===

Each input definition can contain any number of properties. These are categorized in two groups: "Special properties", which are custom properties used internally to handle rendering logic, and "HTML attributes" which are properties that are applied directly as HTML attributes on the input element.

====Special properties====
{{{!}}
{{!}}-
!Property
!Type
!Default
!Description
{{!}}-
{{!}}type
{{!}}string
{{!}}"text"
{{!}}Sets the type of input to render. Possible values are currently "text", "hidden", "select", "checkbox", and "textarea".
{{!}}-
{{!}}label
{{!}}string
{{!}}
{{!}}Set the text for the label. If no value provided, no label will be shown. You may use localization query strings to enable custom localization (for example, label: "@i18n:namespace.StringName"). Localization query strings allow you to use strings from any widget namespace or to create your own namespace in the localization file (i18n.json) and use strings from there (for example, label: "@i18n:myCustomNamespace.myCustomString001"). For more information, see the {{Link-SomewhereInThisVersion|manual=SDK|topic=WebChat-combined|anchor=ccrflab|display text=Labels}} section.
{{!}}-
{{!}}wrapper
{{!}}HTML string
{{!}}<table></table>“<nowiki><table></table></nowiki>"
{{!}}Each input exists in its own row in the form. By default this is a table-row with the label in the left cell and the input in the right cell. You can redefine this wrapper and layout by specifying a new HTML row structure. See the {{Link-SomewhereInThisVersion|manual=SDK|topic=WebChat-combined|anchor=ccrfwrp|display text=Wrappers}} section for more info.<br><br> The default wrapper for an input is "
{{!}}-
{{!}}validate
{{!}}function
{{!}}
{{!}}Define a validation function for the input that executes when the input loses focus (blur) or changes value. Your function must return <tt>true</tt> or <tt>false</tt>. True to indicate it passed, false to indicate it failed. If your validation fails, the form will not submit and the invalid input will be highlighted in red. See the {{Link-SomewhereInThisVersion|manual=SDK|topic=WebChat-combined|anchor=ccrfval|display text=Validation}} section for more details and examples.
{{!}}-
{{!}}validateWhileTyping
{{!}}boolean
{{!}}false
{{!}}Execute validation on keypress in addition to blur and change. This ignores non-character keys like shift, ctrl, and alt.
{{!}}-
{{!}}options
{{!}}array
{{!}}[]
{{!}}When ‘type’ is set to ‘select’, you can populate the select by adding options to this array. Each option is an object (for example, {text: ‘Option 1’, value: ‘1’} for a selectable option, and {text: "Group 1", group: true} for an option group).
{{!}}-
{{!}}}

====HTML attributes====

With the exception of special properties, all properties will be added as HTML attributes on the input element. You can use standard HTML attributes or make your own.

'''Example'''

<source lang="JAVASCRIPT">
{
id: "cx_webchat_form_firstname",
name: "firstname",
maxlength: "100",
placeholder: "@i18n:webchat.ChatFormPlaceholderFirstName",
label: "@i18n:webchat.ChatFormFirstName"
}
</source>

In this example, <tt>id</tt>, <tt>name</tt>, <tt>maxlength</tt>, and <tt>placeholder</tt> are all standard HTML attributes for the text input element. Whatever values are set here will be applied to the input as HTML attributes.

{{NoteFormat|The default input type is "text", so type does not need to be defined if you intend to make a text input. |1}}

'''HTML output'''

<pre>
<input type="text" id="cx_webchat_form_firstname
name="firstname" maxlength="100" placeholder="Required"></input>
</pre>

====Disabling autocomplete====

Since the custom form feature supports adding any HTML attributes to your inputs, you can control standard HTML features like disabling autocomplete. To disable autocomplete, add '''autocomplete: "off"''' to your input definition.

'''Example'''

<source lang="JAVASCRIPT">
{
id: "cx_webchat_form_firstname",
name: "firstname",
maxlength: "100",
placeholder: "@i18n:webchat.ChatFormPlaceholderFirstName",
label: "@i18n:webchat.ChatFormFirstName",
autocomplete: "off"
}
</source>

{{AnchorDiv|ccrflab}}
===Labels===

A label tag will be generated for your input if you specify label text and if your custom input wrapper includes a ‘{label}’ designation. If you have added an ID attribute for your input, the label will automatically be linked to your input so that clicking on the label selects the input or, for checkboxes, toggles it.

Labels can be defined as static strings or localization queries.

{{AnchorDiv|ccrfwrp}}
===Wrappers===

Wrappers are HTML string templates that define a layout. There are two kinds of wrappers, '''Form Wrappers''' and '''Input Wrappers''':

====Form wrapper====

You can specify the parent wrapper for the overall form in the top-level "wrapper" property. In the example below, we specify this value as “<nowiki><table></table></nowiki>".<table></table>This is the default wrapper for the WebChat form:

<source lang="JAVASCRIPT">
{
wrapper: "<table></table>", /* form wrapper */
inputs: []
}
</source>

====Input wrapper====

Each input is rendered as a table row inside the Form Wrapper. You can change this by defining a new wrapper template for your input row. Inside your template you can specify where you want the input and label to be by adding the identifiers "{label}" and "{input}" to your wrapper value. See the example below:

<source lang="JAVASCRIPT">
{
id: "cx_webchat_form_firstname",
name: "firstname",
maxlength: "100",
placeholder: "@i18n:webchat.ChatFormPlaceholderFirstName",
label: "@i18n:webchat.ChatFormFirstName",
wrapper: "<tr><th>{label}</th><td>{input}</td></tr>" /* input row wrapper */
}
</source>

The {label} identifier is optional. Omitting it will allow the input to fill the row. If you decide to keep the label, you can move it to any location within the wrapper, such as putting the label on the right, or stacking the label on top of the input. You can control the layout of each row independently, depending on your needs.

You are not restricted to using a table for your form. You can change the form wrapper to "<nowiki><div></div></nowiki>" and then change the individual input wrappers from a table-row to your own specification. Be aware though that when you move away from the default table wrappers, you are responsible for styling and aligning your layout. Only the default table-row wrapper is supported by default Themes and CSS.{{AnchorDiv|ccrfval}}
===Validation===

You can apply a validation function to each input that lets you check the value after a change has been made and/or the user has moved to a different input (on change and on blur). You can enable validation on key press by setting <tt>validateWhileTyping</tt> to <tt>true</tt> in your input definition.

Here is how to define a validation function:

<source lang="JAVASCRIPT">
{
id: "cx_webchat_form_firstname",
name: "firstname",
maxlength: "100",
placeholder: "@i18n:webchat.ChatFormPlaceholderFirstName",
label: "@i18n:webchat.ChatFormFirstName",

validateWhileTyping: true, // default is false

validate: function(event, form, input, label, $, CXBus, Common){

return true; // or false
}
}
</source>

You must return <tt>true</tt> or <tt>false</tt> to indicate that validation has passed or failed, respectively. If you return false, the WebChat form will not submit, and the input will be highlighted in red. This is achieved by adding the CSS class "cx-error" to the input.

====Validation function arguments====

{{{!}}
{{!}}-
!Argument
!Type
!Description
{{!}}-
{{!}}event
{{!}}JavaScript event object
{{!}}The input event reference object related to the form input field. This event data can be helpful to perform actions like active validation on an input field while the user is typing.
{{!}}-
{{!}}form
{{!}}HTML reference
{{!}}A jquery reference to the form wrapper element.
{{!}}-
{{!}}input
{{!}}HTML reference
{{!}}A jquery reference to the input element being validated.
{{!}}-
{{!}}label
{{!}}HTML reference
{{!}}A jquery reference to the label for the input being validated.
{{!}}-
{{!}}$
{{!}}jquery instance
{{!}}Widget’s internal jquery instance. Use this to help you write your validation logic, if needed.
{{!}}-
{{!}}CXBus
{{!}}CXBus instance
{{!}}Widget’s internal CXBus reference. Use this to call commands on the bus, if needed.
{{!}}-
{{!}}Common
{{!}}Function Library
{{!}}Widget’s internal Common library of functions and utilities. Use if needed.
{{!}}-
{{!}}}
===Form submit===

Custom input field form values are submitted to the server as key value pairs under the userData section of the form submit request, where input field names will be the property keys. During the submit, this data is merged along with the userData defined in the {{Link-SomewhereInThisVersion|manual=SDK|topic=WebChat-combined|anchor=commands|display text=WebChat.open}} command.{{NoteFormat|Depending on the API used (PureEnagage V2 API or Genesys Cloud) the payload structure in the request can vary for each, but the section below explains how the form data is submitted by the WebChat UI plugin when using custom forms.|}}Below is the internal form data object defined in the WebChat plugin by default. Since firstname, lastname, nickname, email, and subject are reserved keywords, users are not allowed to have custom fields with the same name.<source lang="javascript">
{
firstname: '',
lastname: '',
nickname: '',
email: '',
subject: '',
userData: {}
}
</source>
====Example====
The example below shows how the custom form data given in the WebChat form fields have been mapped as form data object.

The form fields with reserved keywords like firstname, lastname, and email will be sent as top level and the rest of the fields will be sent under userData to the WebChatService plugin.

Once the form data object is sent to the WebChatService plugin, it will parse and send in the payload request.[[ File:WebChat_CustomForm_Dark_v1.png|frameless|400px|left]]<source lang="javascript">
{
firstname: 'John',
lastname: 'Smith',
email: 'john.smith@company.com',
userData: {
phonenumber: '9256328346',
enquirytype: 'Sales' //value selected from the dropdown
}
}
</source><br />
|Status=No
}}{{Section
|sectionHeading=Customizable emoji menu
|alignment=Vertical
|structuredtext={{AnchorDiv|cem}}
===Introduction===
WebChat offers a v2 emoji menu that lets you choose which emojis to include in the emoji menu.

[[File:WebChat-Emoji-menu.png|link=https://all.docs.genesys.com/File:WebChat-Emoji-menu.png|401x401px]]
===Differences between v1 and v2===

*v1 shows as a tooltip-style overlay; v2 shows as a new block between the transcript and the message input.
*v1 closes when you select an emoji or click outside the menu; v2 lets you choose multiple emojis and only closes if you click the emoji menu button again.
*v1 has three fixed emojis to choose from; v2 can show hundreds of customizable emojis in a grid layout.
*v1 menu appears in mobile mode; v2 menu is not available in mobile mode (when v2 is configured, no emoji menu button is present in mobile mode).
*v1 menu has default emojis; v2 menu does not have default emojis. It must be explicitly configured with a list of emojis.

===Configuring the emoji menu===
Click the emoji menu icon at the bottom-left corner of the WebChat UI to open the v2 emoji menu. The transcript will be resized to fit the emoji menu, which can vary in height depending on the number of emojis configured.

*When 1-8 emojis are configured, the menu has one row, and no scrollbar appears.
*When 9-16 emojis are configured, the menu has two rows, and no scrollbar appears.
*When 17-24 emojis are configured, the menu has three rows, and no scrollbar appears.
*When 25 or more emojis are configured, the menu has three rows, and a scrollbar appears.

[[File:Emoji Menu Resizing.png|776x776px]]

Configure the v2 emoji menu by passing a string containing emoji into the WebChat configuration or through localization.{{NoteFormat|If you define an emoji list in the WebChat configuration, it will override any emoji lists defined in localization files.|1}}You configure the emoji list by specifying a string of emoji characters, like "🤩🤪🤭🤫". WebChat will parse this string and arrange them in the emoji menu.<source lang="JAVASCRIPT">
// Configure a flat list of emoji characters
_genesys.widgets.webchat.emojiList = "🤩🤪🤭🤫🤨₿🤮🤯🧐🤬🧡🤟🤲🧠🧒🧑🧔🧓🧕🤱₿🧙🧚🧛🧜🧝🧞🧟🧖🧗🧘🦓🦒🦔🦕🦖🦗🥥🥦🥨🥩🇦🇺🇫🇷🎂🛍🇨🇦🇧🇷🐉🎅🇲🇽🕯🇨🇳🐰🎥🍂👨💪🎓🔥🎃🕎💕🕉🇺🇸👩🎊🏊🏳️‍🌈👑☪🌱☘☀🏈🦃💘👰⛄🎿⚽🌎";
</source>
====Add emoji display names====
You can also add names to emojis so that their names will appear when you hover over them. To add a name to an emoji, simply add a colon after the question mark symbol, and then type the name. Separate each name with a semicolon.

The format is ;🤩:name;

You can only add one name to an emoji. The following sample shows the format for configuring several emojis.<source lang="JAVASCRIPT">
// Configure an emoji list with emoji names
_genesys.widgets.webchat.emojiList = "🤩:Star-Struck;🤪:Zany Face;🤭:Face With Hand Over Mouth;🤫:Shushing Face;🤨:Face With Raised Eyebrow;₿:Bitcoin;🤮:Face Vomiting;🤯:Exploding Head;🧐:Face With Monocle;🤬:Face With Symbols on Mouth;🧡:Orange Heart;🤟:Love-You Gesture;🤲:Palms Up Together;🧠:Brain;🧒:Child;🧑:Person;🧔:Man: Beard;🧓:Older Person;🧕:Woman With Headscarf;🤱:Breast-Feeding;🧙:Mage;🧚:Fairy;🧛:Vampire;🧜:Merperson;🧝:Elf;🧞:Genie;🧟:Zombie;🧖:Person in Steamy Room;🧗:Person Climbing;🧘:Person in Lotus Position;🦓:Zebra;🦒:Giraffe;🦔:Hedgehog;🦕:Sauropod;🦖:T-Rex;🦗:Cricket;🥥:Coconut;🥦:Broccoli;🥨:Pretzel;🥩:Cut of Meat;🇦🇺:Australia Day;🇫🇷:Bastille Day;🎂:Birthday;🛍:Black Friday;🇨🇦:Canada Day;🇧🇷:Carnaval;🐉:Chinese New Year;🎅:Christmas;🇲🇽:Cinco de Mayo;🕯:Diwali;🇨🇳:Dragon Boat Festival;🐰:Easter;🎥:Emoji Movie;🍂:Fall / Autumn;👨:Father’s Day;💪:Festivus;🎓:Graduation;🔥:Guy Fawkes;🎃:Halloween;🕎:Hanukkah;💕:Hearts;🕉:Holi;🇺🇸:Independence Day;👩:Mother’s Day;🎊:New Year’s Eve;🏊:Olympics;🏳️‍🌈:Pride;👑:Queen’s Birthday;☪:Ramadan;🌱:Spring;☘:St Patrick’s Day;☀:Summer;🏈:Super Bowl;🦃:Thanksgiving;💘:Valentine’s Day;👰:Wedding / Marriage;⛄:Winter;🎿:Winter Olympics;⚽:World Cup;🌎:World Emoji Day;";
</source>
====Partially named lists====
You don't have to add names for every emoji. You can add titles to only a select few.<source lang="JAVASCRIPT">
// Configure an emoji list with only a few emoji names
_genesys.widgets.webchat.emojiList = "🤩🤪🤭🤫🤨₿🤮🤯🧐🤬🧡🤟;🤲:Palms Up Together;🧠🧒🧑🧔🧓🧕🤱₿🧙🧚🧛🧜🧝🧞🧟🧖🧗🧘🦓🦒🦔🦕🦖🦗🥥🥦🥨🥩🇦🇺🇫🇷🎂;🛍:Black Friday;🇨🇦🇧🇷🐉🎅🇲🇽🕯🇨🇳🐰🎥🍂👨💪🎓🔥🎃🕎💕🕉🇺🇸👩🎊🏊🏳️‍🌈👑☪🌱☘☀🏈🦃💘👰;⛄:Snowman;🎿⚽🌎";
</source>
===Localization===
Emojis can be localized so that each language has a preferred set of emojis and emoji titles.{{NoteFormat|If you define an emoji list in the WebChat configuration, it will override any emoji lists defined in localization files.|1}}The key name for defining an emoji list is "EmojiList". Emoji lists are defined in a localization file using the same syntax as the WebChat configuration.

<source lang="JAVASCRIPT">
{
"en": {
"webchat": {
"EmojiList": "🤩:Star-Struck;🤪:Zany Face;🤭:Face With Hand Over Mouth;🤫:Shushing Face;"
}
}
}
</source><br />
|Status=No
}}
}}

WID/Current/SDK/SideBar-combined

2020-10-26T20:40:58Z

Chrissyforrest: Published

{{Article
|Standalone=No
|DisplayName=SideBar
|TocName=SideBar
|Context=Learn about the Sidebar widget, which customers use to launch other widgets with a single click.
|ComingSoon=No
|Platform=GenesysEngage-cloud
|Role=Developer
|Section={{Section
|sectionHeading=Overview
|anchor=overview
|alignment=Vertical
|structuredtext=Use the Sidebar to launch other widgets with a single click. By default, Sidebar is displayed on the right side of the screen, and you can configure any launchable widgets onto Sidebar, including your custom extension widgets. The Sidebar UI expands when you hover your cursor over it, and contracts when you move the cursor away. Other features include configurable positioning and mobile support. You can also add new configurations on the fly, which automatically re-renders the sidebar.
[[File:Cloud_Sidebar_DesktopLeftPositioned_10032020.png|alt=|left|282x282px]][[File:Cloud_Sidebar_DesktopExpanded_DarkMode_.png|292x292px]]
===Usage===
Use the following methods to launch SideBar manually:

*Call the '''SideBar.open''' {{Link-SomewhereInThisVersion|manual=SDK|topic=SideBar-combined|anchor=commands|display text=command}}
*{{Link-SomewhereInThisVersion|manual=SDK|topic=SideBar-combined|anchor=config|display text=Configure}} Sidebar to show and launch custom widgets.

===Dependency===
You must configure at least one customer-facing UI widget in order to use the Sidebar Widget.
===Customization===
You can customize and {{Link-AnywhereElse|product=WID|version=Current|manual=Developer|topic=GWCInternat|display text=localize}} all of the text shown in the Sidebar Widget by adding entries to your {{Link-SomewhereInThisVersion|manual=SDK|topic=SideBar-combined|anchor=config|display text=configuration}} and {{Link-SomewhereInThisVersion|manual=SDK|topic=SideBar-combined|anchor=localize|display text=localization}} options.

Sidebar supports themes. You can create and register your own themes for Genesys Widgets.
===Namespace===
The Sidebar plugin has the following namespaces tied up with each of the following types:
{{{!}} class="wikitable" style="width: auto;"
{{!}}-
!{{!}}Type
!{{!}}Namespace
{{!}}-
{{!}}{{!}}{{Link-SomewhereInThisVersion|manual=SDK|topic=SideBar-combined|anchor=config|display text=Configuration}}
{{!}}{{!}}sidebar
{{!}}-
{{!}}{{!}}i18n—{{Link-SomewhereInThisVersion|manual=SDK|topic=SideBar-combined|anchor=localize|display text=Localization}}
{{!}}{{!}}sidebar
{{!}}-
{{!}}{{!}}CXBus—{{Link-SomewhereInThisVersion|manual=SDK|topic=SideBar-combined|anchor=commands|display text=API commands}} & {{Link-SomewhereInThisVersion|manual=SDK|topic=SideBar-combined|anchor=events|display text=API events}}
{{!}}{{!}}SideBar
{{!}}-
{{!}}{{!}}CSS
{{!}}{{!}}.cx-sidebar
{{!}}}

===Mobile support===
Sidebar supports both desktop and mobile devices. In mobile mode, the sidebar launcher button is displayed to the bottom of the screen. When triggered, it expands to the full screen of mobile and shows all channels configured with scrollbar when necessary. Like all Genesys Widgets, there are two main modes: Desktop & Mobile. Desktop is employed for monitors, laptops, and tablets. Mobile is employed for smartphones. When a smartphone is detected, Sidebar switches to special full-screen templates that are optimized for both portrait and landscape orientations.

Switching between desktop and mobile mode is done automatically by default. You may configure Genesys Widgets to switch between Desktop and Mobile mode manually if necessary.
===Screenshots===

'''Dark theme'''

[[File:Cloud_Sidebar_Desktop_DarkMode_10032020.png|150x150px]]
[[File:Cloud_Sidebar_DesktopExpanded_DarkMode_10032020.png|150x150px]]
[[File:M_Cloud_Sidebar_MobilePotrait_DarkMode_10032020.png|150x150px]]
[[File:M_Cloud_Sidebar_MobileLandscape_DarkMode_10032020.png|150x150px]]

'''Light theme'''

[[File:Cloud_Sidebar_Desktop_LightMode_10032020.png|150x150px]]
[[File:Cloud_Sidebar_DesktopExpanded_LightMode_10032020_.png|150x150px]]
[[File:Sidebar MobileNeedHelpLight 28022020.jpg|150x150px]]
[[File:M_Cloud_Sidebar_MobilePotrait_LightMode_10032020.png|150x150px]]
[[File:M_Cloud_Sidebar_MobileLandscape_LightMode_10032020.png|150x150px]]
|Status=No
}}{{Section
|sectionHeading=Configuration
|anchor=config
|alignment=Vertical
|structuredtext=SideBar shares the '''_genesys.widgets.sidebar''' configuration namespace. SideBar has UI options to handle its position on the screen, disable expand feature sidebar, hide sidebar, and add new channels on the fly. The display order of channels is based on the order defined in channels configuration array.
===Example===
<pre>
window._genesys.widgets.sidebar = {

showOnStartup: true,

position: 'left',

expandOnHover: true,

channels: [{

name: 'ChannelSelector',
clickCommand: 'ChannelSelector.open',
clickOptions: {},

//use your own static string or i18n query string for the below two display properties
displayName: 'Live Assist',
displayTitle: 'Get live help',

icon: 'agent'
},

{
name: 'WebChat'
}
]
};
</pre>

===Options===

{{{!}} class="wikitable"
{{!}}-
!{{!}}Name
!{{!}}Type
!{{!}}Description
!{{!}}Default
!{{!}}Required
{{!}}-
{{!}}{{!}}showOnStartup
{{!}}{{!}}boolean
{{!}}{{!}}Shows the sidebar on the screen when Widgets is launched.
{{!}}{{!}}true
{{!}}{{!}}false
{{!}}-
{{!}}{{!}}position
{{!}}{{!}}string
{{!}}{{!}}Defines the position of sidebar on the screen. Acceptable values are <code>left</code> or <code>right</code>.
{{!}}{{!}}right
{{!}}{{!}}false
{{!}}-
{{!}}{{!}}expandOnHover
{{!}}{{!}}boolean
{{!}}{{!}}Enables the expand (slide-out) or contract (slide-in) behavior of sidebar.
{{!}}{{!}}true
{{!}}{{!}}false
{{!}}-
{{!}}{{!}}channels[index].name
{{!}}{{!}}string
{{!}}{{!}}Name of the channel. It can be found in the namespace section documentation of each Widget. Used to identify official channels vs custom channels. If a reserved name is used here, Sidebar will apply default values for that channel. A plugin name defined in the new custom plugin can also be given here. To override the default values or when defining a new custom channel/plugin, use the below following properties.
{{!}}{{!}}n/a
{{!}}{{!}}true
{{!}}-
{{!}}{{!}}channels[index].clickCommand
{{!}}{{!}}string
{{!}}{{!}}Change the default command that is triggered when clicked.
{{!}}{{!}}n/a
{{!}}{{!}}false
{{!}}-
{{!}}{{!}}channels[index].clickOptions
{{!}}{{!}}object
{{!}}{{!}}Pass valid command options that are used in above click command execution.
{{!}}{{!}}n/a
{{!}}{{!}}n/a
{{!}}-
{{!}}{{!}}channels[index].readyEvent
{{!}}{{!}}string
{{!}}{{!}}Subscribes to this ready event published by a plugin.
{{!}}{{!}}n/a
{{!}}{{!}}false
{{!}}-
{{!}}{{!}}channels[index].displayName
{{!}}{{!}}string or i18n query string
{{!}}{{!}}Change the default display name for this channel with your own static string or to achieve localization, use i18n query string. Syntax: @i18n:<nowiki><plugin namespace>.<display key></nowiki>
{{!}}{{!}}n/a
{{!}}{{!}}false
{{!}}-
{{!}}{{!}}channels[index].displayTitle
{{!}}{{!}}string or i18n query string
{{!}}{{!}}Change the default tooltip content for this channel with your own static string or to achieve localization, use i18n query string. Syntax: @i18n:<nowiki><plugin namespace>.<display key></nowiki>
{{!}}{{!}}n/a
{{!}}{{!}}false
{{!}}-
{{!}}{{!}}channels[index].icon
{{!}}{{!}}string
{{!}}{{!}}Change the default icon for this channel. For the list of icon names see ''Customize icons'' in {{Link-AnywhereElse|product=WID|version=Current|manual=Developer|topic=GWCCustomize}}.
{{!}}{{!}}n/a
{{!}}{{!}}false
{{!}}-
{{!}}{{!}}channels[index].onClick
{{!}}{{!}}function
{{!}}{{!}}Define a custom onclick function, this overrides clickCommand and clickOptions.
{{!}}{{!}}n/a
{{!}}{{!}}false
{{!}}}
|Status=No
}}{{Section
|sectionHeading=Localization
|anchor=localize
|alignment=Vertical
|structuredtext=For your custom plugins, you can define string key names and values for Name and Title (tooltip) to display on sidebar. The key format requires the plugin name, followed by "Title" or "Name". For example, a plugin named "MyPlugin" will have keys called "MyPluginName" and "MyPluginTitle".

{{NoteFormat|For information on how to set up localization, refer to {{Link-AnywhereElse|product=WID|version=Current|manual=Developer|topic=GWCInternat|display text=Localize widgets and services}}.|1}}
===Strings===
<source lang="javascript">{
"SidebarTitle": "Need help?",
"ChannelSelectorName": "Live Assistance",
"ChannelSelectorTitle": "Get assistance from one of our agents right away",
"CallUsName": "Call Us",
"CallUsTitle": "Call Us details",
"CallbackName": "Callback",
"CallbackTitle": "Receive a Call",
"WebChatName": "Live Chat",
"WebChatTitle": "Live Chat",
"AriaClose": "Close the menu Need help"
}</source>
|Status=No
}}{{Section
|sectionHeading=API commands
|anchor=commands
|alignment=Vertical
|structuredtext=Once you've registered your plugin on the bus, you can call commands on other registered plugins. Here's how to use the global bus object to register a new plugin on the bus.

{{NoteFormat|The global bus object is a debugging tool. When implementing Widgets on your own site, do not use the global bus object to register your custom plugins. Instead, see {{Link-AnywhereElse|product=WID|version=Current|manual=SDK|topic=GWCBusExtensions|display text=Genesys Widgets Extensions}} for more information about extending Genesys Widgets.|1}}

<source lang="javascript">var oMyPlugin = window._genesys.widgets.bus.registerPlugin('MyPlugin');

oMyPlugin.command('SideBar.open');</source>
===configure===
Internal use only. The main App plugin shares configuration settings to widgets using each widget’s configure command. Sidebar widget has to be configured at least with one channel. The configure command can also be called at runtime with new configuration, this will override the existing configuration showing new channels on the screens.
====Example====
<source lang="javascript">
oMyPlugin.command('SideBar.configure', {

showOnStartup: false,
position: 'left',
expandOnHover: false,
channels: [
{
name: 'ChannelSelector',
clickCommand: 'ChannelSelector.open',
clickOptions: {},

//use your own static string or i18n query string for the below two display properties.
Example for i18n query string: '@i18n:sidebar.ChannelSelectorName' where 'sidebar' refers to plugin namespace and
ChannelSelectorName' name refers to the property key containing the actual text.

displayName: '@i18n:sidebar.ChannelSelectorName',
displayTitle: 'Get assistance from one of our agents right away', // Your own static string
readyEvent: 'ChannelSelector.ready',
icon: 'agent',
onClick: function($, CXBus, Common) {
_genesys.widgets.bus.command('MyPlugin.open');
}
}
...
]

}).done(function(e){

// Sidebar configured successfully

}).fail(function(e){

// Sidebar failed to configure properly
});
</source>

====Options====

{{{!}} class="wikitable"
{{!}}-
!{{!}}Option
!{{!}}Type
!{{!}}Description
{{!}}-
{{!}}{{!}}showOnStartup
{{!}}{{!}}boolean
{{!}}{{!}}Shows the sidebar on the screen when Widgets is launched.
{{!}}-
{{!}}{{!}}position
{{!}}{{!}}string
{{!}}{{!}}Defines the position of sidebar on the screen.
{{!}}-
{{!}}{{!}}expandOnHover
{{!}}{{!}}boolean
{{!}}{{!}}Enables the expand or contract behavior of sidebar.
{{!}}-
{{!}}{{!}}channels
{{!}}{{!}}array
{{!}}{{!}}Array containing each channel configuration object. The order of channels are displayed based on the order defined here.
{{!}}-
{{!}}{{!}}channels[index].name
{{!}}{{!}}string
{{!}}{{!}}Name of the channel. It can be found in the namespace section documentation of each Widget. Used to identify official channels vs custom channels. If a reserved name is used here, Sidebar will apply default values for that channel. To override the default values or when defining a new custom channel, use the below following properties.
{{!}}-
{{!}}{{!}}channels[index].clickCommand
{{!}}{{!}}string
{{!}}{{!}}Change the default command that is triggered when clicked.
{{!}}-
{{!}}{{!}}channels[index].clickOptions
{{!}}{{!}}object
{{!}}{{!}}Pass valid command options that are used in above click command execution.
{{!}}-
{{!}}{{!}}channels[index].displayName
{{!}}{{!}}string or i18n query string
{{!}}{{!}}Change the default display name for this channel with your own static string or to achieve localization, use i18n query string. Syntax: @i18n:<nowiki><plugin namespace>.<display key></nowiki>.
{{!}}-
{{!}}{{!}}channels[index].displayTitle
{{!}}{{!}}string or i18n query string
{{!}}{{!}}Change the default tooltip content for this channel with your own static string or to achieve localization, use i18n query string. Syntax: @i18n:<nowiki><plugin namespace>.<display key></nowiki>.
{{!}}-
{{!}}{{!}}channels[index].readyEvent
{{!}}{{!}}string
{{!}}{{!}}Subscribes to this ready event published by a plugin.
{{!}}-
{{!}}{{!}}channels[index].icon
{{!}}{{!}}string
{{!}}{{!}}Change the default Icon for this channel. For the list of Icon names see ''Customize icons'' in {{Link-SomewhereInThisVersion|manual=Developer|topic=GWCCustomize|display text=Customize appearance}}.
{{!}}-
{{!}}{{!}}channels[index].onClick
{{!}}{{!}}function
{{!}}{{!}}Define a custom onclick function, this overrides clickCommand and clickOptions.
{{!}}}
|Status=No
}}{{Section
|sectionHeading=API events
|anchor=events
|alignment=Vertical
|structuredtext=Once you've registered your plugin on the bus, you can subscribe to and listen for published events. Here's how to use the global bus object to register a new plugin on the bus.

{{NoteFormat|The global bus object is a debugging tool. When implementing Widgets on your own site, do not use the global bus object to register your custom plugins. Instead, see {{Link-AnywhereElse|product=WID|version=Current|manual=SDK|topic=GWCBusExtensions|display text=Genesys Widgets Extensions}} for more information about extending Genesys Widgets.|1}}

<source lang="javascript">var oMyPlugin = window._genesys.widgets.bus.registerPlugin('MyPlugin');

oMyPlugin.subscribe('SideBar.ready', function(e){ /* sample code */ });</source>
{{{!}} class="wikitable"
{{!}}-
!{{!}}Name
!{{!}}Description
!{{!}}Data
{{!}}-
{{!}}{{!}}ready
{{!}}{{!}}Sidebar is initialized and ready to accept commands.
{{!}}{{!}}n/a
{{!}}-
{{!}}{{!}}opened
{{!}}{{!}}Sidebar widget has appeared on screen. For desktop it is displayed on the sides of the screen and in mobiles at the bottom corner as a button.
{{!}}{{!}}n/a
{{!}}-
{{!}}{{!}}closed
{{!}}{{!}}Sidebar widget has been removed from the screen.
{{!}}{{!}}n/a
{{!}}-
{{!}}{{!}}expanded
{{!}}{{!}}Sidebar widget has expanded, showing channel icon and name.
{{!}}{{!}}n/a
{{!}}-
{{!}}{{!}}contracted
{{!}}{{!}}Sidebar widget has contracted back, showing channel icons only.
{{!}}{{!}}n/a
{{!}}}
|Status=No
}}
}}
====Resolutions====

{{{!}} class="wikitable"
{{!}}-
!{{!}}Status
!{{!}}When
!{{!}}Returns
{{!}}-
{{!}}{{!}}resolved
{{!}}{{!}}When configuration options are provided and set
{{!}}{{!}}n/a
{{!}}-
{{!}}{{!}}rejected
{{!}}{{!}}When no configuration options are provided
{{!}}{{!}}'Invalid configuration. Please ensure at least one channel is configured.'
{{!}}}

===open===
Opens the Sidebar UI. In Desktop mode, it opens as an actual SideBar and shows the configured channels where as in mobile it opens as a button at the bottom to start.
====Example====
<source lang='javascript'>
oMyPlugin.command('SideBar.open');
</source>

====Resolutions====

{{{!}} class="wikitable"
{{!}}-
!{{!}}Status
!{{!}}When
!{{!}}Returns
{{!}}-
{{!}}{{!}}resolved
{{!}}{{!}}When sidebar is successfully opened
{{!}}{{!}}n/a
{{!}}-
{{!}}{{!}}rejected
{{!}}{{!}}When sidebar is already opened
{{!}}{{!}}'Already opened'
{{!}}}

===close===
Closes the Sidebar UI.
====Example====
<source lang='javascript'>
oMyPlugin.command('SideBar.close');
</source>

====Resolutions====

{{{!}} class="wikitable"
{{!}}-
!{{!}}Status
!{{!}}When
!{{!}}Returns
{{!}}-
{{!}}{{!}}resolved
{{!}}{{!}}When sidebar is successfully closed
{{!}}{{!}}n/a
{{!}}-
{{!}}{{!}}rejected
{{!}}{{!}}When sidebar is already closed
{{!}}{{!}}'already closed'
{{!}}}

===expand===
To show more details about the channels, Sidebar slides out from the sides of the screen on desktop machines but expands to full screen in mobile devices.
====Example====
<source lang='javascript'>
oMyPlugin.command('SideBar.expand');
</source>

====Resolutions====

{{{!}} class="wikitable"
{{!}}-
!{{!}}Status
!{{!}}When
!{{!}}Returns
{{!}}-
{{!}}{{!}}resolved
{{!}}{{!}}When sidebar is successfully expanded
{{!}}{{!}}n/a
{{!}}-
{{!}}{{!}}rejected
{{!}}{{!}}When sidebar is already expanded
{{!}}{{!}}'sidebar already expanded'
{{!}}}

===contract===
Retracts the expanded version of Sidebar, showing only the channel buttons on desktop machines and the sidebar launcher button on mobile devices.
====Example====
<source lang='javascript'>
oMyPlugin.command('SideBar.contract');
</source>

====Resolutions====

{{{!}} class="wikitable"
{{!}}-
!{{!}}Status
!{{!}}When
!{{!}}Returns
{{!}}-
{{!}}{{!}}resolved
{{!}}{{!}}When sidebar is successfully contracted
{{!}}{{!}}n/a
{{!}}-
{{!}}{{!}}rejected
{{!}}{{!}}When sidebar is already contracted
{{!}}{{!}}sidebar already contracted
{{!}}}

WID/Current/SDK/Console-combined

2020-10-26T20:09:08Z

Chrissyforrest: Published

{{Article
|Standalone=No
|DisplayName=Console
|TocName=Console
|Context=Learn how to debug commands and events on the widget bus.
|ComingSoon=No
|Platform=GenesysEngage-cloud
|Role=Developer
|Section={{Section
|sectionHeading=Overview
|anchor=overview
|alignment=Vertical
|structuredtext=Use the Console Widget to debug commands and events on the widget bus. You can use dynamically populated lists to test, debug, or demo all commands. You can also create event watch lists that alert you when an event has fired.

[[File:Console_Main.png|500px|Console example]]

Console provides an easy-to-use interface for debugging the widget bus that complements the standard command-line methods. You can drag and drop the console anywhere on your screen, and when you refresh the page or move to another one, Console reappears right where you left it. It is a great tool for getting to know the widget bus, the API for each widget, and debugging issues.
===Usage===
Launch WebChat manually by using the following methods:

*Call the '''Console.open''' {{Link-SomewhereInThisVersion|manual=SDK|topic=Console-combined|anchor=commands|display text=command}}
*Configure the settings to show Console when the browser window is opened.
*Create your own custom button or link to open Console (using the '''Console.open''' {{Link-SomewhereInThisVersion|manual=SDK|topic=Console-combined|anchor=commands|display text=command}})
|Status=No
}}{{Section
|sectionHeading=Configuration
|anchor=config
|alignment=Vertical
|structuredtext====Description===
Console option to open on initial loading.

===Example===
<pre>
window._genesys.widgets.console = {open: true};
</pre>

===Options===

{{{!}} class="wikitable"
{{!}}-
!{{!}}Name
!{{!}}Type
!{{!}}Description
!{{!}}Default
!{{!}}Required
{{!}}-
{{!}}{{!}}open
{{!}}{{!}}boolean
{{!}}{{!}}Set to <code>true</code> for console to open at start.
{{!}}{{!}}false
{{!}}{{!}}false
{{!}}}
|Status=No
}}{{Section
|sectionHeading=Localization
|anchor=localize
|alignment=Vertical
|structuredtext={{NoteFormat|For information on how to set up localization, please refer to {{Link-AnywhereElse|product=WID|version=Current|manual=Developer|topic=GWCInternat}}.|1}}
==Strings==
<source lang="javascript">{
"ConsoleTitle": "CXBus Console",
"Commands": "Commands",
"Plugin": "Plugin",
"ConsoleErrorButton": "OK",
"Execute": "Execute",
"Event": "Event",
"SubscribeTo": "Subscribe to",
"Unsubscribe": "Unsubscribe",
"ReturnData": "Return Data",
"EventsSubscriber": "Events Subscriber",
"Watch": "Watch",
"pluginNameEvent": "PluginName.Event",
"ClearAll": "Clear All",
"OptionsSample": "JSON Formatted Options {'option': value}"
}</source><br />
|Status=No
}}{{Section
|sectionHeading=API commands
|anchor=commands
|alignment=Vertical
|structuredtext=Once you've registered your plugin on the bus, you can call commands on other registered plugins. Here's how to use the global bus object to register a new plugin on the bus.

{{NoteFormat|The global bus object is a debugging tool. When implementing Widgets on your own site, do not use the global bus object to register your custom plugins. Instead, see {{Link-AnywhereElse|product=WID|version=Current|manual=SDK|topic=GWCBusExtensions|display text=Genesys Widgets Extensions}} for more information about extending Genesys Widgets.|1}}

<source lang="javascript">var oMyPlugin = window._genesys.widgets.bus.registerPlugin('MyPlugin');

oMyPlugin.command('Console.open');</source>
===open===
Opens the Console UI.
====Example====
<source lang="javascript">
oMyPlugin.command('Console.open').done(function(e){

// Console opened successfully

}).fail(function(e){

// Console failed to open
});
</source>

====Resolutions====

{{{!}} class="wikitable"
{{!}}-
!{{!}}Status
!{{!}}When
!{{!}}Returns
{{!}}-
{{!}}{{!}}resolved
{{!}}{{!}}Console is successfully opened
{{!}}{{!}}n/a
{{!}}-
{{!}}{{!}}rejected
{{!}}{{!}}Console is already open
{{!}}{{!}}'Already opened'
{{!}}}

===close===
Closes the Console UI.
====Example====
<source lang="javascript">
oMyPlugin.command('Console.close').done(function(e){

// Console closed successfully

}).fail(function(e){

// Console failed to close
});
</source>

====Resolutions====

{{{!}} class="wikitable"
{{!}}-
!{{!}}Status
!{{!}}When
!{{!}}Returns
{{!}}-
{{!}}{{!}}resolved
{{!}}{{!}}Console successfully closed
{{!}}{{!}}n/a
{{!}}-
{{!}}{{!}}rejected
{{!}}{{!}}Console is already closed
{{!}}{{!}}'Already closed'
{{!}}}

===configure===
Modifies the Console configuration options. See the Console configuration page.
====Example====
<source lang="javascript">
oMyPlugin.command('Console.configure', {

open: false

}).done(function(e){

// Console configured successfully

}).fail(function(e){

// Console failed to configure
});
</source>

====Options====

{{{!}} class="wikitable"
{{!}}-
!{{!}}Option
!{{!}}Type
!{{!}}Description
{{!}}-
{{!}}{{!}}open
{{!}}{{!}}boolean
{{!}}{{!}}If setting is open: true, the console will automatically be open when Widgets is launched and the console is ready.
{{!}}}

====Resolutions====

{{{!}} class="wikitable"
{{!}}-
!{{!}}Status
!{{!}}When
!{{!}}Returns
{{!}}-
{{!}}{{!}}resolved
{{!}}{{!}}Console configuration is provided
{{!}}{{!}}n/a
{{!}}-
{{!}}{{!}}rejected
{{!}}{{!}}No configuration is provided
{{!}}{{!}}'Invalid Configuration'
{{!}}}
|Status=No
}}{{Section
|sectionHeading=API events
|anchor=events
|alignment=Vertical
|structuredtext=Once you've registered your plugin on the bus, you can subscribe to and listen for published events. Here's how to use the global bus object to register a new plugin on the bus.

{{NoteFormat|The global bus object is a debugging tool. When implementing Widgets on your own site, do not use the global bus object to register your custom plugins. Instead, see {{Link-AnywhereElse|product=WID|version=Current|manual=SDK|topic=GWCBusExtensions|display text=Genesys Widgets Extensions}} for more information about extending Genesys Widgets.|1}}

<source lang="javascript">var oMyPlugin = window._genesys.widgets.bus.registerPlugin('MyPlugin');

oMyPlugin.subscribe('Console.ready', function(e){});</source>
{{{!}} class="wikitable"
{{!}}-
!{{!}}Name
!{{!}}Description
!{{!}}Data
{{!}}-
{{!}}{{!}}ready
{{!}}{{!}}Console is initialized and ready to accept commands.
{{!}}{{!}}n/a
{{!}}-
{{!}}{{!}}opened
{{!}}{{!}}The Console Widget has appeared on screen.
{{!}}{{!}}n/a
{{!}}-
{{!}}{{!}}closed
{{!}}{{!}}The Console Widget has been removed from the screen.
{{!}}{{!}}n/a
{{!}}}
|Status=No
}}
}}

WID/Current/SDK/ChannelSelector-combined

2020-10-26T19:51:43Z

Chrissyforrest: Published

{{Article
|Standalone=No
|DisplayName=ChannelSelector
|TocName=ChannelSelector
|Context=Learn how to provide your customers with a configurable list of channels as an entry point for contacting customer service.
|ComingSoon=No
|Platform=GenesysEngage-cloud
|Role=Developer
|Section={{Section
|sectionHeading=Overview
|alignment=Vertical
|structuredtext=The ChannelSelector Widget displays a configurable list of channels, as an entry point for customers to contact customer service. In addition to showing multiple channels, ChannelSelector can be configured to display the estimated wait time (EWT) for each channel. You can also use an EWT value to configure channels to hide, or to show, that they disabled. Channels are not limited to Genesys Widgets; you can add your own custom channels to launch applications or open new windows as necessary.

[[File:Live assistance channels pec.png|455x455px]]

Note the screenshots in the following section, and visit the {{Link-SomewhereInThisVersion|manual=SDK|topic=ChannelSelector-combined|anchor=config|display text=configuration}} section for more information.
===Usage===
Use the following methods to launch ChannelSelector manually:

*Call the '''ChannelSelector.open''' {{Link-SomewhereInThisVersion|manual=SDK|topic=ChannelSelector-combined|anchor=commands|display text=command}}
*Create your own custom button or link to open ChannelSelector (using the "ChannelSelector.open" command)

{{NoteFormat|By default ChannelSelector has no channels configured. The UI will appear empty if not configured. See the {{Link-SomewhereInThisVersion|manual=SDK|topic=ChannelSelector-combined|anchor=config|display text=configuration}} section for examples and information on how to set up your own custom channels. |}}

===Customization===
You can customize and {{Link-AnywhereElse|product=WID|version=Current|manual=Developer|topic=GWCInternat|display text=localize}} all of the static text shown in the ChannelSelector Widget by adding entries into your {{Link-SomewhereInThisVersion|manual=SDK|topic=ChannelSelector-combined|anchor=config|display text=configuration}} and {{Link-SomewhereInThisVersion|manual=SDK|topic=ChannelSelector-combined|anchor=localize|display text=localization}} options.

ChannelSelector supports Themes. You can create and register your own themes for Genesys Widgets.
===Namespace===
The Channel Selector plugin has the following namespaces tied to each of the following types:
{{{!}} class="wikitable" style="width: auto;"
{{!}}-
!{{!}}Type
!{{!}}Namespace
{{!}}-
{{!}}{{!}}{{Link-SomewhereInThisVersion|manual=SDK|topic=ChannelSelector-combined|anchor=config|display text=Configuration}}
{{!}}{{!}}channelselector
{{!}}-
{{!}}{{!}}i18n—{{Link-SomewhereInThisVersion|manual=SDK|topic=ChannelSelector-combined|anchor=localize|display text=Localization}}
{{!}}{{!}}channelselector
{{!}}-
{{!}}{{!}}CXBus—{{Link-SomewhereInThisVersion|manual=SDK|topic=ChannelSelector-combined|anchor=commands|display text=API commands}} & {{Link-SomewhereInThisVersion|manual=SDK|topic=ChannelSelector-combined|anchor=events|display text=API events}}
{{!}}{{!}}ChannelSelector
{{!}}-
{{!}}{{!}}CSS
{{!}}{{!}}.cx-channel-selector
{{!}}}

===Mobile support===
ChannelSelector supports both desktop and mobile devices. Like all Genesys Widgets, there are two main modes: Desktop and Mobile. Desktop is employed for monitors, laptops, and tablets. Mobile is employed for smartphones. When a smartphone is detected, ChannelSelector switches to special full-screen templates that are optimized for both portrait and landscape orientations.

Switching between Desktop and Mobile modes is done automatically by default. You may configure Genesys Widgets to switch between Desktop and Mobile modes manually if necessary.
===Screenshots===
'''Dark theme'''<br />
[[File:GEC_CS_MaxUnAvl_dark_MobileLandscape.png|173x173px]]
[[File:GEC_CS_MaxUnAvl_dark.png|150x150px]]
[[File:GEC_CS_Avl_dark_MobileLandscape.png|176x176px]]
[[File:GEC_CS_Avl_dark.png|150x150px]]
[[File:GEC_CS_MaxUnAvl_dark_MobilePortrait.png|150x150px]]
[[File:GEC_CS_Min_dark.png|150x150px]]
[[File:GEC_CS_Avl_dark_MobilePortrait.png|150x150px]]
[[File:GEC_CS_Min_dark_MobileLandscape.png|181x181px]]
[[File:GEC_CS_Min_dark_MobilePortrait.png|150x150px]]
[[File:GEC_CS_Max_dark_MobileLandscape.png|186x186px]]
[[File:GEC_CS_Max_dark_MobilePortrait.png|150x150px]]

'''Light theme'''
<br />
[[File:GEC CS Avl light MobilePortrait.png|170x170px]]
[[File:GEC_CS_Avl_light_MobileLandscape.png|188x188px]]
[[File:GEC_CS_Avl_light.png|155x155px]]
[[File:GEC_CS_Max_light_MobileLandscape.png|181x181px]]
[[File:GEC_CS_MaxUnAvl_light_MobileLandscape.png|189x189px]]
[[File:GEC_CS_Min_light.png|166x166px]]
[[File:GEC_CS_Min_light_MobileLandscape.png|183x183px]]
[[File:GEC_CS_MaxUnAvl_light.png|161x161px]]
[[File:GEC_CS_Max_light_MobilePortrait.png|150x150px]]
[[File:GEC_CS_MaxUnAvl_light_MobilePortrait.png|150x150px]]
[[File:GEC_CS_Min_light_MobilePortrait.png|150x150px]]
|Status=No
}}{{Section
|sectionHeading=Configuration
|anchor=config
|alignment=Vertical
|structuredtext=ChannelSelector shares the '''_genesys.widgets.channelselector''' configuration namespace. ChannelSelector has UI options to enable and disable channels, hide channels, add new channels, and display estimated wait time (EWT) details. All the channels are displayed based on the array of objects order defined in the channel's configuration. To hide a particular channel, simply remove the corresponding array object.

{{NoteFormat|EWT can only be configured for WebChat, Callback, ClickToCall, and CallUs channels. It may not be applicable for other channels. If configured for the Send Message channel, it will always be shown as available regardless of any EWT value.|}}

==Example==
<syntaxhighlight lang="json">
window._genesys.widgets.channelselector = {

ewtRefreshInterval: 10,

channels: [{

enable: true,
clickCommand: 'CallUs.open',
displayName: 'Call Us',
i18n: 'CallusTitle',
icon: 'call-outgoing',
html: '<img src='http://placehold.it/100x100'>',
ewt: {
display: true,
queue: 'callus_ewt_test_eservices',
availabilityThresholdMin: 300,
availabilityThresholdMax: 480,
hideChannelWhenThresholdMax: false
}
},

{
enable: true,
clickCommand: 'WebChat.open',
displayName: 'Web Chat',
i18n: 'ChatTitle',
icon: 'chat',
html: '',
ewt: {
display: true,
queue: 'chat_ewt_test_eservices',
availabilityThresholdMin: 300,
availabilityThresholdMax: 480,
hideChannelWhenThresholdMax: false
}
},

{
enable: true,
clickCommand: 'Callback.open',
displayName: 'Receive a Call',
i18n: 'CallbackTitle',
icon: 'call-incoming',
html: '',
ewt: {
display: true,
queue: 'callback_ewt_test_eservices',
availabilityThresholdMin: 300,
availabilityThresholdMax: 480,
hideChannelWhenThresholdMax: false
}
},

};
</syntaxhighlight><br />
===Options===
{{{!}} class="wikitable"
{{!}}-
!{{!}}Name
!{{!}}Type
!{{!}}Description
!{{!}}Default
!{{!}}Required
{{!}}-
{{!}}{{!}}ewtRefreshInterval
{{!}}{{!}}number
{{!}}{{!}}EWT is updated for every time interval (seconds) defined here.
{{!}}{{!}}10
{{!}}{{!}}n/a
{{!}}-
{{!}}{{!}}channels[].enable
{{!}}{{!}}boolean
{{!}}{{!}}Enable/disable a channel.
{{!}}{{!}}true
{{!}}{{!}}n/a
{{!}}-
{{!}}{{!}}channels[].clickCommand
{{!}}{{!}}string
{{!}}{{!}}The CXBus command name for opening a particular Widget when this channel is clicked.
{{!}}{{!}}none
{{!}}{{!}}Always
{{!}}-
{{!}}{{!}}channels[].displayName
{{!}}{{!}}string
{{!}}{{!}}A channel name to display on ChannelSelector Widget.
{{!}}{{!}}none
{{!}}{{!}}Always
{{!}}-
{{!}}{{!}}channels[].i18n
{{!}}{{!}}string
{{!}}{{!}}To support localization of the channel display name, this takes a key parameter of the channelselector section in the language pack file. Overrides above displayName.
{{!}}{{!}}none
{{!}}{{!}}n/a
{{!}}-
{{!}}{{!}}channels[].icon
{{!}}{{!}}string
{{!}}{{!}}Select from one of the Genesys Widgets icons by specifying icon css class name.
{{!}}{{!}}none
{{!}}{{!}}Always
{{!}}-
{{!}}{{!}}channels[].html
{{!}}{{!}}string
{{!}}{{!}}Overrides and replaces the icon section of a channel with the html (image tag) defined here.
{{!}}{{!}}none
{{!}}{{!}}n/a
{{!}}-
{{!}}{{!}}channels[].ewt.display
{{!}}{{!}}boolean
{{!}}{{!}}To display EWT details.
{{!}}{{!}}true
{{!}}{{!}}n/a
{{!}}-
{{!}}{{!}}channels[].ewt.queue
{{!}}{{!}}string
{{!}}{{!}}EWT service channel virtual queue.
{{!}}{{!}}none
{{!}}{{!}}Always
{{!}}-
{{!}}{{!}}channels[].ewt.availabilityThresholdMin
{{!}}{{!}}number (seconds)
{{!}}{{!}}If EWT is greater than 0 minutes and less than this minimum threshold value (in minutes), then the EWT is shown with a yellow warning icon. {{NoteFormat|Comparison is made after converting the threshold value in seconds to minutes.|}}
{{!}}{{!}}300
{{!}}{{!}}n/a
{{!}}-
{{!}}{{!}}channels[].ewt.availabilityThresholdMax
{{!}}{{!}}number (seconds)
{{!}}{{!}}If EWT is greater than this minimum threshold value (in minutes) and less than the maximum threshold value (in minutes), then the EWT is shown with a red alert icon.{{NoteFormat|Comparison is made after converting the threshold value in seconds to minutes.|}}
{{!}}{{!}}480
{{!}}{{!}}n/a
{{!}}-
{{!}}{{!}}channels[].ewt.hideChannelWhenThresholdMax
{{!}}{{!}}boolean
{{!}}{{!}}Hides this channel when EWT is greater than the maximum threshold value.
{{!}}{{!}}true
{{!}}{{!}}n/a
{{!}}}
|Status=No
}}{{Section
|sectionHeading=Localization
|anchor=localize
|alignment=Vertical
|structuredtext={{NoteFormat|For information on how to set up localization, refer to {{Link-AnywhereElse|product=WID|version=Current|manual=Developer|topic=GWCInternat|display text=Localize widgets and services}}.|1}}
===Usage===
Use the '''channelselector''' namespace when you define localization strings for the ChannelSelector plugin in your i18n JSON file.

The following example shows how to define new strings for the '''en''' (English) language. You can use any language codes you wish; there is no standard format. When selecting the active language in your configuration, you must match one of the language codes defined in your i18n JSON file. You must only define a language code once in your i18n JSON file. Inside each language object you must define new strings for each Widget.
===Example i18n JSON===
<source lang="javascript">{
"en": {
"channelselector": {
"Title": "Live Assistance",
"SubTitle": "How would you like to get in touch?",
"WaitTimeTitle": "Wait Time",
"AvailableTitle": "Available",
"AriaAvailableTitle": "Available",
"UnavailableTitle": "Unavailable",
"CallbackTitle": "Receive a Call",
"AriaClose": "Live Assistance Close",
"AriaWarning": "Warning",
"AriaAlert": "Alert",
"minute": "min",
"minutes": "mins",
"AriaWindowLabel": "Live Assistance Window"
}
}
}</source>
|Status=No
}}{{Section
|sectionHeading=API commands
|anchor=commands
|alignment=Vertical
|structuredtext=Once you've registered your plugin on the bus, you can call commands on other registered plugins. Here's how to use the global bus object to register a new plugin on the bus.

{{NoteFormat|The global bus object is a debugging tool. When implementing Widgets on your own site, do not use the global bus object to register your custom plugins. Instead, see {{Link-AnywhereElse|product=WID|version=Current|manual=SDK|topic=GWCBusExtensions|display text=Genesys Widgets Extensions}} for more information about extending Genesys Widgets.|1}}

<source lang="javascript">var oMyPlugin = window._genesys.widgets.bus.registerPlugin('MyPlugin');

oMyPlugin.command('ChannelSelector.open');</source>
===close===
Closes the ChannelSelector UI.
====Example====
<source lang="javascript">
oMyPlugin.command('ChannelSelector.close').done(function(e){

// ChannelSelector closed successfully

}).fail(function(e){

// ChannelSelector failed to close
});
</source>

====Resolutions====

{{{!}} class="wikitable"
{{!}}-
!{{!}}Status
!{{!}}When
!{{!}}Returns
{{!}}-
{{!}}{{!}}resolved
{{!}}{{!}}ChannelSelector is successfully closed
{{!}}{{!}}n/a
{{!}}-
{{!}}{{!}}rejected
{{!}}{{!}}ChannelSelector is already closed
{{!}}{{!}}Already closed
{{!}}}

===open===
Opens the ChannelSelector UI.
====Example====
<source lang="javascript">
oMyPlugin.command('ChannelSelector.open').done(function(e){

// ChannelSelector opened successfully

}).fail(function(e){

// ChannelSelector failed to open
});
</source>

====Resolutions====

{{{!}} class="wikitable"
{{!}}-
!{{!}}Status
!{{!}}When
!{{!}}Returns
{{!}}-
{{!}}{{!}}resolved
{{!}}{{!}}ChannelSelector Widget is successfully opened
{{!}}{{!}}n/a
{{!}}-
{{!}}{{!}}rejected
{{!}}{{!}}ChannelSelector Widget is already open
{{!}}{{!}}'Already open'
{{!}}}

===configure===
Modifies the ChannelSelector configuration.
====Example====
<source lang="javascript">
oMyPlugin.command('ChannelSelector.configure', {

channels: [
{
enabled: true,
clickCommand: 'CallUs.open',
readyEvent: 'CallUs.ready',
displayName: 'Call Us',
i18n: 'CallusTitle',
icon: 'call-outgoing',
html: '',
ewt:{

display: true,
queue:'chat_ewt_test_eservices',
availabilityThresholdMin:60,
availabilityThresholdMax:600
}
}
]

}).done(function(e){

// ChannelSelector configured successfully

}).fail(function(e){

// ChannelSelector failed to configure
});
</source>

====Options====

{{{!}} class="wikitable"
{{!}}-
!{{!}}Option
!{{!}}Type
!{{!}}Description
{{!}}-
{{!}}{{!}}ewtRefreshInterval
{{!}}{{!}}number
{{!}}{{!}}EWT is updated for every time interval (seconds) is defined.
{{!}}-
{{!}}{{!}}channels
{{!}}{{!}}array
{{!}}{{!}}Array containing each channel configuration object. The order of channels is displayed based on the order defined here.
{{!}}-
{{!}}{{!}}channels[].enable
{{!}}{{!}}boolean
{{!}}{{!}}Enable/disable chat channel.
{{!}}-
{{!}}{{!}}channels[].clickCommand
{{!}}{{!}}string
{{!}}{{!}}The CXBus command name for opening a particular Widget when this channel is clicked.
{{!}}-
{{!}}{{!}}channels[].readyEvent
{{!}}{{!}}string
{{!}}{{!}}Subscribes to this ready event published by a plugin and enables the channel when that plugin is ready.
{{!}}-
{{!}}{{!}}channels[].displayName
{{!}}{{!}}string
{{!}}{{!}}A channel name to display in the ChannelSelector Widget.
{{!}}-
{{!}}{{!}}channels[].i18n
{{!}}{{!}}string
{{!}}{{!}}To support localization of channel display name, this takes a key parameter of the channelselector section in the language pack file. Overrides above displayName.
{{!}}-
{{!}}{{!}}channels[].icon
{{!}}{{!}}string
{{!}}{{!}}Select from one of the Genesys Widgets icons by specifying icon css class name.
{{!}}-
{{!}}{{!}}channels[].html
{{!}}{{!}}string
{{!}}{{!}}Overrides and replaces the icon section of a channel with the html (image tag) defined here.
{{!}}-
{{!}}{{!}}channels[].ewt.display
{{!}}{{!}}boolean
{{!}}{{!}}To display EWT details.
{{!}}-
{{!}}{{!}}channels[].ewt.queue
{{!}}{{!}}string
{{!}}{{!}}EWT service channel virtual queue name.
{{!}}-
{{!}}{{!}}channels[].ewt.availabilityThresholdMin
{{!}}{{!}}number (seconds)
{{!}}{{!}}If EWT is greater than 0 minutes and less than this minimum threshold value (in minutes), then the EWT is shown with a yellow warning icon.
Note: Comparison is made after converting the threshold
value in seconds to minutes.
{{!}}-
{{!}}{{!}}channels[].ewt.availabilityThresholdMax
{{!}}{{!}}number (seconds)
{{!}}{{!}}If EWT is greater than this minimum threshold value (in minutes) and less than the maximum threshold value (in minutes), then the EWT is shown with a red alert icon.
Note: Comparison is made after converting the threshold
value in seconds to minutes.
{{!}}-
{{!}}{{!}}channels[].ewt.hideChannelWhenThresholdMax
{{!}}{{!}}boolean
{{!}}{{!}}Hides this channel when EWT is greater than the maximum threshold value.
{{!}}}

====Resolutions====

{{{!}} class="wikitable"
{{!}}-
!{{!}}Status
!{{!}}When
!{{!}}Returns
{{!}}-
{{!}}{{!}}resolved
{{!}}{{!}}Configuration options are provided and set
{{!}}{{!}}n/a
{{!}}-
{{!}}{{!}}rejected
{{!}}{{!}}No configuration options are provided
{{!}}{{!}}'Invalid configuration'
{{!}}}

===displayStats===
Displays estimated wait time (EWT) and availability details for each channel.
====Example====
<source lang="javascript">
oMyPlugin.command('ChannelSelector.displayStats').done(function(e){

// ChannelSelector displayed stats successfully

}).fail(function(e){

// ChannelSelector failed to display stats
});
</source>

====Resolutions====

{{{!}} class="wikitable"
{{!}}-
!{{!}}Status
!{{!}}When
!{{!}}Returns
{{!}}-
{{!}}{{!}}resolved
{{!}}{{!}}EWT is displayed successfully
{{!}}{{!}}n/a
{{!}}-
{{!}}{{!}}rejected
{{!}}{{!}}StatsService fails to retrieve EWT data
{{!}}{{!}}'Unable to display EWT Stats in ChannelSelector'
{{!}}-
{{!}}{{!}}rejected
{{!}}{{!}}enableEwt config is disabled or when required channel plugins are not ready
{{!}}{{!}}'Either EWT config is disabled or plugins not yet ready'
{{!}}}

===disableStats===
Clears the UI of any EWT. Disables EWT fetching for the defined time interval.
====Example====
<source lang="javascript">
oMyPlugin.command('ChannelSelector.disableStats').done(function(e){

// ChannelSelector disabled stats successfully

}).fail(function(e){

// ChannelSelector failed to disable stats
});
</source>

====Resolutions====

{{{!}} class="wikitable"
{{!}}-
!{{!}}Status
!{{!}}When
!{{!}}Returns
{{!}}-
{{!}}{{!}}resolved
{{!}}{{!}}ChannelSelector Widget is successfully opened
{{!}}{{!}}n/a
{{!}}-
{{!}}{{!}}rejected
{{!}}{{!}}ChannelSelector Widget is not opened
{{!}}{{!}}'ChannelSelector not opened to disable stats details'
{{!}}-
{{!}}{{!}}rejected
{{!}}{{!}}EWT is disabled for all channels
{{!}}{{!}}'Stats already disabled'
{{!}}}

===enableStats===
Displays EWT and availability details in the UI. Enables fetching EWT for the defined time interval.
====Example====
<source lang="javascript">
oMyPlugin.command('ChannelSelector.enableStats').done(function(e){

// ChannelSelector enabled stats successfully

}).fail(function(e){

// ChannelSelector failed to enable stats
});
</source>

====Resolutions====

{{{!}} class="wikitable"
{{!}}-
!{{!}}Status
!{{!}}When
!{{!}}Returns
{{!}}-
{{!}}{{!}}resolved
{{!}}{{!}}ChannelSelector Widget is successfully opened
{{!}}{{!}}n/a
{{!}}-
{{!}}{{!}}rejected
{{!}}{{!}}EWT details are already displayed
{{!}}{{!}}'Stats already enabled'
{{!}}-
{{!}}{{!}}rejected
{{!}}{{!}}ChannelSelector Widget is not opened
{{!}}{{!}}'ChannelSelector not opened to enable stats details'
{{!}}}
|Status=No
}}{{Section
|sectionHeading=API events
|anchor=events
|alignment=Vertical
|structuredtext=Once you've registered your plugin on the bus, you can subscribe to and listen for published events. Here's how to use the global bus object to register a new plugin on the bus.

{{NoteFormat|The global bus object is a debugging tool. When implementing Widgets on your own site, do not use the global bus object to register your custom plugins. Instead, see {{Link-AnywhereElse|product=WID|version=Current|manual=SDK|topic=GWCBusExtensions|display text=Genesys Widgets Extensions}} for more information about extending Genesys Widgets.|1}}

<source lang="javascript">var oMyPlugin = window._genesys.widgets.bus.registerPlugin('MyPlugin');

oMyPlugin.subscribe('ChannelSelector.ready', function(e){});</source>
{{{!}} class="wikitable"
{{!}}-
!{{!}}Name
!{{!}}Description
!{{!}}Data
{{!}}-
{{!}}{{!}}ready
{{!}}{{!}}ChannelSelector plugin is initialized and ready to accept commands
{{!}}{{!}}n/a
{{!}}-
{{!}}{{!}}opened
{{!}}{{!}}ChannelSelector Widget has appeared on screen
{{!}}{{!}}n/a
{{!}}-
{{!}}{{!}}closed
{{!}}{{!}}ChannelSelector Widget has been removed from the screen
{{!}}{{!}}n/a
{{!}}}
|Status=No
}}
}}