Difference between revisions of "WID/Current/SDK/WebChatService-combined"

From Genesys Documentation
Jump to: navigation, search
(Published)
(Published)
Line 8: Line 8:
 
|Role=Developer
 
|Role=Developer
 
|Section={{Section
 
|Section={{Section
−
|sectionHeading=API Events
+
|sectionHeading=Overview
−
|anchor=events
 
 
|alignment=Vertical
 
|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.
+
|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.
  
−
{{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|anchor=top|display text=Widgets Extensions}} for more information about extending Genesys Widgets.|1}}
+
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.
  
−
<source lang="javascript">var oMyPlugin = window._genesys.widgets.bus.registerPlugin('MyPlugin');
+
===Namespace===
  
−
oMyPlugin.subscribe('WebChatService.ready', function(e){});</source>
+
The WebChat Service plugin has the following namespaces tied up with each of the following types:
  
 
{{{!}}
 
{{{!}}
 
{{!}}-
 
{{!}}-
−
!Name
+
!{{!}}Type
−
!Description
+
!{{!}}Namespace
−
!Data
+
{{!}}-
−
!Introduced / Updated
+
{{!}}{{!}}{{Link-SomewhereInThisVersion|manual=SDK|topic=WebChatService-combined|anchor=config|display text=Configuration}}
 +
{{!}}{{!}}webchat
 
{{!}}-
 
{{!}}-
−
{{!}}ready
+
{{!}}{{!}}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 is initialized and ready to accept commands.
+
{{!}}{{!}}WebChatService
−
{{!}}n/a
+
{{!}}}
−
{{!}}
+
 
−
{{!}}-
+
===Customization===
−
{{!}}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.
+
WebChatService has many configuration options but no customization options. It is a plug-and-play plugin and works as is.
−
{{!}}{async: (boolean)}
+
|Status=No
−
{{!}}9.0.002.06
+
}}{{Section
−
{{!}}-
+
|sectionHeading=Configuration
−
{{!}}restoreTimeout
+
|anchor=config
−
{{!}}Chat session restoration attempted was denied after user navigated away from originating website for longer than the time limit: default 60 seconds.
+
|alignment=Vertical
−
{{!}}n/a
+
|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 {{Link-SomewhereInThisVersion|manual=SDK|topic=WebChatService-combined|anchor=configoptions|display text=available}} in Genesys via the transport section configuration {{Link-SomewhereInThisVersion|manual=SDK|topic=WebChatService-combined|anchor=t-1|display text=options}}.}}
−
{{!}}restoreFailed
+
 
−
{{!}}Could not restore chat session after page navigation or refresh.
+
{{AnchorDiv|mainexample}}
−
{{!}}n/a
+
===Example===
−
{{!}}
+
 
−
{{!}}-
+
<pre>
−
{{!}}restoredOffline
+
// When using GMS API
−
{{!}}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
+
window._genesys.widgets.webchat = {
−
{{!}}
+
 
−
{{!}}-
+
apikey: 'n3eNkgxxxxxxxxxxxx8VA',
−
{{!}}messageReceived
+
dataURL: 'https://api.genesyscloud.com/gms-chat/2/chat',
−
{{!}}A new message has been received from the server. Includes text messages, status messages, notices, and other message types.
+
enableCustomHeader: true,
−
{{!}}{originalMessages: (object), messages: (array of objects), restoring: (boolean), sessionData: (object)}
+
 
−
{{!}}9.0.002.06
+
userData: {},
−
{{!}}-
+
emojis: true,
−
{{!}}error
+
actionsMenu: true,
−
{{!}}An error occurred between the client and the server.
+
 
−
{{!}}(AJAX Response)
+
autoInvite: {
−
{{!}}
+
 
−
{{!}}-
+
enabled: false,
−
{{!}}started
+
timeToInviteSeconds: 10,
−
{{!}}Chat session has successfully started.
+
inviteTimeoutSeconds: 30
−
{{!}}(AJAX Response containing session data)
+
},
−
{{!}}
+
 
−
{{!}}-
+
chatButton: {
−
{{!}}ended
+
 
−
{{!}}Chat session has successfully ended.
+
enabled: true,
−
{{!}}n/a
+
template: '<div>CHAT NOW</div>',
−
{{!}}
+
effect: 'fade',
−
{{!}}-
+
openDelay: 1000,
−
{{!}}agentTypingStarted
+
effectDuration: 300,
−
{{!}}Agents has started typing a new message.
+
hideDuringInvite: true
−
{{!}}(AJAX Response)
+
}
−
{{!}}
+
};
−
{{!}}-
+
 
−
{{!}}agentTypingStopped
+
// When using PureEngage v3 API
−
{{!}}Agent has stopped typing.
+
 
−
{{!}}(AJAX Response)
+
window._genesys.widgets.webchat = {
−
{{!}}
+
 
−
{{!}}-
+
emojis: true,
−
{{!}}pollingStarted
+
userData: {},
−
{{!}}Chat server automatic polling has started.
+
transport: {
−
{{!}}n/a
+
 
−
{{!}}
+
type: 'pureengage-v3-rest',
−
{{!}}-
+
dataURL: https://<hostname>/nexus/v3/chat/sessions,
−
{{!}}pollingStopped
+
endpoint: 'xxxxxxxxx',
−
{{!}}Chat server automatic polling has stopped.
+
headers: {
−
{{!}}n/a
+
'x-api-key': 'xxxxxxxx'
−
{{!}}
+
},
−
{{!}}-
+
async: {
−
{{!}}clientConnected
+
 
−
{{!}}Indicates the user has been connected to the chat session.
+
enabled: true,
−
{{!}}{message: (object), agents: (object), numAgentsConnected: (number)}
+
 
−
{{!}}
+
getSessionData: function(sessionData, Cookie, CookieOptions) {
−
{{!}}-
+
 
−
{{!}}clientDisconnected
+
// Note: You don't have to use Cookies. You can, instead, store in a secured location like a database.
−
{{!}}Indicates the user has been disconnected form the chat session.
+
Cookie.set('customer-defined-session-cookie', JSON.stringify(sessionData), CookieOptions);
−
{{!}}{message: (object), agents: (object), numAgentsConnected: (number)}
+
},
−
{{!}}
+
 
−
{{!}}-
+
setSessionData: function(Open, Cookie, CookieOptions) {
−
{{!}}agentConnected
+
 
−
{{!}}Indicates an agent has connected to the chat.
+
// Retrieve from your secured location.
−
{{!}}{message: (object), agents: (object), numAgentsConnected: (number)}
+
return Cookie.get('customer-defined-session-cookie');
−
{{!}}
+
}
−
{{!}}-
+
},
−
{{!}}agentDisconnected
+
 
−
{{!}}Indicates an agent has disconnected from the chat.
+
chatButton: {
−
{{!}}{message: (object), agents: (object), numAgentsConnected: (number)}
+
 
−
{{!}}
+
enabled: true,
−
{{!}}-
+
template: '<div>CHAT NOW</div>',
−
{{!}}supervisorConnected
+
effect: 'fade',
−
{{!}}Indicates a supervisor has connected to the chat.
+
openDelay: 1000,
−
{{!}}{message: (object), agents: (object), numAgentsConnected: (number)}
+
effectDuration: 300,
−
{{!}}
+
hideDuringInvite: true
−
{{!}}-
+
}
−
{{!}}supervisorDisconnected
+
};
−
{{!}}Indicates a supervisor has disconnected from the chat.
+
</pre>
−
{{!}}{message: (object), agents: (object), numAgentsConnected: (number)}
+
 
 +
{{AnchorDiv|configoptions}}
 +
===Options===
 +
 
 +
<nowiki><tabber></nowiki>
 +
GMS API=
 +
{{{!}}  
 +
{{!}}-  
 +
!Name
 +
!Type
 +
!Description
 +
!Default
 +
!Required
 +
!Introduced / Updated
 +
{{!}}-
 +
{{!}}apikey
 +
{{!}}string
 +
{{!}}Apigee Proxy secure token.
 +
{{!}}n/a
 +
{{!}}Yes, if using Apigee Proxy
 
{{!}}
 
{{!}}
−
{{!}}-
+
{{!}}-  
−
{{!}}botConnected
+
{{!}}endpoint
−
{{!}}<nowiki>Indicates a bot has connected to the chat.
+
{{!}}string
−
{{NoteFormat</nowiki>
+
{{!}}Manually select the endpoint to initiate chat on.
−
{{!}}<nowiki>This event is applicable only when using {{Link-SomewhereInThisManual</nowiki>
 
−
{{!}}topic=WebChatService-combined
 
−
{{!}}anchor=configoptions
 
−
{{!}}<nowiki>display text=WebChat with GMS API}}.}}</nowiki>
 
−
{{!}}{message: (object), agents: (object), numAgentsConnected: (number)}
 
−
{{!}}9.0.014.13
 
−
{{!}}-
 
−
{{!}}botDisconnected
 
−
{{!}}<nowiki>Indicates a bot has disconnected from the chat.
 
−
{{NoteFormat</nowiki>
 
−
{{!}}<nowiki>This event is applicable only when using {{Link-SomewhereInThisManual</nowiki>
 
−
{{!}}topic=WebChatService-combined
 
−
{{!}}anchor=configoptions
 
−
{{!}}<nowiki>display text=WebChat with GMS API}}.}}</nowiki>
 
−
{{!}}{message: (object), agents: (object), numAgentsConnected: (number)}
 
−
{{!}}9.0.014.13
 
−
{{!}}-
 
−
{{!}}clientTypingStarted
 
−
{{!}}The user has started typing. Sends an event to the agent.
 
 
{{!}}n/a
 
{{!}}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
 
{{!}}n/a
 
{{!}}
 
{{!}}
−
{{!}}-
+
{{!}}-  
−
{{!}}disconnected
+
{{!}}dataURL
−
{{!}}Cannot reach servers. No connection. Either the user is offline or the server is offline.
+
{{!}}string (URL)
 +
{{!}}URL for GMS REST chat service. If cometD.enabled is set to true, this property will be ignored.
 
{{!}}n/a
 
{{!}}n/a
 +
{{!}}Always
 
{{!}}
 
{{!}}
−
{{!}}-
+
{{!}}-  
−
{{!}}reconnected
+
{{!}}enableCustomHeader
−
{{!}}Connection restored. This event is only published after 'disconnected'.
+
{{!}}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
 
{{!}}n/a
 
{{!}}
 
{{!}}
−
{{!}}-
+
{{!}}-  
−
{{!}}chatServerWentOffline
+
{{!}}ajaxTimeout
−
{{!}}<nowiki>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.
+
{{!}}number
−
 
+
{{!}}Number of milliseconds to wait before AJAX timeout.
−
{{NoteFormat</nowiki>
+
{{!}}3000
−
{{!}}<nowiki>This event is applicable only when using {{Link-SomewhereInThisManual</nowiki>
 
−
{{!}}topic=WebChatService-combined
 
−
{{!}}anchor=configoptions
 
−
{{!}}<nowiki>display text=WebChat with GMS API}}.}}</nowiki>
 
 
{{!}}n/a
 
{{!}}n/a
 
{{!}}
 
{{!}}
−
{{!}}-
+
{{!}}-  
−
{{!}}chatServerBackOnline
+
{{!}}xhrFields
−
{{!}}<nowiki>Chat server had come back online after going offline. This will only be published after 'chatServerWentOffline'.
+
{{!}}object
−
 
+
{{!}}Allows you to set the properties for the AJAX xhrFields object (for example, {withCredentials: false}).
−
{{NoteFormat</nowiki>
+
{{!}}{withCredentials: false}
−
{{!}}<nowiki>This event is applicable only when using {{Link-SomewhereInThisManual</nowiki>
 
−
{{!}}topic=WebChatService-combined
 
−
{{!}}anchor=configoptions
 
−
{{!}}<nowiki>display text=WebChat with GMS API}}.}}</nowiki>
 
 
{{!}}n/a
 
{{!}}n/a
 
{{!}}
 
{{!}}
−
{{!}}-
+
{{!}}-  
−
{{!}}connectionPending
+
{{!}}pollExceptionLimit
−
{{!}}<nowiki>If there is a connection problem and WebChatService is trying to reconnect, this event will be published. Published before 'chatServerWentOffline'.
+
{{!}}number
−
 
+
{{!}}Number of successive poll exceptions (chat server offline) before WebChatService publishes 'chatServerWentOffline'.
−
{{NoteFormat</nowiki>
+
{{!}}5
−
{{!}}<nowiki>This event is applicable only when using {{Link-SomewhereInThisManual</nowiki>
 
−
{{!}}topic=WebChatService-combined
 
−
{{!}}anchor=configoptions
 
−
{{!}}<nowiki>display text=WebChat with GMS API}}.}}</nowiki>
 
 
{{!}}n/a
 
{{!}}n/a
 
{{!}}
 
{{!}}
−
{{!}}-
+
{{!}}-  
−
{{!}}connectionRestored
+
{{!}}restoreTimeout
−
{{!}}Is published when the connection has be reestablished. Publishes at the same time as 'chatServerBackOnline'.
+
{{!}}number
−
{{!}}n/a
+
{{!}}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
 +
{{!}}
 
{{!}}
 
{{!}}
−
{{!}}-
+
{{!}}-  
 
{{!}}}
 
{{!}}}
 
|Status=No
 
|Status=No
 
}}{{Section
 
}}{{Section
−
|sectionHeading=Overview
+
|sectionHeading=Localization
 +
|anchor=localize
 +
|alignment=Vertical
 +
|structuredtext=WebChatService doesn't have any localization options.
 +
|Status=No
 +
}}{{Section
 +
|sectionHeading=API Commands
 +
|anchor=commands
 
|alignment=Vertical
 
|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.
+
|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|anchor=top|display text=Widgets Extensions}} for more information about extending Genesys Widgets.|1}}
  
