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('WebChat.open');

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.

Example

oMyPlugin.command('WebChat.configure', {

	emojis: true,
	actionsMenu: true,
	inviteOnRestoreTimeout: true,
	uploadsEnabled:true,
	confirmCloseEnabled:true,
	chatButton:{

		enabled: false,
		openDelay: 1000,
		template: '<span>Done</span>',
		effect: 'fade',
		effectDuration: 1000,
		hideDuringInvite: true
	},
	proactive:{

		enabled: false,
		idleTime: 1000,
		cancelTimer: 1000
	},
	autoInvite:{

		enabled: true,
		timeToInviteSeconds: 1000,
		inviteTimeoutSeconds: 1000
	}

}).done(function(e){

	// WebChat configured successfully

}).fail(function(e){

	// WebChat wasn't configured properly
});

Customizable Chat Registration Fields

WebChat allows you to customize the registration form shown to users prior to starting a session. The following form inputs are currently supported:

• Text
• Select
• Hidden
• Checkbox
• Textarea

Customization is done through a JSON object structure that defines the layout, input type, label, and attributes for each input. You can set the default registration form definition in the _genesys.widgets.webchat.form configuration option. Alternately, you can pass a new registration form definition through the WebChat.open command:

_genesys.widgets.bus.command(“WebChat.open”, {formJSON: oRegFormDef});

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

Default Example

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

{
	wrapper: "<table></table>",
	inputs: [

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

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

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

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

Using this JSON definition will result in this output

Properties

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

Special Properties

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

HTML Attributes

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

Example

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

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

Note: the default input type is “text”, so type does not need to be defined if you intend to make a text input.

HTML Output

<input type=“text” id=“cx_webchat_form_firstname” name=“firstname” maxlength=“100” placeholder=“Required”></input>

Labels

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

Labels can be defined as static strings or localization queries.

Wrappers

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

Form Wrapper

You can specify the parent wrapper for the overall form in the top-level “wrapper” property. In the example below, we specify this value as “

”. This is the default wrapper for the WebChat form.

{
	wrapper: "<table></table>", /* form wrapper */
	inputs: []
}

Input Wrapper

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

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

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

You aren’t restricted to using a table for your form.You could change the form wrapper to “

” and then change the individual inputs wrappers from a table-row to your own specification. Be aware though that when you move away from the default table wrappers, you are responsible for styling and aligning your layout. Only the default table-row wrapper is supported by default Themes and CSS.

Validation

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

A validation function is defined like this:

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

	validateWhileTyping: true, // default is false

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

		return true; // or false
	}
}

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

Validation Function Arguments

Argument	Type	Description
event	JavaScript event object
form	HTML reference	A jquery reference to the form wrapper element.
input	HTML reference	A jquery reference to the input element being validated.
label	HTML reference	A jquery reference to the label for the input being validated.
$	jquery instance	Widget’s internal jquery instance. Use this to help you write your validation logic, if needed.
CXBus	CXBus instance	Widget’s internal CXBus reference. Use this to call commands on the bus, if needed.
Common	Function Library	Widget’s internal Common library of functions and utilities. Use if needed.

Examples

Please add appropriate examples…

Resolutions

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

open

Opens the WebChat UI.

Example

oMyPlugin.command('WebChat.open', {

	userData: {},
	form: {

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

}).done(function(e){

	// WebChat opened successfully

}).fail(function(e){

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

Options

Option	Type	Description
userData	object	Object containing arbitrary data that gets sent to the server. Overrides userData set in the webchat configuration object.
form	object	Object containing form data to prefill in the chat entry form and optionally auto-submit the form.
form.autoSubmit	boolean	Automatically submit the form. Useful for bypassing the entry form step.
form.firstname	string	Value for the first name entry field.
form.lastname	string	Value for the last name entry field.
form.email	string	Value for the email entry field.
form.subject	string	Value for the subject entry field.

Resolutions

Status	When	Returns
resolved	When WebChat is successfully opened	n/a
rejected	When WebChat is already open	'already opened'

close

Closes the WebChat UI.

Example

oMyPlugin.command('WebChat.close').done(function(e){

	// WebChat closed successfully

}).fail(function(e){

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

Resolutions

Status	When	Returns
resolved	When WebChat is successfully closed	n/a
rejected	When WebChat is already closed	'already closed'

minimize

Minimize or unminimize WebChat UI.

Example

oMyPlugin.command('WebChat.minimize').done(function(e){

	// WebChat minimized successfully

}).fail(function(e){

	// WebChat ignores command
});

Options

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

Resolutions

Status	When	Returns
resolved	Always	n/a
rejected	Never	'Invalid configuration'

endChat

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

Example

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

	// WebChat ended a chat successfully

}).fail(function(e){

	// WebChat has no active chat session
});

Resolutions

Status	When	Returns
resolved	When there is an active chat session to end	n/a
rejected	When there is no active chat session to end	'there is no active chat session to end'

invite

Show an invitation to chat using the Toaster popup element. Text shown in invitation can be edited in the localization file.

Example

oMyPlugin.command('WebChat.invite').done(function(e){

	// WebChat invited successfully

}).fail(function(e){

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

Resolutions

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

reInvite

When an active chat session is unable to restore, this invitation will offer the user to start a new chat. Text shown in invitation can be edited in the localization file.

Example

oMyPlugin.command('WebChat.reInvite').done(function(e){

	// WebChat reinvited successfully

}).fail(function(e){

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

Resolutions

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

injectMessage

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

Example

oMyPlugin.command('WebChat.injectMessage', {

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

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

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

}).done(function(e){

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

}).fail(function(e){

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

Options

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

Resolutions

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

showChatButton

Makes the standalone chat button visible on the screen using either the default template and CSS or customer-defined ones.

Example

oMyPlugin.command('WebChat.showChatButton', {

	openDelay: 1000,
	duration: 1500

}).done(function(e){

	// WebChat shows chat button successfully

}).fail(function(e){

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

Options

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

Resolutions

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

hideChatButton

Hides the standalone chat button.

Example

oMyPlugin.command('WebChat.hideChatButton', {duration: 1500}).done(function(e){

	// WebChat hid chat button successfully

}).fail(function(e){

	// WebChat button is already hidden
});

Options

Option	Type	Description
duration	number	Duration in milliseconds for the show and hide animation.

Resolutions

Status	When	Returns
resolved	When the chat button is currently visible	n/a
rejected	When the chat button is already hidden	'Chat button is already hidden. Ignoring command.'

showOverlay

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

Example

oMyPlugin.command('WebChat.showOverlay', {

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

}).done(function(e){

	// WebChat successfully shows overlay

}).fail(function(e){

	// WebChat isn't open
});

Options

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

Resolutions

Status	When	Returns
resolved	When WebChat is open and the overlay opens.
rejected	When WebChat is not currently open.	WebChat is not currently open. Ignoring command.

hideOverlay

Hides the slide-down overlay.

Example

oMyPlugin.command('WebChat.hideOverlay').done(function(e){

	// WebChat hid overlay successfully

}).fail(function(e){

	// WebChat isn't open
});

Resolutions

Status	When	Returns
resolved	When WebChat is open and the overlay closes.
rejected	When WebChat is not currently open.	WebChat is not currently open. Ignoring command.