Jump to: navigation, search
(Update with the copy of version: draft)
(Automated save: adding PEC_Migrated template.)
 
(4 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
= API Commands =
 
= API Commands =
__NOTOC__
 
Once you've registered your own plugin on the bus, you can call commands on other registered plugins. Below we'll quickly register a new plugin on the bus using the global bus object.
 
  
{{NoteFormat|The global bus object is a debug tool. When implementing Widgets on your own site, do not use the global bus object to register your custom plugins. Instead, see [[GWCBusExtensions|Widgets Extensions]] for more information about extending Genesys Widgets.|1}}
+
{{Template:PEC_Migrated}}
  
  
<source lang='javascript'>var oMyPlugin = window._genesys.widgets.bus.registerPlugin('MyPlugin');
 
  
oMyPlugin.command('WebChatService.getAgents');</source>
+
{{NoteFormat|Documentation for this software has moved to a new home. Please update links and bookmarks to content hosted at https://all.docs.genesys.com/WID/Current/SDK/WebChatService-combined#API_Commands.}}
 
 
== 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. Intended to be used by WebChat widgets only. Should not be invoked manually.
 
<br /><br />
 
=== Example ===
 
<source lang='javascript'>
 
oMyPlugin.command('WebChatService.startChat', {
 
 
 
userData: {},
 
nickname: 'Jonny',
 
firstname: 'Johnathan',
 
lastname: 'Smith',
 
email: 'jon.smith@mail.com',
 
subject: 'product questions'
 
 
 
}).done(function(e){
 
 
 
// WebChatService started a chat successfully
 
 
 
}).fail(function(e){
 
 
 
// WebChatService failed to start chat
 
});
 
</source>
 
 
 
<br />
 
=== Options ===
 
{|
 
|-
 
! Option
 
! Type
 
! Description
 
|-
 
| 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.
 
|-
 
| 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'.
 
|-
 
|}
 
<br />
 
=== 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 JSON provided in userData property'
 
|-
 
|}
 
== endChat ==
 
Ends the chat session with the chat server via GMS. Intended to be used by WebChat widgets only. Should not be invoked manually.
 
<br /><br />
 
=== Example ===
 
<source lang='javascript'>
 
oMyPlugin.command('WebChatService.endChat').done(function(e){
 
 
 
// WebChatService ended a chat successfully
 
 
 
}).fail(function(e){
 
 
 
// WebChatService failed to end chat
 
});
 
</source>
 
 
 
<br />
 
=== 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 ==
 
Send a message from the client to the chat session. Intended to be used by WebChat widgets only. Should not be invoked manually.
 
<br /><br />
 
=== 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>
 
 
 
<br />
 
=== Options ===
 
{|
 
|-
 
! Option
 
! Type
 
! Description
 
|-
 
| message
 
| string
 
| The message you want to send.
 
|-
 
|}
 
<br />
 
=== 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 ==
 
Send a custom notice from the client to the chat server.
 
<br /><br />
 
=== Example ===
 
<source lang='javascript'>
 
oMyPlugin.command('WebChatService.sendCustomNotice', {message: 'bye'}).done(function(e){
 
 
 
// WebChatService sent a custom message successfully
 
 
 
}).fail(function(e){
 
 
 
// WebChatService failed to send a custom message
 
});
 
</source>
 
 
 
<br />
 
=== Options ===
 
{|
 
|-
 
! Option
 
! Type
 
! Description
 
|-
 
| message
 
| string
 
| A message you want to send along with the custom notice.
 
|-
 
|}
 
<br />
 
=== Resolutions ===
 
{|
 
|-
 
! Status
 
! When
 
! Returns
 
|-
 
| resolved
 
| When message is successfully sent
 
| (AJAX Response Object)
 
|-
 
| rejected
 
| When AJAX exception occurs
 
| (AJAX Response Object)
 
|-
 
|}
 
== sendTyping ==
 
Send 'customer typing' notification to chat session. A visual indication will be shown to agent. Intended to be used by WebChat widgets only. Should not be invoked manually.
 
<br /><br />
 
=== Example ===
 
<source lang='javascript'>
 
oMyPlugin.command('WebChatService.sendTyping').done(function(e){
 
 
 
// WebChatService sent typing successfully
 
 
 
}).fail(function(e){
 
 
 
// WebChatService failed to send typing
 
});
 
</source>
 
 
 
<br />
 
=== 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 ==
 
Send 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.}}
 
<br /><br />
 
=== Example ===
 
<source lang='javascript'>
 
oMyPlugin.command('WebChatService.sendFilteredMessage', {
 
 
 
message: 'filtered message',
 
regex: /[a-zA-Z]/
 
 
 
}).done(function(e){
 
 
 
// WebChatService sent filtered message successfully
 
 
 
}).fail(function(e){
 
 
 
// WebChatService failed to send filtered message
 
});
 
</source>
 
 
 
<br />
 
=== 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
 