−
===Usage===
+
<source lang="javascript">var oMyPlugin = window._genesys.widgets.bus.registerPlugin('MyPlugin');
  
−
WebChatService and the matching WebChat widget work together right out of the box and they share the same configuration object. Using WebChat uses WebChatService.
+
oMyPlugin.command('WebChatService.getAgents');</source>
  
−
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.
+
{{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=configoptions|display text=WebChatService Configuration.}}|1}}
  
−
===Namespace===
+
===configure===
  
−
The WebChat Service plugin has the following namespaces tied up with each of the following types:
+
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.
  
−
{{{!}}
+
===startChat===
−
{{!}}-
 
−
!{{!}}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===
+
Initiates a new chat session with the chat server via GMS or with the service configured under transport section. For use by WebChat widgets only. You must not invoke this manually.
  
−
WebChatService has many configuration options but no customization options. It is a plug-and-play plugin and works as is.
+
====Example====
−
|Status=No
+
<source lang="javascript">
−
}}{{Section
+
oMyPlugin.command('WebChatService.startChat', {
−
|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 {{Link-SomewhereInThisVersion|manual=SDK|topic=WebChatService-combined|anchor=configoptions|display text=available}} in Genesys via the transport section configuration {{Link-SomewhereInThisVersion|manual=SDK|topic=WebChatService-combined|anchor=t-1|display text=options}}.}}
+
nickname: 'Jonny',
−
 
+
firstname: 'Johnathan',
−
{{AnchorDiv|mainexample}}
+
lastname: 'Smith',
−
===Example===
+
email: 'jon.smith@mail.com',
 +
subject: 'product questions',
 +
userData: {}
  
−
<pre>
+
}).done(function(e){
−
// When using GMS API
 
  
−
window._genesys.widgets.webchat = {
+
// WebChatService started a chat successfully
  
−
apikey: 'n3eNkgxxxxxxxxxxxx8VA',
+
}).fail(function(e){
−
dataURL: 'https://api.genesyscloud.com/gms-chat/2/chat',
 
−
enableCustomHeader: true,
 
  
−
userData: {},
+
// WebChatService failed to start chat
−
emojis: true,
+
});
−
actionsMenu: true,
+
</source>
  
−
autoInvite: {
+
====Options====
  
−
enabled: false,
+
{{{!}}
−
timeToInviteSeconds: 10,
+
{{!}}-
−
inviteTimeoutSeconds: 30
+
!Option
−
},
+
!Type
−
 
+
!Description
−
chatButton: {
+
{{!}}-
−
 
+
{{!}}nickname
−
enabled: true,
+
{{!}}string
−
template: '<div>CHAT NOW</div>',
+
{{!}}Chat Entry Form Data: 'nickname'.
−
effect: 'fade',
+
{{!}}-
−
openDelay: 1000,
+
{{!}}firstname
−
effectDuration: 300,
+
{{!}}string
−
hideDuringInvite: true
+
{{!}}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.
 +
{{!}}-
 +
{{!}}}  
  
−
// When using PureEngage v3 API
+
====Resolutions====
  
−
window._genesys.widgets.webchat = {
+
{{{!}}
−
 
+
{{!}}-
−
emojis: true,
+
!Status
−
userData: {},
+
!When
−
transport: {
+
!Returns
 +
{{!}}-
 +
{{!}}resolved
 +
{{!}}When server confirms session started
 +
{{!}}(AJAX Response Object)
 +
{{!}}-
 +
{{!}}rejected
 +
{{!}}When a chat session is already active
 +
{{!}}'There is already an active chat session'
 +
{{!}}-
 +
{{!}}rejected
 +
{{!}}When AJAX exception occurs
 +
{{!}}(AJAX Response Object)
 +
{{!}}-
 +
{{!}}rejected
 +
{{!}}When server exception occurs
 +
{{!}}(AJAX Response Object)
 +
{{!}}-
 +
{{!}}rejected
 +
{{!}}When userData is invalid
 +
{{!}}'malformed data object provided in userData property'
 +
{{!}}-
 +
{{!}}}
 +
 
 +
===endChat===
  
−
type: 'pureengage-v3-rest',
+
Ends the chat session with the chat server via GMS or with the service configured under transport section. For use by WebChat widgets only. You must not invoke this manually.
−
dataURL: https://<hostname>/nexus/v3/chat/sessions,
 
−
endpoint: 'xxxxxxxxx',
 
−
headers: {
 
−
'x-api-key': 'xxxxxxxx'
 
−
},
 
−
async: {
 
  
−
enabled: true,
+
====Example====
 +
<source lang="javascript">
 +
oMyPlugin.command('WebChatService.endChat').done(function(e){
  
−
getSessionData: function(sessionData, Cookie, CookieOptions) {
+
// WebChatService ended a chat successfully
  
−
// Note: You don't have to use Cookies. You can, instead, store in a secured location like a database.
+
}).fail(function(e){
−
Cookie.set('customer-defined-session-cookie', JSON.stringify(sessionData), CookieOptions);
 
−
},
 
  
−
setSessionData: function(Open, Cookie, CookieOptions) {
+
// WebChatService failed to end chat
 +
});
 +
</source>
  
−
// Retrieve from your secured location.
+
====Resolutions====
−
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|configoptions}}
 
−
===Options===
 
−
 
−
<nowiki><tabber></nowiki>
 
−
GMS API=
 
 
{{{!}}  
 
{{{!}}  
 
{{!}}-  
 
{{!}}-  
−
!Name
+
!Status
−
!Type
+
!When
−
!Description
+
!Returns
−
!Default
 
−
!Required
 
−
!Introduced / Updated
 
 
{{!}}-  
 
{{!}}-  
−
{{!}}apikey
+
{{!}}resolved
−
{{!}}string
+
{{!}}When active session is ended successfully
−
{{!}}Apigee Proxy secure token.
+
{{!}}(AJAX Response Object)
−
{{!}}n/a
 
−
{{!}}Yes, if using Apigee Proxy
 
−
{{!}}
 
 
{{!}}-  
 
{{!}}-  
−
{{!}}endpoint
+
{{!}}rejected
−
{{!}}string
+
{{!}}If no chat session is currently active
−
{{!}}Manually select the endpoint to initiate chat on.
+
{{!}}'There is no active chat session'
−
{{!}}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.
+
===sendMessage===
−
{{!}}n/a
+
 
−
{{!}}Always
+
Sends a message from the client to the chat session. For use by WebChat widgets only. You must not invoke this manually.
−
{{!}}
+
 
 +
====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
 
{{!}}-  
 
{{!}}-  
−
{{!}}enableCustomHeader
+
{{!}}message
−
{{!}}boolean
+
{{!}}string
−
{{!}}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.
+
{{!}}The message you want to send
−
{{!}}false
 
−
{{!}}No
 
−
{{!}}9.0.002.06
 
 
{{!}}-  
 
{{!}}-  
−
{{!}}userData
+
{{!}}}
−
{{!}}object
+
 
−
{{!}}Arbitrary attached data to include when initiating a chat.
+
====Resolutions====
−
{{!}}{}
+
 
−
{{!}}n/a
+
{{{!}}  
−
{{!}}
 
 
{{!}}-  
 
{{!}}-  
−
{{!}}ajaxTimeout
+
!Status
−
{{!}}number
+
!When
−
{{!}}Number of milliseconds to wait before AJAX timeout.
+
!Returns
−
{{!}}3000
 
−
{{!}}n/a
 
−
{{!}}
 
 
{{!}}-  
 
{{!}}-  
−
{{!}}xhrFields
+
{{!}}resolved
−
{{!}}object
+
{{!}}When message is successfully sent
−
{{!}}Allows you to set the properties for the AJAX xhrFields object (for example, {withCredentials: false}).
+
{{!}}(AJAX Response Object)
−
{{!}}{withCredentials: false}
 
−
{{!}}n/a
 
−
{{!}}
 
 
{{!}}-  
 
{{!}}-  
−
{{!}}pollExceptionLimit
+
{{!}}rejected
−
{{!}}number
+
{{!}}If no message text provided
−
{{!}}Number of successive poll exceptions (chat server offline) before WebChatService publishes 'chatServerWentOffline'.
+
{{!}}'No message text provided'
−
{{!}}5
 
−
{{!}}n/a
 
−
{{!}}
 
 
{{!}}-  
 
{{!}}-  
−
{{!}}restoreTimeout
+
{{!}}rejected
−
{{!}}number
+
{{!}}If no chat session is currently active
−
{{!}}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).
+
{{!}}'There is no active chat session'
−
{{!}}60000
 
−
{{!}}
 
−
{{!}}
 
 
{{!}}-  
 
{{!}}-  
−
{{!}}}
+
{{!}}rejected
−
|Status=No
+
{{!}}When AJAX exception occurs
−
}}{{Section
+
{{!}}(AJAX Response Object)
−
|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-SomewhereInThisManual|topic=GWCBusExtensions|anchor=top|display text=Widgets Extensions}} for more information about extending Genesys Widgets.|1}}
+
===sendCustomNotice===
  
