API Commands

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.

Important

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 Widgets Extensions for more information about extending Genesys Widgets.

var oMyPlugin = window._genesys.widgets.bus.registerPlugin('MyPlugin');

oMyPlugin.command('WebChatService.startChat');

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

Example

oMyPlugin.command('WebChatService.startChat', {

	userData: {},
	autoSubmit: false,
	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
});

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'.

Resolutions

Status	When	Returns
resolved	When server confirms session started	(AJAX Response Object)
rejected	When an 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.

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

Send a message from the client to the chat session. Intended to be used by WebChat widgets only. Should not be invoked 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

Send a custom notice from the client to the chat server.

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
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.

Example

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

	// WebChatService sent typying successfully

}).fail(function(e){

	// WebChatService failed to send typing
});

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.

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]+/g

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

Add a new regular expression prefilter to the prefilter list. Any messages matched using the prefilters 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]+/g}).done(function(e){

	// WebChatService added filter successfully
	// e.data == Array 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

Update the userData associated with the active 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 JSON you want to send to the server for this active session.

Resolutions

Status	When	Returns
resolved	When userData is successfully sent	(AJAX Response Object)
rejected	When AJAX exception occurs	(AJAX Response Object)

startPoll

Start automatic polling for new messages. Intended to be used by WebChat widgets only. Should not be invoked 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
resolved	When there is an active session	n/a
rejected	If 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.

Example

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

	// WebChatService stopped polling successfully

}).fail(function(e){

	// WebChatService failed to stop polling
});

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.

Example

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

	// WebChatService reset polling successfully

}).fail(function(e){

	// WebChatService failed to reset polling
});

Resolutions

Status	When	Returns
resolved	Always	n/a
rejected	Never	undefined

configure

Configure the widget. See configuration page for WebChatService.

Example

oMyPlugin.command('WebChatService.configure', {

	apikey: '123456',
	endPoint: 'http://localhost:8080/foo/mywebservice',
	dataURL: 'http://localhost:8080/foo/mygms',
	userData: {},
	ajaxTimeout: 10000,

}).done(function(e){

	// WebChatService configured successfully

}).fail(function(e){

	// WebChatService failed to configure
});

Options

Option	Type	Description
apikey	string	Apigee Proxy secure token
endpoint	string	Manually select the endpoint to initiate the chat on
dataURL	URL String	URL of GMS server
userData	object	Arbitrary JSON attached data to include when initiating a chat
ajaxTimeout	number	Number of milliseconds to wait before AJAX timeout

Resolutions

Status	When	Returns
resolved	When configuration options are provided and set	n/a
rejected	When no configuration options are provided	'Invalid configuration'

getTranscript

Fetch an array of all messages in the chat session

Example

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

	// WebChatService got transcript successfully

}).fail(function(e){

	// WebChatService failed to get transcript
});

Resolutions

Status	When	Returns
resolved	Always	(Array)

getAgents

Return a list of agents that have participated in the chat. Includes agent metadata.

Example

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

	// WebChatService got agents successfully
	//e.data == 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

Return 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.data == 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

Sends the file from the client machine to the agent.

Example

oMyPlugin.command('WebChatService.sendFile', {files: $('<input/>').attr('type', 'file')[0] }).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 (e.g. <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)

downLoadFile

Downloads the file to the client machine.

Example

oMyPlugin.command('WebChatService.downLoadFile', {fileId: '1'}).done(function(e){

	// WebChatService sent file successfully

}).fail(function(e){

	// WebChatService failed to send file
});

Options

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

getFileLimits

This optional request can be used before uploading a large file. If size, type, or other constraints are not met, then uploading the file will fail, avoiding network and CPU overhead.

Example

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

	// WebChatService got file limits successfully

}).fail(function(e){

	// WebChatService failed to get file limits
});

Resolutions

Status	When	Returns
resolved		(AJAX Response Object)
rejected		(AJAX Response Object)

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.

Example

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

	// WebChatService registered textarea 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.'