|-
 
|}
 
<br />
 
=== 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 ==
 
Add a new regular expression prefilter to the prefilter list. Any messages matched using the prefilters will not be shown in the transcript
 
 
 
{{NoteFormat|Filters are now automatically stored and recalled on chat restore for the duration of the session.}}
 
<br /><br />
 
=== Example ===
 
<source lang='javascript'>
 
oMyPlugin.command('WebChatService.addPrefilter', {filters: /[a-zA-Z]/}).done(function(e){
 
 
 
// WebChatService added filter successfully
 
// e == Object of registered prefilters
 
 
 
}).fail(function(e){
 
 
 
// WebChatService failed to add filter
 
});
 
</source>
 
 
 
<br />
 
=== Options ===
 
{|
 
|-
 
! Option
 
! Type
 
! Description
 
|-
 
| filters
 
| RegExp or Array of RegExp
 
| Regular Expression(s) to add to the prefilter list
 
|-
 
|}
 
<br />
 
=== 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.
 
<br /><br />
 
=== Example ===
 
<source lang='javascript'>
 
oMyPlugin.command('WebChatService.updateUserData', {firstname: 'Joe'}).done(function(e){
 
 
 
// WebChatService updated user data successfully
 
 
 
}).fail(function(e){
 
 
 
// WebChatService failed to update user data
 
});
 
</source>
 
 
 
<br />
 
=== Options ===
 
{|
 
|-
 
! Option
 
! Type
 
! Description
 
|-
 
| n/a
 
| object
 
| userData JSON you want to send to the server for this active session.
 
|-
 
|}
 
<br />
 
=== Resolutions ===
 
{|
 
|-
 
! Status
 
! When
 
! Returns
 
|-
 
| 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
 
|-
 
|}
 
== poll ==
 
Internal use only. Start polling for new messages. Intended to be used by WebChat widgets only. Should not be invoked manually.
 
<br /><br />
 
=== Example ===
 
<source lang='javascript'>
 
oMyPlugin.command('WebChatService.poll').done(function(e){
 
 
 
// WebChatService started polling successfully
 
 
 
}).fail(function(e){
 
 
 
// WebChatService failed to start polling
 
});
 
</source>
 
 
 
<br />
 
=== Resolutions ===
 
{|
 
|-
 
! Status
 
! When
 
! Returns
 
|-
 
| 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'
 
|-
 
|}
 
== startPoll ==
 
Start automatic polling for new messages. Intended to be used by WebChat widgets only. Should not be invoked manually.
 
<br /><br />
 
=== Example ===
 
<source lang='javascript'>
 
oMyPlugin.command('WebChatService.startPoll').done(function(e){
 
 
 
// WebChatService started polling successfully
 
 
 
}).fail(function(e){
 
 
 
// WebChatService failed to start polling
 
});
 
</source>
 
 
 
<br />
 
=== Resolutions ===
 
{|
 
|-
 
! Status
 
! When
 
! Returns
 
|-
 
| resolved
 
| When there is an active session
 
| n/a
 
|-
 
| rejected
 
| When no chat session is currently active
 
| No active chat session.
 
|-
 
|}
 
== stopPoll ==
 
Stop automatic polling for new messages. Intended to be used by WebChat widgets only. Should not be invoked manually.
 
<br /><br />
 
=== Example ===
 
<source lang='javascript'>
 
oMyPlugin.command('WebChatService.stopPoll').done(function(e){
 
 
 
// WebChatService stopped polling successfully
 
 
 
}).fail(function(e){
 
 
 
// WebChatService failed to stop polling
 
});
 
</source>
 
 
 
<br />
 
=== 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.
 
|-
 
|}
 
== resetPollExceptions ==
 
Reset the poll exception count to 0. pollExceptionLimit is set in the configuration.
 
<br /><br />
 
=== Example ===
 
<source lang='javascript'>
 
oMyPlugin.command('WebChatService.resetPollExceptions').done(function(e){
 
 
 
// WebChatService reset polling successfully
 
 
 
}).fail(function(e){
 
 
 
// WebChatService failed to reset polling
 
});
 
</source>
 
 
 
<br />
 
=== Resolutions ===
 
{|
 
|-
 
! Status
 
! When
 
! Returns
 
|-
 
| resolved
 
| Always
 
| n/a
 
|-
 
| rejected
 
| Never
 
| undefined
 
|-
 
|}
 
== restore ==
 
Internal use only. Intended to be used by WebChatService only. Should not be invoked manually.
 
<br /><br />
 
=== Example ===
 
<source lang='javascript'>
 
oMyPlugin.command('WebChatService.restore').done(function(e){
 
 
 
// WebChatService restored successfully
 
 
 
}).fail(function(e){
 
 
 
// WebChatService failed to restore
 
});
 
</source>
 
 
 
<br />
 
=== Resolutions ===
 