−
<source lang="javascript">var oMyPlugin = window._genesys.widgets.bus.registerPlugin('MyPlugin');
+
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  use this out of the box.
  
−
oMyPlugin.command('WebChatService.getAgents');</source>
+
====Example====
  
−
{{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=configoptions|display text=WebChatService Configuration.}}|1}}
+
<source lang="javascript">
 +
oMyPlugin.command('WebChatService.sendCustomNotice', {message: 'bye'}).done(function(e){
  
−
===configure===
+
// WebChatService sent a custom message successfully
−
 
 
−
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.
 
−
 
 
−
===startChat===
 
−
 
 
−
Initiates a new chat session with the chat server via GMS or with the service configured under transport section. For use by WebChat widgets only. You must not invoke this manually.
 
−
 
 
−
====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){
 
}).fail(function(e){
  
−
// WebChatService failed to start chat
+
// WebChatService failed to send a custom message
 
});
 
});
 
</source>
 
</source>
Line 453: Line 429:
 
!Description
 
!Description
 
{{!}}-  
 
{{!}}-  
−
{{!}}nickname
+
{{!}}message
 
{{!}}string
 
{{!}}string
−
{{!}}Chat Entry Form Data: 'nickname'.
+
{{!}}A message you want to send along with the custom notice
−
{{!}}-
 
−
{{!}}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====
 
====Resolutions====
−
 
 
{{{!}}  
 
{{{!}}  
 
{{!}}-  
 
{{!}}-  
Line 486: Line 441:
 
!When
 
!When
 
!Returns
 
!Returns
 +
!Introduced / Updated
 
{{!}}-  
 
{{!}}-  
 
{{!}}resolved
 
{{!}}resolved
−
{{!}}When server confirms session started
+
{{!}}When message is successfully sent
 
{{!}}(AJAX Response Object)
 
{{!}}(AJAX Response Object)
−
{{!}}-
+
{{!}}
−
{{!}}rejected
 
−
{{!}}When a chat session is already active
 
−
{{!}}'There is already an active chat session'
 
 
{{!}}-  
 
{{!}}-  
 
{{!}}rejected
 
{{!}}rejected
 
{{!}}When AJAX exception occurs
 
{{!}}When AJAX exception occurs
 
{{!}}(AJAX Response Object)
 
{{!}}(AJAX Response Object)
 +
{{!}}
 
{{!}}-  
 
{{!}}-  
 
{{!}}rejected
 
{{!}}rejected
−
{{!}}When server exception occurs
+
{{!}}When the server doesn't support receiving custom notices
−
{{!}}(AJAX Response Object)
+
{{!}}This transport doesn't support sendCustomNotice command.
−
{{!}}-
+
{{!}}9.0.008.04
−
{{!}}rejected
 
−
{{!}}When userData is invalid
 
−
{{!}}'malformed data object provided in userData property'
 
 
{{!}}-  
 
{{!}}-  
 
{{!}}}  
 
{{!}}}  
  
−
===endChat===
+
===sendTyping===
  
−
Ends the chat session with the chat server via GMS or with the service configured under transport section. For use by WebChat widgets only. You must not invoke this manually.
+
Sends a 'customer typing' notification to chat session. A visual indication will be shown to agent. For use by WebChat widgets only. You must not invoke this manually.
  
 
====Example====
 
====Example====
 +
 
<source lang="javascript">
 
<source lang="javascript">
−
oMyPlugin.command('WebChatService.endChat').done(function(e){
+
oMyPlugin.command('WebChatService.sendTyping').done(function(e){
  
−
// WebChatService ended a chat successfully
+
// WebChatService sent typing successfully
  
 
}).fail(function(e){
 
}).fail(function(e){
  
−
// WebChatService failed to end chat
+
// WebChatService failed to send typing
 
});
 
});
 
</source>
 
</source>
 +
 +
====Options====
 +
 +
{{{!}}
 +
{{!}}-
 +
!Option
 +
!Type
 +
!Description
 +
{{!}}-
 +
{{!}}Message
 +
{{!}}String
 +
{{!}}The message you want to send along with the typing notification
 +
{{!}}-
 +
{{!}}}
  
 
====Resolutions====
 
====Resolutions====
Line 534: Line 500:
 
{{!}}-  
 
{{!}}-  
 
{{!}}resolved
 
{{!}}resolved
−
{{!}}When active session is ended successfully
+
{{!}}When AJAX request is successful
 +
{{!}}(AJAX Response Object)
 +
{{!}}-
 +
{{!}}rejected
 +
{{!}}When AJAX exception occurs
 
{{!}}(AJAX Response Object)
 
{{!}}(AJAX Response Object)
 
{{!}}-  
 
{{!}}-  
Line 543: Line 513:
 
{{!}}}  
 
{{!}}}  
  
−
===sendMessage===
+
===sendFilteredMessage===
  
−
Sends a message from the client to the chat session. For use by WebChat widgets only. You must not invoke this manually.
+
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====
 
====Example====
 +
 
<source lang="javascript">
 
<source lang="javascript">
−
oMyPlugin.command('WebChatService.sendMessage', {message: 'hi'}).done(function(e){
+
oMyPlugin.command('WebChatService.sendFilteredMessage', {
 +
 
 +
message: 'filtered message',
 +
regex: /[a-zA-Z]/
 +
 
 +
}).done(function(e){
  
−
// WebChatService sent a message successfully
+
// WebChatService sent filtered message successfully
  
 
}).fail(function(e){
 
}).fail(function(e){
  
−
// WebChatService failed to send a message
+
// WebChatService failed to send filtered message
 
});
 
});
 
</source>
 
</source>
  
 
====Options====
 
====Options====
 +
 
{{{!}}  
 
{{{!}}  
 
{{!}}-  
 
{{!}}-  
Line 568: Line 547:
 
{{!}}message
 
{{!}}message
 
{{!}}string
 
{{!}}string
−
{{!}}The message you want to send
+
{{!}}Message you want to send but don't want to appear in the transcript
 +
{{!}}-
 +
{{!}}regex
 +
{{!}}RegExp
 +
{{!}}Regular expression to match the message
 
{{!}}-  
 
{{!}}-  
 
{{!}}}  
 
{{!}}}  
  
 
====Resolutions====
 
====Resolutions====
−
 
 
{{{!}}  
 
{{{!}}  
 
{{!}}-  
 
{{!}}-  
Line 581: Line 563:
 
{{!}}-  
 
{{!}}-  
 
{{!}}resolved
 
{{!}}resolved
−
{{!}}When message is successfully sent
+
{{!}}When there is an active session
−
{{!}}(AJAX Response Object)
+
{{!}}n/a
−
{{!}}-
 
−
{{!}}rejected
 
−
{{!}}If no message text provided
 
−
{{!}}'No message text provided'
 
 
{{!}}-  
 
{{!}}-  
 
{{!}}rejected
 
{{!}}rejected
 
{{!}}If no chat session is currently active
 
{{!}}If no chat session is currently active
−
{{!}}'There is no active chat session'
+
{{!}}'No active chat session'
−
{{!}}-
 
−
{{!}}rejected
 
−
{{!}}When AJAX exception occurs
 
−
{{!}}(AJAX Response Object)
 
 
{{!}}-  
 
{{!}}-  
 
{{!}}}  
 
{{!}}}  
  
−
===sendCustomNotice===
+
===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
  
−
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  use this out of the box.
+
{{NoteFormat|Filters are now automatically stored and recalled on chat restore for the duration of the session.}}
  
 
====Example====
 
====Example====
  
 
<source lang="javascript">
 
<source lang="javascript">
−
oMyPlugin.command('WebChatService.sendCustomNotice', {message: 'bye'}).done(function(e){
+
oMyPlugin.command('WebChatService.addPrefilter', {filters: /[a-zA-Z]/}).done(function(e){
  
−
// WebChatService sent a custom message successfully
+
// WebChatService added filter successfully
 +
// e == Object of registered prefilters
  
 
}).fail(function(e){
 
}).fail(function(e){
  
−
// WebChatService failed to send a custom message
+
// WebChatService failed to add filter
 
});
 
});
 
</source>
 
</source>
Line 623: Line 600:
 
!Description
 
!Description
 
{{!}}-  
 
{{!}}-  
−
{{!}}message
+
{{!}}filters
−
{{!}}string
+
{{!}}RegExp or Array of RegExp
−
{{!}}A message you want to send along with the custom notice
+
{{!}}Regular Expression(s) to add to the prefilter list
 
{{!}}-  
 
{{!}}-  
 
{{!}}}  
 
{{!}}}  
Line 635: Line 612:
 
!When
 
!When
 
!Returns
 
!Returns
−
!Introduced / Updated
 
 
{{!}}-  
 
{{!}}-  
 
{{!}}resolved
 
{{!}}resolved
−
{{!}}When message is successfully sent
+
{{!}}When valid filters are provided
−
{{!}}(AJAX Response Object)
+
{{!}}Array of all registered prefilters.
−
{{!}}
 
 
{{!}}-  
 
{{!}}-  
 
{{!}}rejected
 
{{!}}rejected
−
{{!}}When AJAX exception occurs
+
{{!}}When invalid or missing filters provided
−
{{!}}(AJAX Response Object)
+
{{!}}'Missing or invalid filters provided. Please provide a regular expression or an array of regular expressions.'
−
{{!}}
 
−
{{!}}-
 
−
{{!}}rejected
 
−
{{!}}When the server doesn't support receiving custom notices
 
−
{{!}}This transport doesn't support sendCustomNotice command.
 
−
{{!}}9.0.008.04
 
 
{{!}}-  
 
{{!}}-  
 
{{!}}}  
 
{{!}}}  
  
−
===sendTyping===
+
===updateUserData===
  
−
Sends a 'customer typing' notification to chat session. A visual indication will be shown to agent. For use by WebChat widgets only. You must not invoke this manually.
+
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====
 
====Example====
  
 
<source lang="javascript">
 
<source lang="javascript">
−
oMyPlugin.command('WebChatService.sendTyping').done(function(e){
+
oMyPlugin.command('WebChatService.updateUserData', {firstname: 'Joe'}).done(function(e){
  
−
// WebChatService sent typing successfully
+
// WebChatService updated user data successfully
  
 
}).fail(function(e){
 
}).fail(function(e){
  
−
// WebChatService failed to send typing
+
// WebChatService failed to update user data
 
});
 
});
 
</source>
 
</source>
Line 679: Line 648:
 
!Description
 
!Description
 
{{!}}-  
 
{{!}}-  
−
{{!}}Message
+
{{!}}n/a
−
{{!}}String
+
{{!}}object
−
{{!}}The message you want to send along with the typing notification
+
{{!}}userData object you want to send to the server for this active session
 
{{!}}-  
 
{{!}}-  
 
{{!}}}  
 
{{!}}}  
Line 692: Line 661:
 
!When
 
!When
 
!Returns
 
!Returns
 +
!Introduced / Updated
 
{{!}}-  
 
{{!}}-  
 
{{!}}resolved
 
{{!}}resolved
−
{{!}}When AJAX request is successful
+
{{!}}Session is active and userData is successfully sent
 
{{!}}(AJAX Response Object)
 
{{!}}(AJAX Response Object)
 +
{{!}}
 
{{!}}-  
 
{{!}}-  
 
{{!}}rejected
 
{{!}}rejected
−
{{!}}When AJAX exception occurs
+
{{!}}Session is active and AJAX exception occurs
 
{{!}}(AJAX Response Object)
 
{{!}}(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
 
{{!}}rejected
−
{{!}}If no chat session is currently active
+
{{!}}Session is active and the server doesn't support updating userData
−
{{!}}'There is no active chat session'
+
{{!}}This transport doesn't support updating userData during an active chat session.
 +
{{!}}9.0.008.04
 
{{!}}-  
 
{{!}}-  
 
{{!}}}  
 
{{!}}}  
  
−
===sendFilteredMessage===
+
===poll===
  
−
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.
+
Internal use only. Starts polling for new messages. For use by WebChat widgets only. You must not invoke this manually.
−
 
 
−
{{NoteFormat|Filters are now automatically stored and recalled on chat restore for the duration of the session.}}
 
  
 
====Example====
 
====Example====
  
 
<source lang="javascript">
 
<source lang="javascript">
−
oMyPlugin.command('WebChatService.sendFilteredMessage', {
+
oMyPlugin.command('WebChatService.poll').done(function(e){
  
−
message: 'filtered message',
+
// WebChatService started polling successfully
−
regex: /[a-zA-Z]/
 
−
 
 
−
}).done(function(e){
 
−
 
 
−
// WebChatService sent filtered message successfully
 
  
 
}).fail(function(e){
 
}).fail(function(e){
  
−
// WebChatService failed to send filtered message
+
// WebChatService failed to start polling
 
});
 
});
 
</source>
 
</source>
  
−
====Options====
+
====Resolutions====
  
 
{{{!}}  
 
{{{!}}  
 
{{!}}-  
 
{{!}}-  
−
!Option
+
!Status
−
!Type
+
!When
−
!Description
+
!Returns
−
{{!}}-
+
!Introduced / Updated
−
{{!}}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
 
{{!}}resolved
 
{{!}}When there is an active session
 
{{!}}When there is an active session
 
{{!}}n/a
 
{{!}}n/a
 +
{{!}}
 +
{{!}}-
 +
{{!}}rejected
 +
{{!}}WebChatService isn't calling this command
 +
{{!}}'Access Denied to private command. Only WebChatService is allowed to invoke this command.'
 +
{{!}}
 
{{!}}-  
 
{{!}}-  
 
{{!}}rejected
 
{{!}}rejected
 
{{!}}If no chat session is currently active
 
{{!}}If no chat session is currently active
−
{{!}}'No active chat session'
+
{{!}}'previous poll has not finished.'
 +
{{!}}
 +
{{!}}-
 +
{{!}}rejected
 +
{{!}}When the server doesn't support polling
 +
{{!}}'This transport doesn't support polling.'
 +
{{!}}9.0.008.04
 
{{!}}-  
 
{{!}}-  
 
{{!}}}  
 
{{!}}}  
  
−
===addPrefilter===
+
===startPoll===
  
−
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
+
Starts automatic polling for new messages. For use by WebChat widgets only. You must not invoke this manually.
−
 
 
−
{{NoteFormat|Filters are now automatically stored and recalled on chat restore for the duration of the session.}}
 
  
 
====Example====
 
====Example====
  
 
<source lang="javascript">
 
<source lang="javascript">
−
oMyPlugin.command('WebChatService.addPrefilter', {filters: /[a-zA-Z]/}).done(function(e){
+
oMyPlugin.command('WebChatService.startPoll').done(function(e){
  
−
// WebChatService added filter successfully
+
// WebChatService started polling successfully
−
// e == Object of registered prefilters
 
  
 
}).fail(function(e){
 
}).fail(function(e){
  
−
// WebChatService failed to add filter
+
// WebChatService failed to start polling
 
});
 
});
 
</source>
 
</source>
  
−
====Options====
+
====Resolutions====
  
 
{{{!}}  
 
{{{!}}  
 
{{!}}-  
 
{{!}}-  
−
!Option
+
!Status
−
!Type
+
!When
−
!Description
+
!Returns
−
{{!}}-
+
!Introduced / Updated
−
{{!}}filters
 
−
{{!}}RegExp or Array of RegExp
 
−
{{!}}Regular Expression(s) to add to the prefilter list
 
−
{{!}}-
 
−
{{!}}}
 
−
 
 
−
====Resolutions====
 
−
{{{!}}
 
−
{{!}}-
 
−
!Status
 
−
!When
 
−
!Returns
 
 
{{!}}-  
 
{{!}}-  
 
{{!}}resolved
 
{{!}}resolved
−
{{!}}When valid filters are provided
+
{{!}}When there is an active session
−
{{!}}Array of all registered prefilters.
+
{{!}}n/a
 +
{{!}}
 
{{!}}-  
 
{{!}}-  
 
{{!}}rejected
 
{{!}}rejected
−
{{!}}When invalid or missing filters provided
+
{{!}}When no chat session is currently active
−
{{!}}'Missing or invalid filters provided. Please provide a regular expression or an array of regular expressions.'
+
{{!}}No active chat session
 +
{{!}}
 
{{!}}-  
 
{{!}}-  
−
{{!}}}  
+
{{!}}rejected
 +
{{!}}When the server doesn't support polling
 +
{{!}}This transport doesn't support polling
 +
{{!}}9.0.008.04
 +
{{!}}-
 +
{{!}}}  
  
−
===updateUserData===
+
===stopPoll===
  
−
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.
+
Stops automatic polling for new messages. For use by WebChat widgets only. You must not invoke this manually.
  
 
====Example====
 
====Example====
  
 
<source lang="javascript">
 
<source lang="javascript">
−
oMyPlugin.command('WebChatService.updateUserData', {firstname: 'Joe'}).done(function(e){
+
oMyPlugin.command('WebChatService.stopPoll').done(function(e){
  
−
// WebChatService updated user data successfully
+
// WebChatService stopped polling successfully
  
 
}).fail(function(e){
 
}).fail(function(e){
  
−
// WebChatService failed to update user data
+
// WebChatService failed to stop polling
 
});
 
});
 
</source>
 
</source>
  
−
====Options====
+
====Resolutions====
  
 
{{{!}}  
 
{{{!}}  
 
{{!}}-  
 
{{!}}-  
−
!Option
+
!Status
−
!Type
+
!When
−
!Description
+
!Returns
 +
!Introduced / Updated
 
{{!}}-  
 
{{!}}-  
 +
{{!}}resolved
 +
{{!}}When there is an active session
 
{{!}}n/a
 
{{!}}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
 
{{!}}rejected
−
{{!}}Session is active and AJAX exception occurs
+
{{!}}If no chat session is currently active
−
{{!}}(AJAX Response Object)
+
{{!}}No active chat session
−
{{!}}
 
−
{{!}}-
 
−
{{!}}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
 
{{!}}rejected
−
{{!}}Session is active and the server doesn't support updating userData
+
{{!}}When the server doesn't support polling
−
{{!}}This transport doesn't support updating userData during an active chat session.
+
{{!}}This transport doesn't support polling
 
{{!}}9.0.008.04
 
{{!}}9.0.008.04
 
{{!}}-  
 
{{!}}-  
 
{{!}}}  
 
{{!}}}  
  