{|
 
|-
 
! Status
 
! When
 
! Returns
 
|-
 
| resolved
 
| Session has been found.
 
| n/a
 
|-
 
| rejected
 
| Session can not be found
 
| n/a
 
|-
 
|}
 
== getTranscript ==
 
Fetch an array of all messages in the chat session
 
<br /><br />
 
=== 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>
 
 
 
<br />
 
=== Resolutions ===
 
{|
 
|-
 
! Status
 
! When
 
! Returns
 
|-
 
| resolved
 
| Always
 
| Object with an array of messages
 
|-
 
|}
 
== getAgents ==
 
Return a list of agents that have participated in the chat. Includes agent metadata.
 
<br /><br />
 
=== Example ===
 
<source lang='javascript'>
 
oMyPlugin.command('WebChatService.getAgents').done(function(e){
 
 
 
// WebChatService got agents successfully
 
// e == Object with agents information in chat
 
 
 
}).fail(function(e){
 
 
 
// WebChatService failed to get agents
 
});
 
</source>
 
 
 
<br />
 
=== Resolutions ===
 
{|
 
|-
 
! Status
 
! When
 
! Returns
 
|-
 
| resolved
 
| Always
 
| (Object List) {name: (String), connected: (Boolean), supervisor: (Boolean), connectedTime: (int time),disconnectedTime: (int time)}
 
|-
 
|}
 
== getStats ==
 
Return stats on chat session including start time, end time, duration, and list of agents.
 
<br /><br />
 
=== Example ===
 
<source lang='javascript'>
 
oMyPlugin.command('WebChatService.getStats').done(function(e){
 
 
 
// WebChatService got stats successfully
 
// e == Object with chat session stats
 
 
 
}).fail(function(e){
 
 
 
// WebChatService failed to get stats
 
});
 
</source>
 
 
 
<br />
 
=== Resolutions ===
 
{|
 
|-
 
! Status
 
! When
 
! Returns
 
|-
 
| resolved
 
| Always
 
| {agents: (Object), startTime: (int time), endTime: (int time), duration: (int time)}
 
|-
 
|}
 
== downloadFile ==
 
Downloads the file to the client machine.
 
<br /><br />
 
=== Example ===
 
<source lang='javascript'>
 
oMyPlugin.command('WebChatService.downloadFile', {fileId: '1'}).done(function(e){
 
 
 
// WebChatService sent file successfully
 
 
 
}).fail(function(e){
 
 
 
// WebChatService failed to send file
 
});
 
</source>
 
 
 
<br />
 
=== Options ===
 
{|
 
|-
 
! Option
 
! Type
 
! Description
 
|-
 
| fileId
 
| string
 
| This is the id of the file to be downloaded from the session
 
|-
 
|}
 
<br />
 
== registerTypingPreviewInput ==
 
Select an HTML input to watch for key events. Used to trigger startTyping and stopTyping automatically. Intended to be used by WebChat widgets only. Should not be invoked manually.
 
<br /><br />
 
=== Example ===
 
<source lang='javascript'>
 
oMyPlugin.command('WebChatService.registerTypingPreviewInput', {input: $('input') }).done(function(e){
 
 
 
// WebChatService registered input area successfully
 
 
 
}).fail(function(e){
 
 
 
// WebChatService failed to register typing preview
 
});
 
</source>
 
 
 
<br />
 
=== Options ===
 
{|
 
|-
 
! Option
 
! Type
 
! Description
 
|-
 
| input
 
| HTML Reference
 
| An HTML reference to a text or textarea input
 
|-
 
|}
 
<br />
 
=== 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 ==
 
Allows you to register a function that receives the message JSON, allowing you to manipulate the values before it is rendered in the transcript.
 
<br /><br />
 
=== Example ===
 
<source lang='javascript'>
 
oMyPlugin.command('WebChatService.registerPreProcessor', {preprocessor: function(){}}).done(function(e){
 
 
 
// WebChatService registered preprocessor function
 
// e == function that was registered
 
 
 
}).fail(function(e){
 
 
 
// WebChatService failed to register function
 
 
 
});
 
</source>
 
 
 
<br />
 
=== Options ===
 
{|
 
|-
 
! Option
 
! Type
 
! Description
 
|-
 
| preprocessor
 
| function
 
| The preprocessor function you want to register.
 
|-
 
|}
 
<br />
 
=== 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>'.
 
|-
 
|}
 
  
  
 
[[Category:V:PSAAS:Public]]
 
[[Category:V:PSAAS:Public]]

Latest revision as of 23:27, June 21, 2020

API Commands

Important
This content may not be the latest Genesys Engage cloud content. To find the latest content, go to Genesys Engage cloud for Administrators.



Important
Documentation for this software has moved to a new home. Please update links and bookmarks to content hosted at https://all.docs.genesys.com/WID/Current/SDK/WebChatService-combined#API_Commands.
This page was last edited on June 21, 2020, at 23:27.
Comments or questions about this documentation? Contact us for support!