−
===poll===
+
===resetPollExceptions===
  
−
Internal use only. Starts polling for new messages. For use by WebChat widgets only. You must not invoke this manually.
+
Resets the poll exception count to 0. pollExceptionLimit is set in the configuration.
  
 
====Example====
 
====Example====
  
 
<source lang="javascript">
 
<source lang="javascript">
−
oMyPlugin.command('WebChatService.poll').done(function(e){
+
oMyPlugin.command('WebChatService.resetPollExceptions').done(function(e){
  
−
// WebChatService started polling successfully
+
// WebChatService reset polling successfully
  
 
}).fail(function(e){
 
}).fail(function(e){
  
−
// WebChatService failed to start polling
+
// WebChatService failed to reset polling
 
});
 
});
 
</source>
 
</source>
Line 906: Line 846:
 
{{!}}-  
 
{{!}}-  
 
{{!}}resolved
 
{{!}}resolved
−
{{!}}When there is an active session
+
{{!}}Always
 
{{!}}n/a
 
{{!}}n/a
 
{{!}}
 
{{!}}
 
{{!}}-  
 
{{!}}-  
 
{{!}}rejected
 
{{!}}rejected
−
{{!}}WebChatService isn't calling this command
+
{{!}}When the server doesn't support polling
−
{{!}}'Access Denied to private command. Only WebChatService is allowed to invoke this command.'
+
{{!}}This transport doesn't support resetPollExceptions command.
−
{{!}}
+
{{!}}9.0.008.04
 
{{!}}-  
 
{{!}}-  
−
{{!}}rejected
+
{{!}}}  
−
{{!}}If no chat session is currently active
+
 
−
{{!}}'previous poll has not finished.'
+
===restore===
−
{{!}}
 
−
{{!}}-
 
−
{{!}}rejected
 
−
{{!}}When the server doesn't support polling
 
−
{{!}}'This transport doesn't support polling.'
 
−
{{!}}9.0.008.04
 
−
{{!}}-
 
−
{{!}}}
 
  
−
===startPoll===
+
Internal use only. For use by WebChat widgets only. You must not invoke this manually unless you are using Async mode.
−
 
 
−
Starts automatic polling for new messages. For use by WebChat widgets only. You must not invoke this manually.
 
  
 
====Example====
 
====Example====
  
 
<source lang="javascript">
 
<source lang="javascript">
−
oMyPlugin.command('WebChatService.startPoll').done(function(e){
+
oMyPlugin.command('WebChatService.restore').done(function(e){
  
−
// WebChatService started polling successfully
+
// WebChatService restored successfully
  
 
}).fail(function(e){
 
}).fail(function(e){
  
−
// WebChatService failed to start polling
+
// WebChatService failed to restore
 
});
 
});
 
</source>
 
</source>
  
−
====Resolutions====
+
====Options====
  
 
{{{!}}  
 
{{{!}}  
 
{{!}}-  
 
{{!}}-  
−
!Status
+
!Option
−
!When
+
!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 PureEngage v3 API. For more information, see the “PureEngage v3” tab in the “Options” table in {{Link-SomewhereInThisVersion|manual=SDK|topic=WebChatService-combined|anchor=configoptions|display text=WebChatService Configuration}}.
 +
{{!}}(JWT string token)
 +
{{!}}9.0.008.04
 +
{{!}}-
 +
{{!}}}
 +
 
 +
====Resolutions====
 +
 
 +
{{{!}}
 +
{{!}}-
 +
!Status
 +
!When
 
!Returns
 
!Returns
 
!Introduced / Updated
 
!Introduced / Updated
 
{{!}}-  
 
{{!}}-  
 
{{!}}resolved
 
{{!}}resolved
−
{{!}}When there is an active session
+
{{!}}Session has been found.
 
{{!}}n/a
 
{{!}}n/a
 
{{!}}
 
{{!}}
 
{{!}}-  
 
{{!}}-  
 
{{!}}rejected
 
{{!}}rejected
−
{{!}}When no chat session is currently active
+
{{!}}Session cannot be found.
−
{{!}}No active chat session
+
{{!}}n/a
 
{{!}}
 
{{!}}
 
{{!}}-  
 
{{!}}-  
 
{{!}}rejected
 
{{!}}rejected
−
{{!}}When the server doesn't support polling
+
{{!}}Restoring chat session is in progress.
−
{{!}}This transport doesn't support polling
+
{{!}}Already restoring. Ignoring request.
−
{{!}}9.0.008.04
+
{{!}}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
 
{{!}}-  
 
{{!}}-  
 
{{!}}}  
 
{{!}}}  
  
−
===stopPoll===
+
===getTranscript===
 +
 
 +
Fetches an array of all messages in the chat session.
  
−
Stops automatic polling for new messages. For use by WebChat widgets only. You must not invoke this manually.
+
{{NoteFormat|For more information on the fields included in JSON response, see [https://docs.genesys.com/Documentation:GMS:API:APIResponses#Digital_Channels_Chat_V2_Response_Format Digital Channels Chat V2 Response Format].}}
  
 
====Example====
 
====Example====
  
 
<source lang="javascript">
 
<source lang="javascript">
−
oMyPlugin.command('WebChatService.stopPoll').done(function(e){
+
oMyPlugin.command('WebChatService.getTranscript').done(function(e){
  
−
// WebChatService stopped polling successfully
+
// WebChatService got transcript successfully
 +
// e == Object with an array of messages
  
 
}).fail(function(e){
 
}).fail(function(e){
  
−
// WebChatService failed to stop polling
+
// WebChatService failed to get transcript
 
});
 
});
 
</source>
 
</source>
Line 994: Line 955:
 
!When
 
!When
 
!Returns
 
!Returns
−
!Introduced / Updated
 
 
{{!}}-  
 
{{!}}-  
 
{{!}}resolved
 
{{!}}resolved
−
{{!}}When there is an active session
+
{{!}}Always
−
{{!}}n/a
+
{{!}}Object with an array of messages
−
{{!}}
 
−
{{!}}-
 
−
{{!}}rejected
 
−
{{!}}If no chat session is currently active
 
−
{{!}}No active chat session
 
−
{{!}}
 
−
{{!}}-
 
−
{{!}}rejected
 
−
{{!}}When the server doesn't support polling
 
−
{{!}}This transport doesn't support polling
 
−
{{!}}9.0.008.04
 
 
{{!}}-  
 
{{!}}-  
 
{{!}}}  
 
{{!}}}  
  
−
===resetPollExceptions===
+
===getAgents===
  
−
Resets the poll exception count to 0. pollExceptionLimit is set in the configuration.
+
Return a list of agents currently participating in the chat. Includes agent metadata.
  
 
====Example====
 
====Example====
  
 
<source lang="javascript">
 
<source lang="javascript">
−
oMyPlugin.command('WebChatService.resetPollExceptions').done(function(e){
+
oMyPlugin.command('WebChatService.getAgents').done(function(e){
  
−
// WebChatService reset polling successfully
+
// WebChatService got agents successfully
 +
// e == Object with agents information in chat
  
 
}).fail(function(e){
 
}).fail(function(e){
  
−
// WebChatService failed to reset polling
+
// WebChatService failed to get agents
 
});
 
});
 
</source>
 
</source>
Line 1,037: Line 987:
 
!When
 
!When
 
!Returns
 
!Returns
−
!Introduced / Updated
 
 
{{!}}-  
 
{{!}}-  
 
{{!}}resolved
 
{{!}}resolved
 
{{!}}Always
 
{{!}}Always
−
{{!}}n/a
+
{{!}}(Object List) {name: (String), connected: (Boolean), supervisor: (Boolean), connectedTime: (int time),disconnectedTime: (int time)}
−
{{!}}
 
−
{{!}}-
 
−
{{!}}rejected
 
−
{{!}}When the server doesn't support polling
 
−
{{!}}This transport doesn't support resetPollExceptions command.
 
−
{{!}}9.0.008.04
 
 
{{!}}-  
 
{{!}}-  
 
{{!}}}  
 
{{!}}}  
  
−
===restore===
+
===getStats===
  
−
Internal use only. For use by WebChat widgets only. You must not invoke this manually unless you are using Async mode.
+
Returns stats on chat session including start time, end time, duration, and list of agents.
  
 
====Example====
 
====Example====
  
 
<source lang="javascript">
 
<source lang="javascript">
−
oMyPlugin.command('WebChatService.restore').done(function(e){
+
oMyPlugin.command('WebChatService.getStats').done(function(e){
  
−
// WebChatService restored successfully
+
// WebChatService got stats successfully
 +
// e == Object with chat session stats
  
 
}).fail(function(e){
 
}).fail(function(e){
  
−
// WebChatService failed to restore
+
// WebChatService failed to get stats
 
});
 
});
 
</source>
 
</source>
  
−
====Options====
+
====Resolutions====
  
 
{{{!}}  
 
{{{!}}  
 
{{!}}-  
 
{{!}}-  
−
!Option
+
!Status
−
!Type
+
!When
−
!Description
+
!Returns
−
!Accepted Values
 
−
!Introduced / Updated
 
 
{{!}}-  
 
{{!}}-  
−
{{!}}sessionData
+
{{!}}resolved
−
{{!}}string
+
{{!}}Always
−
{{!}}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 PureEngage v3 API. For more information, see the “PureEngage v3” tab in the “Options” table in {{Link-SomewhereInThisVersion|manual=SDK|topic=WebChatService-combined|anchor=configoptions|display text=WebChatService Configuration}}.
+
{{!}}{agents: (Object), startTime: (int time), endTime: (int time), duration: (int time)}
−
{{!}}(JWT string token)
 
−
{{!}}9.0.008.04
 
 
{{!}}-  
 
{{!}}-  
 
{{!}}}  
 
{{!}}}  
  
−
====Resolutions====
+
===sendFile===
 +
 
 +
'''[Introduced: 9.0.008.04]'''
 +
 
 +
Sends the file from the client machine to the agent.
  
−
{{{!}}  
+
{{NoteFormat|This command is not applicable when using Chat via GMS.}}
−
{{!}}-
+
 
−
!Status
+
====Example====
−
!When
+
 
−
!Returns
+
<source lang="javascript">
−
!Introduced / Updated
+
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====
 +
 
 +
{{{!}}
 
{{!}}-  
 
{{!}}-  
−
{{!}}resolved
+
!Option
−
{{!}}Session has been found.
+
!Type
−
{{!}}n/a
+
!Description
−
{{!}}
 
 
{{!}}-  
 
{{!}}-  
−
{{!}}rejected
+
{{!}}files
−
{{!}}Session cannot be found.
+
{{!}}File
−
{{!}}n/a
+
{{!}}A reference to a file input element (for example <input type=“file”/>)
−
{{!}}
 
−
{{!}}-
 
−
{{!}}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===
+
====Resolutions====
  
−
Fetches an array of all messages in the chat session.
+
{{{!}}  
−
 
+
{{!}}-  
−
{{NoteFormat|For more information on the fields included in JSON response, see [https://docs.genesys.com/Documentation:GMS:API:APIResponses#Digital_Channels_Chat_V2_Response_Format Digital Channels Chat V2 Response Format].}}
+
!Status
−
 
 
−
====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
 
!When
 
!Returns
 
!Returns
 
{{!}}-  
 
{{!}}-  
 
{{!}}resolved
 
{{!}}resolved
−
{{!}}Always
+
{{!}}When the file sent is a valid type and size
−
{{!}}Object with an array of messages
+
{{!}}(AJAX Response Object)
 +
{{!}}-
 +
{{!}}rejected
 +
{{!}}When the file sent is an invalid type
 +
{{!}}(AJAX Response Object)
 +
{{!}}-
 +
{{!}}rejected
 +
{{!}}When the number of uploads is exceeded
 +
{{!}}(AJAX Response Object)
 +
{{!}}-
 +
{{!}}rejected
 +
{{!}}When the file size exceeds the limit
 +
{{!}}(AJAX Response Object)
 +
{{!}}-
 +
{{!}}rejected
 +
{{!}}When the file size is too large or an unknown error occurs
 +
{{!}}(AJAX Response Object)
 +
{{!}}-
 +
{{!}}rejected
 +
{{!}}When the server doesn't support file uploads
 +
{{!}}This transport doesn't support file uploads
 
{{!}}-  
 
{{!}}-  
 
{{!}}}  
 
{{!}}}  
  
−
===getAgents===
+
===downloadFile===
  
−
Return a list of agents currently participating in the chat. Includes agent metadata.
+
====Downloads the file to the client machine.  Example====
 +
<source lang="javascript">
 +
oMyPlugin.command('WebChatService.downloadFile', {fileId: '1', fileName: 'myfile.txt'}).done(function(e){
  
−
====Example====
+
// WebChatService sent file successfully
−
 
 
−
<source lang="javascript">
 
−
oMyPlugin.command('WebChatService.getAgents').done(function(e){
 
−
 
 
−
// WebChatService got agents successfully
 
−
// e == Object with agents information in chat
 
  
 
}).fail(function(e){
 
}).fail(function(e){
  
−
// WebChatService failed to get agents
+
// WebChatService failed to send file
 
});
 
});
 
</source>
 
</source>
  
−
====Resolutions====
+
====Options====
 +
{{{!}}
 +
{{!}}-
 +
!Option
 +
!Type
 +
!Description
 +
{{!}}-
 +
{{!}}field
 +
{{!}}string
 +
{{!}}This is the id of the file to be downloaded from the session
 +
{{!}}-
 +
{{!}}}
 +
 
 +
===Resolutions===
  
 
{{{!}}  
 
{{{!}}  
Line 1,181: Line 1,129:
 
!When
 
!When
 
!Returns
 
!Returns
−
{{!}}-  
+
{{!}}-
 
{{!}}resolved
 
{{!}}resolved
−
{{!}}Always
+
{{!}}When the file is downloaded successfully
−
{{!}}(Object List) {name: (String), connected: (Boolean), supervisor: (Boolean), connectedTime: (int time),disconnectedTime: (int time)}
+
{{!}}n/a
 
{{!}}-  
 
{{!}}-  
 
{{!}}}  
 
{{!}}}  
  
−
===getStats===
+
===getSessionData===
 +
 
 +
'''[Introduced: 9.0.002.06]'''
  
−
Returns stats on chat session including start time, end time, duration, and list of agents.
+
Retrieves the active session data at any time.
  
 
====Example====
 
====Example====
  
 
<source lang="javascript">
 
<source lang="javascript">
−
oMyPlugin.command('WebChatService.getStats').done(function(e){
+
oMyPlugin.command('WebChatService.getSessionData')
−
 
 
−
// WebChatService got stats successfully
 
−
// e == Object with chat session stats
 
−
 
 
−
}).fail(function(e){
 
−
 
 
−
// WebChatService failed to get stats
 
−
});
 
 
</source>
 
</source>
  
Line 1,213: Line 1,155:
 
!When
 
!When
 
!Returns
 
!Returns
 +
!Introduced / Updated
 
{{!}}-  
 
{{!}}-  
 
{{!}}resolved
 
{{!}}resolved
−
{{!}}Always
+
{{!}}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=configoptions|display text=WebChatService Configuration.}}
−
{{!}}{agents: (Object), startTime: (int time), endTime: (int time), duration: (int time)}
+
{{!}}{secureKey: (string), sessionID: (number/string), alias: (number/string), userId: (number/string)}
 +
{{!}}
 +
{{!}}-
 +
{{!}}resolved
 +
{{!}}Always, when using Chat via PureEngage v3 API. For more information, see the 'PureEngage v3' tab in the 'Options' table in {{Link-SomewhereInThisVersion|manual=SDK|topic=WebChatService-combined|anchor=configoptions|display text=WebChatService Configuration.}}
 +
{{!}}{participantId: (string), sessionId: {string), token: (string), transportId: (string)}
 +
{{!}}9.0.008.04
 +
{{!}}-
 +
{{!}}rejected
 +
{{!}}Never
 +
{{!}}undefined
 +
{{!}}
 
{{!}}-  
 
{{!}}-  
 
{{!}}}  
 
{{!}}}  
  
−
===sendFile===
+
===fetchHistory===
  
 
'''[Introduced: 9.0.008.04]'''
 
'''[Introduced: 9.0.008.04]'''
  
−
Sends the file from the client machine to the agent.
+
For use with WebChat Widget only. 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.
−
 
 
−
{{NoteFormat|This command is not applicable when using Chat via GMS.}}
 
  
 
====Example====
 
====Example====
  
 
<source lang="javascript">
 
<source lang="javascript">
−
oMyPlugin.command('WebChatService.sendFile', {files: $('<input/>').attr('type', 'file') /* Only works on UI, can not dynamically change */ }).done(function(e){
+
oMyPlugin.command('WebChatService.fetchHistory')
 +
</source>
  
−
// WebChatService sent file successfully
+
====Resolutions====
  
−
}).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
 
!Status
 
!When
 
!When
Line 1,264: Line 1,195:
 
{{!}}-  
 
{{!}}-  
 
{{!}}resolved
 
{{!}}resolved
−
{{!}}When the file sent is a valid type and size
+
{{!}}When old messages are retrieved.
 
{{!}}(AJAX Response Object)
 
{{!}}(AJAX Response Object)
 
{{!}}-  
 
{{!}}-  
 
{{!}}rejected
 
{{!}}rejected
−
{{!}}When the file sent is an invalid type
+
{{!}}When request fails.
 
{{!}}(AJAX Response Object)
 
{{!}}(AJAX Response Object)
 
{{!}}-  
 
{{!}}-  
 
{{!}}rejected
 
{{!}}rejected
−
{{!}}When the number of uploads is exceeded
+
{{!}}When Asynchronous mode is not enabled.
−
{{!}}(AJAX Response Object)
+
{{!}}Fetching history messages applies only to Asynchronous chat
 
{{!}}-  
 
{{!}}-  
 
{{!}}rejected
 
{{!}}rejected
−
{{!}}When the file size exceeds the limit
+
{{!}}When all messages are received
−
{{!}}(AJAX Response Object)
+
{{!}}No more messages to fetch
−
{{!}}-
 
−
{{!}}rejected
 
−
{{!}}When the file size is too large or an unknown error occurs
 
−
{{!}}(AJAX Response Object)
 
−
{{!}}-
 
−
{{!}}rejected
 
−
{{!}}When the server doesn't support file uploads
 
−
{{!}}This transport doesn't support file uploads
 
 
{{!}}-  
 
{{!}}-  
 
{{!}}}  
 
{{!}}}  
  
−
===downloadFile===
+
===registerTypingPreviewInput===
 +
 
 +
Selects an HTML input to watch for key events. Used to trigger startTyping and stopTyping automatically. For use by WebChat widgets only. You must not invoke this manually.
 +
 
 +
====Example====
  
−
==== Downloads the file to the client machine.  Example ====
 
 
<source lang="javascript">
 
<source lang="javascript">
−
oMyPlugin.command('WebChatService.downloadFile', {fileId: '1', fileName: 'myfile.txt'}).done(function(e){
+
oMyPlugin.command('WebChatService.registerTypingPreviewInput', {input: $('input') }).done(function(e){
  
−
// WebChatService sent file successfully
+
// WebChatService registered input area successfully
  
 
}).fail(function(e){
 
}).fail(function(e){
  
−
// WebChatService failed to send file
+
// WebChatService failed to register typing preview
 
});
 
});
 
</source>
 
</source>
  
−
==== Options ====
+
====Options====
 +
 
 
{{{!}}  
 
{{{!}}  
 
{{!}}-  
 
{{!}}-  
Line 1,310: Line 1,237:
 
!Description
 
!Description
 
{{!}}-  
 
{{!}}-  
−
{{!}}field
+
{{!}}input
−
{{!}}string
+
{{!}}HTML Reference
−
{{!}}This is the id of the file to be downloaded from the session
+
{{!}}An HTML reference to a text or textarea input
 
{{!}}-  
 
{{!}}-  
 
{{!}}}  
 
{{!}}}  
  
−
===Resolutions===
+
====Resolutions====
  
 
{{{!}}  
 
{{{!}}  
Line 1,323: Line 1,250:
 
!When
 
!When
 
!Returns
 
!Returns
−
{{!}}-
+
{{!}}-  
 
{{!}}resolved
 
{{!}}resolved
−
{{!}}When the file is downloaded successfully
+
{{!}}When valid HTML input reference is provided
 
{{!}}n/a
 
{{!}}n/a
 +
{{!}}-
 +
{{!}}rejected
 +
{{!}}When 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.'
 
{{!}}-  
 
{{!}}-  
 
{{!}}}  
 
{{!}}}  
  
−
===getSessionData===
+
===registerPreProcessor===
  
−
'''[Introduced: 9.0.002.06]'''
+
Registers a function that receives the message object, allowing you to manipulate the values before it is rendered in the transcript.
−
 
 
−
Retrieves the active session data at any time.
 
  
 
====Example====
 
====Example====
  
−
<source lang="javascript">
+
<nowiki><source lang='javascript'></nowiki>
−
oMyPlugin.command('WebChatService.getSessionData')
+
oMyPlugin.command('WebChatService.registerPreProcessor', {preprocessor: function(message){
−
</source>
+
 
 +
message.text = message.text + ' some preprocessing text';
 +
 
 +
return message;
 +
|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.
  
−
====Resolutions====
+
{{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|anchor=top|display text=Widgets Extensions}} for more information about extending Genesys Widgets.|1}}
  
−
{{{!}}
+
<source lang="javascript">var oMyPlugin = window._genesys.widgets.bus.registerPlugin('MyPlugin');
−
{{!}}-
 
−
!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=configoptions|display text=WebChatService Configuration.}}
 
−
{{!}}{secureKey: (string), sessionID: (number/string), alias: (number/string), userId: (number/string)}
 
−
{{!}}
 
−
{{!}}-
 
−
{{!}}resolved
 
−
{{!}}Always, when using Chat via PureEngage v3 API. For more information, see the 'PureEngage v3' tab in the 'Options' table in {{Link-SomewhereInThisVersion|manual=SDK|topic=WebChatService-combined|anchor=configoptions|display text=WebChatService Configuration.}}
 
−
{{!}}{participantId: (string), sessionId: {string), token: (string), transportId: (string)}
 
−
{{!}}9.0.008.04
 
−
{{!}}-
 
−
{{!}}rejected
 
−
{{!}}Never
 
−
{{!}}undefined
 
−
{{!}}
 
−
{{!}}-
 
−
{{!}}}
 
  
−
===fetchHistory===
+
oMyPlugin.subscribe('WebChatService.ready', function(e){});</source>
  
−
'''[Introduced: 9.0.008.04]'''
+
{{{!}}
−
 
+
{{!}}-
−
For use with WebChat Widget only. 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.
+
!Name
−
 
+
!Description
−
====Example====
+
!Data
−
 
+
!Introduced / Updated
−
<source lang="javascript">
+
{{!}}-
−
oMyPlugin.command('WebChatService.fetchHistory')
+
{{!}}ready
−
</source>
+
{{!}}WebChatService is initialized and ready to accept commands.
−
 
+
{{!}}n/a
−
====Resolutions====
+
{{!}}
−
 
+
{{!}}-
−
{{{!}}  
+
{{!}}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.
−
!Status
+
{{!}}{async: (boolean)}
−
!When
+
{{!}}9.0.002.06
−
!Returns
+
{{!}}-
−
{{!}}-  
+
{{!}}restoreTimeout
−
{{!}}resolved
+
{{!}}Chat session restoration attempted was denied after user navigated away from originating website for longer than the time limit: default 60 seconds.
−
{{!}}When old messages are retrieved.
+
{{!}}n/a
−
{{!}}(AJAX Response Object)
+
{{!}}
−
{{!}}-  
+
{{!}}-
−
{{!}}rejected
+
{{!}}restoreFailed
−
{{!}}When request fails.
+
{{!}}Could not restore chat session after page navigation or refresh.
−
{{!}}(AJAX Response Object)
+
{{!}}n/a
−
{{!}}-  
+
{{!}}
−
{{!}}rejected
+
{{!}}-
−
{{!}}When Asynchronous mode is not enabled.
+
{{!}}restoredOffline
−
{{!}}Fetching history messages applies only to Asynchronous chat
+
{{!}}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
−
{{!}}rejected
+
{{!}}
−
{{!}}When all messages are received
+
{{!}}-
−
{{!}}No more messages to fetch
+
{{!}}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
−
===registerTypingPreviewInput===
+
{{!}}-
−
 
+
{{!}}error
−
Selects an HTML input to watch for key events. Used to trigger startTyping and stopTyping automatically. For use by WebChat widgets only. You must not invoke this manually.
+
{{!}}An error occurred between the client and the server.
−
 
+
{{!}}(AJAX Response)
−
====Example====
+
{{!}}
−
 
+
{{!}}-
−
<source lang="javascript">
+
{{!}}started
−
oMyPlugin.command('WebChatService.registerTypingPreviewInput', {input: $('input') }).done(function(e){
+
{{!}}Chat session has successfully started.
−
 
+
{{!}}(AJAX Response containing session data)
−
// WebChatService registered input area successfully
+
{{!}}
−
 
+
{{!}}-
−
}).fail(function(e){
+
{{!}}ended
−
 
+
{{!}}Chat session has successfully ended.
−
// WebChatService failed to register typing preview
+
{{!}}n/a
−
});
+
{{!}}
−
</source>
+
{{!}}-
−
 
+
{{!}}agentTypingStarted
−
====Options====
+
{{!}}Agents has started typing a new message.
−
 
+
{{!}}(AJAX Response)
−
{{{!}}  
+
{{!}}
−
{{!}}-  
+
{{!}}-
−
!Option
+
{{!}}agentTypingStopped
−
!Type
+
{{!}}Agent has stopped typing.
−
!Description
+
{{!}}(AJAX Response)
−
{{!}}-  
+
{{!}}
−
{{!}}input
+
{{!}}-
−
{{!}}HTML Reference
+
{{!}}pollingStarted
−
{{!}}An HTML reference to a text or textarea input
+
{{!}}Chat server automatic polling has started.
−
{{!}}-
+
{{!}}n/a
−
{{!}}}
+
{{!}}
−
 
+
{{!}}-
−
====Resolutions====
+
{{!}}pollingStopped
−
 
+
{{!}}Chat server automatic polling has stopped.
−
{{{!}}  
+
{{!}}n/a
−
{{!}}-
+
{{!}}
−
!Status
+
{{!}}-
−
!When
+
{{!}}clientConnected
−
!Returns
+
{{!}}Indicates the user has been connected to the chat session.
−
{{!}}-  
+
{{!}}{message: (object), agents: (object), numAgentsConnected: (number)}
−
{{!}}resolved
+
{{!}}
−
{{!}}When valid HTML input reference is provided
+
{{!}}-
−
{{!}}n/a
+
{{!}}clientDisconnected
−
{{!}}-
+
{{!}}Indicates the user has been disconnected form the chat session.
−
{{!}}rejected
+
{{!}}{message: (object), agents: (object), numAgentsConnected: (number)}
−
{{!}}When 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.'
+
{{!}}-
−
{{!}}-
+
{{!}}agentConnected
−
{{!}}}  
+
{{!}}Indicates an agent has connected to the chat.
−
 
+
{{!}}{message: (object), agents: (object), numAgentsConnected: (number)}
−
===registerPreProcessor===
+
{{!}}
−
 
+
{{!}}-
−
Registers a function that receives the message object, allowing you to manipulate the values before it is rendered in the transcript.
+
{{!}}agentDisconnected
−
 
+
{{!}}Indicates an agent has disconnected from the chat.
−
====Example====
+
{{!}}{message: (object), agents: (object), numAgentsConnected: (number)}
−
 
+
{{!}}
−
<nowiki><source lang='javascript'></nowiki>
+
{{!}}-
−
oMyPlugin.command('WebChatService.registerPreProcessor', {preprocessor: function(message){
+
{{!}}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
 +
{{!}}<nowiki>Indicates a bot has connected to the chat.
 +
{{NoteFormat</nowiki>
 +
{{!}}<nowiki>This event is applicable only when using {{Link-SomewhereInThisManual</nowiki>
 +
{{!}}topic=WebChatService-combined
 +
{{!}}anchor=configoptions
 +
{{!}}<nowiki>display text=WebChat with GMS API}}.}}</nowiki>
 +
{{!}}{message: (object), agents: (object), numAgentsConnected: (number)}
 +
{{!}}9.0.014.13
 +
{{!}}-
 +
{{!}}botDisconnected
 +
{{!}}<nowiki>Indicates a bot has disconnected from the chat.
 +
{{NoteFormat</nowiki>
 +
{{!}}<nowiki>This event is applicable only when using {{Link-SomewhereInThisManual</nowiki>
 +
{{!}}topic=WebChatService-combined
 +
{{!}}anchor=configoptions
 +
{{!}}<nowiki>display text=WebChat with GMS API}}.}}</nowiki>
 +
{{!}}{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
 +
{{!}}<nowiki>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.
  
−
message.text = message.text + ' some preprocessing text';
+
{{NoteFormat</nowiki>
 +
{{!}}<nowiki>This event is applicable only when using {{Link-SomewhereInThisManual</nowiki>
 +
{{!}}topic=WebChatService-combined
 +
{{!}}anchor=configoptions
 +
{{!}}<nowiki>display text=WebChat with GMS API}}.}}</nowiki>
 +
{{!}}n/a
 +
{{!}}
 +
{{!}}-
 +
{{!}}chatServerBackOnline
 +
{{!}}<nowiki>Chat server had come back online after going offline. This will only be published after 'chatServerWentOffline'.
 +
 
 +
{{NoteFormat</nowiki>
 +
{{!}}<nowiki>This event is applicable only when using {{Link-SomewhereInThisManual</nowiki>
 +
{{!}}topic=WebChatService-combined
 +
{{!}}anchor=configoptions
 +
{{!}}<nowiki>display text=WebChat with GMS API}}.}}</nowiki>
 +
{{!}}n/a
 +
{{!}}
 +
{{!}}-
 +
{{!}}connectionPending
 +
{{!}}<nowiki>If there is a connection problem and WebChatService is trying to reconnect, this event will be published. Published before 'chatServerWentOffline'.
  
−
return message;
+
{{NoteFormat</nowiki>
 +
{{!}}<nowiki>This event is applicable only when using {{Link-SomewhereInThisManual</nowiki>
 +
{{!}}topic=WebChatService-combined
 +
{{!}}anchor=configoptions
 +
{{!}}<nowiki>display text=WebChat with GMS API}}.}}</nowiki>
 +
{{!}}n/a
 +
{{!}}
 +
{{!}}-
 +
{{!}}connectionRestored
 +
{{!}}Is published when the connection has be reestablished. Publishes at the same time as 'chatServerBackOnline'.
 +
{{!}}n/a
 +
{{!}}
 +
{{!}}-
 +
{{!}}}
 
|Status=No
 
|Status=No
 
}}
 
}}

Revision as of 21:26, April 6, 2020

This topic is part of the manual Widgets API Reference for version Current of Widgets.

Learn how to use Genesys chat services.

Related documentation:

Overview

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 up with each of the following types:

Type Namespace
Configuration webchat
CXBus—API commands & API events WebChatService

Customization

WebChatService has many configuration options but no customization options. It is a plug-and-play plugin and works as is.

Configuration

WebChat and WebChatService share the _genesys.widgets.webchat configuration namespace. WebChat contains the UI options and WebChatService contains the connection options.

Important
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 configuration options.

Example

// When using GMS 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 PureEngage 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
	}
};

Options

<tabber> GMS API=

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 to initiate chat on. 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

Localization

WebChatService doesn't have any localization options.

API Commands

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.

Important
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 Widgets Extensions for more information about extending Genesys Widgets.
var oMyPlugin = window._genesys.widgets.bus.registerPlugin('MyPlugin');

oMyPlugin.command('WebChatService.getAgents');
Important
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 WebChatService Configuration.

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.

startChat

Initiates a new chat session with the chat server via GMS or with the service configured under transport section. For use by WebChat widgets only. You must not invoke this manually.

Example

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
});

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 When server confirms session started (AJAX Response Object)
rejected When a chat session is already active 'There is already an active chat session'
rejected When AJAX exception occurs (AJAX Response Object)
rejected When server exception occurs (AJAX Response Object)
rejected When userData is invalid 'malformed data object provided in userData property'

endChat

Ends the chat session with the chat server via GMS or with the service configured under transport section. For use by WebChat widgets only. You must not invoke this manually.

Example

oMyPlugin.command('WebChatService.endChat').done(function(e){

	// WebChatService ended a chat successfully

}).fail(function(e){

	// WebChatService failed to end chat
});

Resolutions

Status When Returns
resolved When active session is ended successfully (AJAX Response Object)
rejected If no chat session is currently active 'There is no active chat session'

sendMessage

Sends a message from the client to the chat session. For use by WebChat widgets only. You must not invoke this manually.

Example

oMyPlugin.command('WebChatService.sendMessage', {message: 'hi'}).done(function(e){

	// WebChatService sent a message successfully

}).fail(function(e){

	// WebChatService failed to send a message
});

Options

Option Type Description
message string The message you want to send

Resolutions

Status When Returns
resolved When message is successfully sent (AJAX Response Object)
rejected If no message text provided 'No message text provided'
rejected If no chat session is currently active 'There is no active chat session'
rejected When 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 use this out of the box.

Example

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
});

Options

Option Type Description
message string A message you want to send along with the custom notice

Resolutions

Status When Returns Introduced / Updated
resolved When message is successfully sent (AJAX Response Object)
rejected When AJAX exception occurs (AJAX Response Object)
rejected When 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 chat session. A visual indication will be shown to agent. For use by WebChat widgets only. You must not invoke this manually.

Example

oMyPlugin.command('WebChatService.sendTyping').done(function(e){

	// WebChatService sent typing successfully

}).fail(function(e){

	// WebChatService failed to send typing
});

Options

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

Resolutions

Status When Returns
resolved When AJAX request is successful (AJAX Response Object)
rejected When AJAX exception occurs (AJAX Response Object)
rejected If no chat session is currently active 'There is no active chat session'

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.

Important
Filters are now automatically stored and recalled on chat restore for the duration of the session.

Example

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
});

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 When there is an active session n/a
rejected If no chat session is currently active 'No active chat session'

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

Important
Filters are now automatically stored and recalled on chat restore for the duration of the session.

Example

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
});

Options

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

Resolutions

Status When Returns
resolved When valid filters are provided Array of all registered prefilters.
rejected When 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

oMyPlugin.command('WebChatService.updateUserData', {firstname: 'Joe'}).done(function(e){

	// WebChatService updated user data successfully

}).fail(function(e){

	// WebChatService failed to update user data
});

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. For use by WebChat widgets only. You must not invoke this manually.

Example

oMyPlugin.command('WebChatService.poll').done(function(e){

	// WebChatService started polling successfully

}).fail(function(e){

	// WebChatService failed to start polling
});

Resolutions

Status When Returns Introduced / Updated
resolved When 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 If no chat session is currently active 'previous poll has not finished.'
rejected When the server doesn't support polling 'This transport doesn't support polling.' 9.0.008.04

startPoll

Starts automatic polling for new messages. For use by WebChat widgets only. You must not invoke this manually.

Example

oMyPlugin.command('WebChatService.startPoll').done(function(e){

	// WebChatService started polling successfully

}).fail(function(e){

	// WebChatService failed to start polling
});

Resolutions

Status When Returns Introduced / Updated
resolved When there is an active session n/a
rejected When no chat session is currently active No active chat session
rejected When the server doesn't support polling This transport doesn't support polling 9.0.008.04

stopPoll

Stops automatic polling for new messages. For use by WebChat widgets only. You must not invoke this manually.

Example

oMyPlugin.command('WebChatService.stopPoll').done(function(e){

	// WebChatService stopped polling successfully

}).fail(function(e){

	// WebChatService failed to stop polling
});

Resolutions

Status When Returns Introduced / Updated
resolved When there is an active session n/a
rejected If no chat session is currently active No active chat session
rejected When 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

oMyPlugin.command('WebChatService.resetPollExceptions').done(function(e){

	// WebChatService reset polling successfully

}).fail(function(e){

	// WebChatService failed to reset polling
});

Resolutions

Status When Returns Introduced / Updated
resolved Always n/a
rejected When the server doesn't support polling This transport doesn't support resetPollExceptions command. 9.0.008.04

restore

Internal use only. For use by WebChat widgets only. You must not invoke this manually unless you are using Async mode.

Example

oMyPlugin.command('WebChatService.restore').done(function(e){

	// WebChatService restored successfully

}).fail(function(e){

	// WebChatService failed to restore
});

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 PureEngage v3 API. For more information, see the “PureEngage v3” tab in the “Options” table in WebChatService Configuration. (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.

Important
For more information on the fields included in JSON response, see Digital Channels Chat V2 Response Format.

Example

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
});

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

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
});

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

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
});

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.

Important
This command is not applicable when using Chat via GMS.

Example

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
});

Options

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

Resolutions

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

downloadFile

Downloads the file to the client machine. Example

oMyPlugin.command('WebChatService.downloadFile', {fileId: '1', fileName: 'myfile.txt'}).done(function(e){

	// WebChatService sent file successfully

}).fail(function(e){

	// WebChatService failed to send file
});

Options

Option Type Description
field string This is the id of the file to be downloaded from the session

Resolutions

Status When Returns
resolved When the file is downloaded successfully n/a

getSessionData

[Introduced: 9.0.002.06]

Retrieves the active session data at any time.

Example

oMyPlugin.command('WebChatService.getSessionData')

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 WebChatService Configuration. {secureKey: (string), sessionID: (number/string), alias: (number/string), userId: (number/string)}
resolved Always, when using Chat via PureEngage v3 API. For more information, see the 'PureEngage v3' tab in the 'Options' table in WebChatService Configuration. {participantId: (string), sessionId: {string), token: (string), transportId: (string)} 9.0.008.04
rejected Never undefined

fetchHistory

[Introduced: 9.0.008.04]

For use with WebChat Widget only. 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 messageReceived event.

Example

oMyPlugin.command('WebChatService.fetchHistory')

Resolutions

Status When Returns
resolved When old messages are retrieved. (AJAX Response Object)
rejected When request fails. (AJAX Response Object)
rejected When Asynchronous mode is not enabled. Fetching history messages applies only to Asynchronous chat
rejected When 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. For use by WebChat widgets only. You must not invoke this manually.

Example

oMyPlugin.command('WebChatService.registerTypingPreviewInput', {input: $('input') }).done(function(e){

	// WebChatService registered input area successfully

}).fail(function(e){

	// WebChatService failed to register typing preview
});

Options

Option Type Description
input HTML Reference An HTML reference to a text or textarea input

Resolutions

Status When Returns
resolved When valid HTML input reference is provided n/a
rejected When 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

<source lang='javascript'> oMyPlugin.command('WebChatService.registerPreProcessor', {preprocessor: function(message){

message.text = message.text + ' some preprocessing text';

return message;

API Events

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.

Important
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 Widgets Extensions for more information about extending Genesys Widgets.
var oMyPlugin = window._genesys.widgets.bus.registerPlugin('MyPlugin');

oMyPlugin.subscribe('WebChatService.ready', function(e){});
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-SomewhereInThisManual topic=WebChatService-combined anchor=configoptions display text=WebChat with GMS 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-SomewhereInThisManual topic=WebChatService-combined anchor=configoptions display text=WebChat with GMS 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-SomewhereInThisManual topic=WebChatService-combined anchor=configoptions display text=WebChat with GMS 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-SomewhereInThisManual topic=WebChatService-combined anchor=configoptions display text=WebChat with GMS 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-SomewhereInThisManual topic=WebChatService-combined anchor=configoptions display text=WebChat with GMS API}}.}} n/a
connectionRestored Is published when the connection has be reestablished. Publishes at the same time as 'chatServerBackOnline'. n/a

}}).done(function(e){

// WebChatService registered preprocessor function // e == function that was registered

}).fail(function(e){

// WebChatService failed to register function

}); </source>

Options

Option Type Description
preprocessor function The preprocessor function you want to register.

Resolutions

Status When Returns
resolved When a valid preprocessor function is provided and is registered. The registered preprocessor function.
rejected When an invalid preprocessor function is provided. No preprocessor function provided. Type provided was '<DATATYPE>'.
Retrieved from "https://all.docs.genesys.com/WID/Current/SDK/WebChatService-combined (2025-06-19 17:11:22)"
Comments or questions about this documentation? Contact us for support!