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

From Genesys Documentation
Jump to: navigation, search
(Published)
(Published)
 
(8 intermediate revisions by 2 users not shown)
Line 3: Line 3:
 
|DisplayName=CallbackService
 
|DisplayName=CallbackService
 
|TocName=CallbackService
 
|TocName=CallbackService
−
|Platform=PureEngage
+
|Context=Learn how to use CallbackService to schedule a callback with customer service.
 
|ComingSoon=No
 
|ComingSoon=No
−
|Context=Learn how to schedule a callback with customer service.
+
|Platform=GenesysEngage-cloud
 +
|Role=Developer
 
|Section={{Section
 
|Section={{Section
 
|sectionHeading=Overview
 
|sectionHeading=Overview
−
|Standalone=No
 
−
|ComingSoon=No
 
 
|alignment=Vertical
 
|alignment=Vertical
−
|structuredtext=CallbackService exposes high-level API access to Genesys callback services, allowing you to use our {{Link-AnywhereElse|product=WID|version=Current|manual=SDK|topic=Callback-combined}} Widget to schedule a callback with customer service—or to develop your own custom Callback Widget. CallbackService dramatically simplifies integration, improving the reliability, feature set, and compatibility of every widget on the bus.
+
|structuredtext=CallbackService exposes high-level API access to Genesys Callback services, allowing you to use our {{Link-AnywhereElse|product=WID|version=Current|manual=SDK|topic=Callback-combined}} Widget to schedule a callback with customer service—or to develop your own custom Callback Widget. CallbackService dramatically simplifies integration, improving the reliability, feature set, and compatibility of every widget on the bus.
 
===Usage===
 
===Usage===
−
CallbackService and the matching Callback widget work together right out of the box and they share the same configuration object. Using Callback uses CallbackService.
+
Callback Service and the matching Callback widget work together, and they share a configuration object. Using Callback uses CallbackService.
  
−
You can also use CallbackService as a high-level API using bus commands and events to build your own Callback widget.
+
You can also use Callback Service as a high-level API using bus commands and events to build your own Callback widget.
 
===Namespace===
 
===Namespace===
−
The Callback Service plugin has the following namespaces tied up with each of the following types:  
+
The CallbackService plugin has the following namespaces tied to each of the following types:  
 
{{{!}} class="wikitable" style="width: auto;"
 
{{{!}} class="wikitable" style="width: auto;"
 
{{!}}-
 
{{!}}-
Line 24: Line 23:
 
{{!}}-
 
{{!}}-
 
{{!}}{{!}}{{Link-SomewhereInThisVersion|manual=SDK|topic=CallbackService-combined|anchor=config|display text=Configuration}}
 
{{!}}{{!}}{{Link-SomewhereInThisVersion|manual=SDK|topic=CallbackService-combined|anchor=config|display text=Configuration}}
−
{{!}}{{!}}sendmessage
+
{{!}}{{!}}Sendmessage
 
{{!}}-
 
{{!}}-
 
{{!}}{{!}}CXBus—{{Link-SomewhereInThisVersion|manual=SDK|topic=CallbackService-combined|anchor=commands|display text=API commands}} & {{Link-SomewhereInThisVersion|manual=SDK|topic=CallbackService-combined|anchor=events|display text=API events}}
 
{{!}}{{!}}CXBus—{{Link-SomewhereInThisVersion|manual=SDK|topic=CallbackService-combined|anchor=commands|display text=API commands}} & {{Link-SomewhereInThisVersion|manual=SDK|topic=CallbackService-combined|anchor=events|display text=API events}}
Line 32: Line 31:
  
 
===Customization===
 
===Customization===
−
CallbackService does not have customization options. It is a plug-and-play plugin and works as is.
+
CallbackService does not have customization options. It is a Plug and Play plugin and works as is.
−
|advanced=No
 
 
|Status=No
 
|Status=No
 
}}{{Section
 
}}{{Section
 
|sectionHeading=Configuration
 
|sectionHeading=Configuration
 
|anchor=config
 
|anchor=config
−
|Standalone=No
 
−
|ComingSoon=No
 
 
|alignment=Vertical
 
|alignment=Vertical
 
|structuredtext====Description===
 
|structuredtext====Description===
Line 46: Line 42:
 
===Example===
 
===Example===
 
<source lang="javascript">
 
<source lang="javascript">
−
// If using Callback API v1
 
−
 
−
window._genesys.widgets.callback = {
 
−
 
−
apikey: 'n3eNkgXXXXXXXXOXXXXXXXXA',
 
−
dataURL: 'http://host:port/genesys/1/service/callback/samples',
 
−
userData: {},
 
−
countryCodes: true
 
−
};
 
−
 
−
// If using Callback API v3
 
−
 
 
window._genesys.widgets.callback = {
 
window._genesys.widgets.callback = {
  
Line 82: Line 66:
 
{{!}}{{!}}apikey
 
{{!}}{{!}}apikey
 
{{!}}{{!}}string
 
{{!}}{{!}}string
−
{{!}}{{!}}Apigee Proxy secure token. If apiVersion is v3, this holds the x-api-key value.
+
{{!}}{{!}}If apiVersion is v3, this holds the x-api-key value.
 
{{!}}{{!}}n/a
 
{{!}}{{!}}n/a
 
{{!}}{{!}}n/a
 
{{!}}{{!}}n/a
Line 89: Line 73:
 
{{!}}{{!}}dataURL
 
{{!}}{{!}}dataURL
 
{{!}}{{!}}URL String
 
{{!}}{{!}}URL String
−
{{!}}{{!}}URL to the API endpoint for Callback
+
{{!}}{{!}}URL to the API endpoint for Callback.{{NoteFormat|The base URL for your API endpoints is:
 +
 
 +
<nowiki>https://gapi-<region>.genesyscloud.com/engagement/v3</nowiki>
 +
 
 +
You will receive the <region> information from Genesys at the same time that you receive your API key.|}}
 
{{!}}{{!}}n/a
 
{{!}}{{!}}n/a
 
{{!}}{{!}}n/a
 
{{!}}{{!}}n/a
Line 96: Line 84:
 
{{!}}{{!}}apiVersion
 
{{!}}{{!}}apiVersion
 
{{!}}{{!}}string
 
{{!}}{{!}}string
−
{{!}}{{!}}Version of Callback API  
+
{{!}}{{!}}Version of Callback API.{{NoteFormat|This value determines the version of Callback API.|}}
−
 
 
−
'''Note:''' This value determines the version of Callback API in GMS/v3.
 
  
−
{{!}}{{!}}'v1', 'v3'
+
{{!}}{{!}}'v3'
 
{{!}}{{!}}'v1'
 
{{!}}{{!}}'v1'
 
{{!}}{{!}}Yes, if using [https://developer.genesyscloud.com/reference/engagement/Callbacks/index.html#bookCallbackExternal Callback v3] dataURL
 
{{!}}{{!}}Yes, if using [https://developer.genesyscloud.com/reference/engagement/Callbacks/index.html#bookCallbackExternal Callback v3] dataURL
Line 106: Line 92:
 
{{!}}{{!}}serviceName
 
{{!}}{{!}}serviceName
 
{{!}}{{!}}string
 
{{!}}{{!}}string
−
{{!}}{{!}}Service Name of Callback API in v3
+
{{!}}{{!}}Name of the Callback virtual queue.
 
{{!}}{{!}}n/a
 
{{!}}{{!}}n/a
 
{{!}}{{!}}n/a
 
{{!}}{{!}}n/a
Line 113: Line 99:
 
{{!}}{{!}}userData
 
{{!}}{{!}}userData
 
{{!}}{{!}}object
 
{{!}}{{!}}object
−
{{!}}{{!}}Arbitrary attached data to include while scheduling a callback
+
{{!}}{{!}}Arbitrary attached data to include while scheduling a callback.
 
{{!}}{{!}}n/a
 
{{!}}{{!}}n/a
 
{{!}}{{!}}{}
 
{{!}}{{!}}{}
Line 120: Line 106:
 
{{!}}{{!}}ajaxTimeout
 
{{!}}{{!}}ajaxTimeout
 
{{!}}{{!}}number
 
{{!}}{{!}}number
−
{{!}}{{!}}Number of milliseconds to wait before AJAX timeout
+
{{!}}{{!}}Number of milliseconds to wait before AJAX timeout.
 
{{!}}{{!}}n/a
 
{{!}}{{!}}n/a
 
{{!}}{{!}}3000
 
{{!}}{{!}}3000
 
{{!}}{{!}} 
 
{{!}}{{!}} 
 
{{!}}}
 
{{!}}}
−
|advanced=No
 
 
|Status=No
 
|Status=No
 
}}{{Section
 
}}{{Section
 
|sectionHeading=Localization
 
|sectionHeading=Localization
 
|anchor=localize
 
|anchor=localize
−
|Standalone=No
 
−
|ComingSoon=No
 
 
|alignment=Vertical
 
|alignment=Vertical
 
|structuredtext=CallbackService does not have localization options.
 
|structuredtext=CallbackService does not have localization options.
−
|advanced=No
 
 
|Status=No
 
|Status=No
 
}}{{Section
 
}}{{Section
 
|sectionHeading=API Commands
 
|sectionHeading=API Commands
 
|anchor=commands
 
|anchor=commands
−
|Standalone=No
 
−
|ComingSoon=No
 
 
|alignment=Vertical
 
|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.
 
|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}}
+
{{NoteFormat|The global bus object is a debugging tool. When implementing Widgets on your own site, do not use the global bus object to register your custom plugins. Instead, see {{Link-SomewhereInThisVersion|manual=SDK|topic=GWCBusExtensions|display text=Genesys Widgets Extensions}} for more information about extending Genesys Widgets.|1}}
  
−
<source lang='javascript'>var oMyPlugin = window._genesys.widgets.bus.registerPlugin('MyPlugin');
+
<source lang="javascript">var oMyPlugin = window._genesys.widgets.bus.registerPlugin('MyPlugin');
  
 
oMyPlugin.command('CallbackService.schedule', {
 
oMyPlugin.command('CallbackService.schedule', {
Line 161: Line 141:
 
Internal use only. The main App plugin shares configuration settings with widgets using each widget’s configure command. The configure command can only be called at startup. Calling configure again after startup may result in unpredictable behavior.
 
Internal use only. The main App plugin shares configuration settings with widgets using each widget’s configure command. The configure command can only be called at startup. Calling configure again after startup may result in unpredictable behavior.
 
===schedule===
 
===schedule===
−
Schedule a callback service with the GMS callback schedule API.
+
Schedule a callback service with the callback schedule API.
 
====Example====
 
====Example====
−
<source lang='javascript'>
+
<source lang="javascript">
−
// If using Callback API v1
 
−
 
 
−
oMyPlugin.command('CallbackService.schedule', {
 
−
 
 
−
userData: {}
 
−
firstname: 'Bob',
 
−
lastname: 'Jones',
 
−
email: 'b.jones@mail.com',
 
−
subject: 'product questions',
 
−
desiredTime: '2017-03-03T00:24:17.804Z',
 
−
phonenumber: '4151110000'
 
−
 
 
−
});
 
−
 
 
−
// If using Callback API v3
 
−
 
 
 
oMyPlugin.command('CallbackService.schedule', {
 
oMyPlugin.command('CallbackService.schedule', {
  
Line 228: Line 192:
 
{{!}}{{!}}userData
 
{{!}}{{!}}userData
 
{{!}}{{!}}object
 
{{!}}{{!}}object
−
{{!}}{{!}}Arbitrary data that is to be attached with callback schedule. Properties defined here will be merged with default userData set in the configuration object. If Genesys Web Engagement (GWE) is enabled, this userData also includes visitID, globalVisitID and pageID.
+
{{!}}{{!}}Arbitrary data that is to be attached with callback schedule. Properties defined here will be merged with default userData set in the configuration object.
 
{{!}}-
 
{{!}}-
 
{{!}}{{!}}serviceName
 
{{!}}{{!}}serviceName
Line 245: Line 209:
 
{{!}}-
 
{{!}}-
 
{{!}}{{!}}resolved
 
{{!}}{{!}}resolved
−
{{!}}{{!}}When server confirms callback is scheduled
+
{{!}}{{!}}Server confirms callback is scheduled
 
{{!}}{{!}}200 OK AJAX Response - Schedule Callback
 
{{!}}{{!}}200 OK AJAX Response - Schedule Callback
  
−
  For Callback API v3, refer to 'Responses' in [https://developer.genhtcc.com/reference/callback/Callbacks/index.html#bookCallbackExternal Schedule Callback V3]
+
  For Callback API v3, refer to 'Responses' in [https://developer.genesyscloud.com/reference/engagement/Callbacks/index.html#bookCallbackExternal Schedule Callback V3]
 
{{!}}-
 
{{!}}-
 
{{!}}{{!}}rejected
 
{{!}}{{!}}rejected
−
{{!}}{{!}}When selected timeslot is not available
+
{{!}}{{!}}Selected time slot is not available
 
{{!}}{{!}}400 Bad Request AJAX Error Response  
 
{{!}}{{!}}400 Bad Request AJAX Error Response  
  
−
  For Callback API v3, refer to 'Responses' in [https://developer.genhtcc.com/reference/callback/Callbacks/index.html#bookCallbackExternal Schedule Callback V3]
+
  For Callback API v3, refer to 'Responses' in [https://developer.genesyscloud.com/reference/engagement/Callbacks/index.html#bookCallbackExternal Schedule Callback V3]
 
{{!}}-
 
{{!}}-
 
{{!}}{{!}}rejected
 
{{!}}{{!}}rejected
−
{{!}}{{!}}When AJAX exception occurs
+
{{!}}{{!}}AJAX exception occurs
 
{{!}}{{!}}429 Too Many Requests AJAX Error Response
 
{{!}}{{!}}429 Too Many Requests AJAX Error Response
  
−
  For Callback API v3, refer to 'Responses' in [https://developer.genhtcc.com/reference/callback/Callbacks/index.html#bookCallbackExternal Schedule Callback V3]
+
  For Callback API v3, refer to 'Responses' in [https://developer.genesyscloud.com/reference/engagement/Callbacks/index.html#bookCallbackExternal Schedule Callback V3]
 
{{!}}-
 
{{!}}-
 
{{!}}{{!}}rejected
 
{{!}}{{!}}rejected
−
{{!}}{{!}}When server exception occurs
+
{{!}}{{!}}Server exception occurs
 
{{!}}{{!}}500 Internal Server Error Response
 
{{!}}{{!}}500 Internal Server Error Response
  
−
  For Callback API v3, refer to 'Responses' in [https://developer.genhtcc.com/reference/callback/Callbacks/index.html#bookCallbackExternal Schedule Callback V3]
+
  For Callback API v3, refer to 'Responses' in [https://developer.genesyscloud.com/reference/engagement/Callbacks/index.html#bookCallbackExternal Schedule Callback V3]
 
{{!}}-
 
{{!}}-
 
{{!}}{{!}}rejected
 
{{!}}{{!}}rejected
−
{{!}}{{!}}When no form data is found to schedule callback
+
{{!}}{{!}}No form data is found to schedule callback
 
{{!}}{{!}}'No data found to schedule callback'
 
{{!}}{{!}}'No data found to schedule callback'
 
{{!}}}
 
{{!}}}
Line 275: Line 239:
  
 
===availability===
 
===availability===
−
Get the list of available callback time slots using the GMS callback service.
+
Get the list of available callback time slots using the callback service.
 
====Example====
 
====Example====
−
<source lang='javascript'>
+
<source lang="javascript">
−
// If using Callback API v1
 
−
 
 
−
oMyPlugin.command('CallbackService.availability', {
 
−
 
 
−
startDate: '2017-04-03T00:24:17.804Z',
 
−
numberOfDays: '5',
 
−
maxTimeSlots: 20
 
−
 
 
−
}).done(function(e){
 
−
 
 
−
// CallbackService successfully showing availability
 
−
 
 
−
}).fail(function(e){
 
−
 
 
−
// CallbackService failed to show availability
 
−
});
 
−
 
 
−
// If using Callback API v3
 
−
 
 
 
oMyPlugin.command('CallbackService.availability', {
 
oMyPlugin.command('CallbackService.availability', {
  
Line 354: Line 299:
 
{{!}}-
 
{{!}}-
 
{{!}}{{!}}resolved
 
{{!}}{{!}}resolved
−
{{!}}{{!}}When server confirms the list of available callback timeslots
+
{{!}}{{!}}Server confirms the list of available callback time slots
 
{{!}}{{!}}200 OK AJAX Response - Query Callback Availability
 
{{!}}{{!}}200 OK AJAX Response - Query Callback Availability
  
−
  For Callback API v3, refer to 'Responses' in [https://developer.genhtcc.com/reference/callback/Availability/index.html#queryAvailabilityV2 Availability Callback V3]
+
  For Callback API v3, refer to 'Responses' in [https://developer.genesyscloud.com/reference/engagement/Availability/index.html#queryAvailabilityV2 Availability Callback V3]
 
{{!}}-
 
{{!}}-
 
{{!}}{{!}}rejected
 
{{!}}{{!}}rejected
−
{{!}}{{!}}When timeslots are not available for selected period
+
{{!}}{{!}}Time slots are not available for selected period
 
{{!}}{{!}}400 Bad Request AJAX Response
 
{{!}}{{!}}400 Bad Request AJAX Response
  
−
  For Callback API v3, refer to 'Responses' in [https://developer.genhtcc.com/reference/callback/Availability/index.html#queryAvailabilityV2 Availability Callback V3]
+
  For Callback API v3, refer to 'Responses' in [https://developer.genesyscloud.com/reference/engagement/Availability/index.html#queryAvailabilityV2 Availability Callback V3]
 
{{!}}-
 
{{!}}-
 
{{!}}{{!}}rejected
 
{{!}}{{!}}rejected
−
{{!}}{{!}}When AJAX exception occurs
+
{{!}}{{!}}AJAX exception occurs
 
{{!}}{{!}}400 Bad Request AJAX Response
 
{{!}}{{!}}400 Bad Request AJAX Response
  
−
  For Callback API v3, refer to 'Responses' in [https://developer.genhtcc.com/reference/callback/Availability/index.html#queryAvailabilityV2 Availability Callback V3]
+
  For Callback API v3, refer to 'Responses' in [https://developer.genesyscloud.com/reference/engagement/Availability/index.html#queryAvailabilityV2 Availability Callback V3]
 
{{!}}-
 
{{!}}-
 
{{!}}{{!}}rejected
 
{{!}}{{!}}rejected
−
{{!}}{{!}}When server exception occurs
+
{{!}}{{!}}Server exception occurs
 
{{!}}{{!}}500 Internal Server Error Response
 
{{!}}{{!}}500 Internal Server Error Response
  
−
  For Callback API v3, refer to 'Responses' in [https://developer.genhtcc.com/reference/callback/Availability/index.html#queryAvailabilityV2 Availability Callback V3]
+
  For Callback API v3, refer to 'Responses' in [https://developer.genesyscloud.com/reference/engagement/Availability/index.html#queryAvailabilityV2 Availability Callback V3]
 
{{!}}-
 
{{!}}-
 
{{!}}{{!}}rejected
 
{{!}}{{!}}rejected
−
{{!}}{{!}}When no query data is found
+
{{!}}{{!}}No query data is found
 
{{!}}{{!}}'No query parameters passed for callback availability service'
 
{{!}}{{!}}'No query parameters passed for callback availability service'
 
{{!}}}
 
{{!}}}
−
|advanced=No
 
 
|Status=No
 
|Status=No
 
}}{{Section
 
}}{{Section
 
|sectionHeading=API Events
 
|sectionHeading=API Events
 
|anchor=events
 
|anchor=events
−
|Standalone=No
 
−
|ComingSoon=No
 
 
|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=Once you've registered your plugin on the bus, you can subscribe to and listen for published events. Here's how to use the global bus object to register a new plugin on the bus.
  
−
{{NoteFormat|The global bus object is a debugging tool. When implementing Widgets on your own site, do not use the global bus object to register your custom plugins. Instead, see {{Link-SomewhereInThisManual|topic=GWCBusExtensions|anchor=top|display text=Widgets Extensions}} for more information about extending Genesys Widgets.|1}}
+
{{NoteFormat|The global bus object is a debugging tool. When implementing Widgets on your own site, do not use the global bus object to register your custom plugins. Instead, see {{Link-SomewhereInThisVersion|manual=SDK|topic=GWCBusExtensions|display text=Genesys Widgets Extensions}} for more information about extending Genesys Widgets.|1}}
  
−
<source lang='javascript'>var oMyPlugin = window._genesys.widgets.bus.registerPlugin('MyPlugin');
+
<source lang="javascript">var oMyPlugin = window._genesys.widgets.bus.registerPlugin('MyPlugin');
  
 
oMyPlugin.subscribe('CallbackService.ready', function(e){});</source>
 
oMyPlugin.subscribe('CallbackService.ready', function(e){});</source>
Line 409: Line 351:
 
{{!}}{{!}}Callback is scheduled successfully.
 
{{!}}{{!}}Callback is scheduled successfully.
 
{{!}}{{!}}200 OK AJAX Response - Schedule Callback
 
{{!}}{{!}}200 OK AJAX Response - Schedule Callback
−
  For Callback API v3, refer to 'Responses' in [https://developer.genhtcc.com/reference/callback/Callbacks/index.html#bookCallbackExternal Schedule Callback V3]
+
  For Callback API v3, refer to 'Responses' in [https://developer.genesyscloud.com/reference/engagement/Callbacks/index.html#bookCallbackExternal Schedule Callback V3]
 
{{!}}-
 
{{!}}-
 
{{!}}{{!}}scheduleError
 
{{!}}{{!}}scheduleError
 
{{!}}{{!}}An error occurred between the client and the server during a callback schedule.
 
{{!}}{{!}}An error occurred between the client and the server during a callback schedule.
−
{{!}}{{!}}The JSON data returned by GMS Callback server.  
+
{{!}}{{!}}The JSON data returned by Callback server.  
−
  For Callback API v3, refer to 'Responses' in [https://developer.genhtcc.com/reference/callback/Callbacks/index.html#bookCallbackExternal Schedule Callback V3]
+
  For Callback API v3, refer to 'Responses' in [https://developer.genesyscloud.com/reference/engagement/Callbacks/index.html#bookCallbackExternal Schedule Callback V3]
 
{{!}}-
 
{{!}}-
 
{{!}}{{!}}availableSlots
 
{{!}}{{!}}availableSlots
 
{{!}}{{!}}Callback available slots fetched successfully.
 
{{!}}{{!}}Callback available slots fetched successfully.
 
{{!}}{{!}}200 OK AJAX Response - Query Callback Availability
 
{{!}}{{!}}200 OK AJAX Response - Query Callback Availability
−
  For Callback API v3, refer to 'Responses' in [https://developer.genhtcc.com/reference/callback/Availability/index.html#queryAvailabilityV2 Availability Callback V3]
+
  For Callback API v3, refer to 'Responses' in [https://developer.genesyscloud.com/reference/engagement/Availability/index.html#queryAvailabilityV2 Availability Callback V3]
 
{{!}}-
 
{{!}}-
 
{{!}}{{!}}availabilityError
 
{{!}}{{!}}availabilityError
 
{{!}}{{!}}An error occurred between the client and the server while fetching the available timeslots.
 
{{!}}{{!}}An error occurred between the client and the server while fetching the available timeslots.
−
{{!}}{{!}}The JSON data returned by GMS Callback server.  
+
{{!}}{{!}}The JSON data returned by Callback server.  
−
  For Callback API v3, refer to 'Responses' in [https://developer.genhtcc.com/reference/callback/Availability/index.html#queryAvailabilityV2 Availability Callback V3]
+
  For Callback API v3, refer to 'Responses' in [https://developer.genesyscloud.com/reference/engagement/Availability/index.html#queryAvailabilityV2 Availability Callback V3]
 
{{!}}}
 
{{!}}}
−
|advanced=No
 
 
|Status=No
 
|Status=No
 
}}
 
}}
 
}}
 
}}

Latest revision as of 23:20, October 22, 2020

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

Learn how to use CallbackService to schedule a callback with customer service.

Related documentation:

Overview

CallbackService exposes high-level API access to Genesys Callback services, allowing you to use our Callback Widget to schedule a callback with customer service—or to develop your own custom Callback Widget. CallbackService dramatically simplifies integration, improving the reliability, feature set, and compatibility of every widget on the bus.

Usage

Callback Service and the matching Callback widget work together, and they share a configuration object. Using Callback uses CallbackService.

You can also use Callback Service as a high-level API using bus commands and events to build your own Callback widget.

Namespace

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

Type Namespace
Configuration Sendmessage
CXBus—API commands & API events CallbackService


Customization

CallbackService does not have customization options. It is a Plug and Play plugin and works as is.

Configuration

Description

Callback and CallbackService share the _genesys.widgets.callback configuration namespace. Callback contains the UI options and CallbackService contains the connection options.

Example

window._genesys.widgets.callback = {

	apikey: 'n3eNkgXXXXXXXXOXXXXXXXXA',
	apiVersion: 'v3',
	serviceName: 'service',
	dataURL: 'http://host:port/callbacks',
	userData: {},
	countryCodes: true
};

Options

Name Type Description Accepted Values Default Required
apikey string If apiVersion is v3, this holds the x-api-key value. n/a n/a Yes, if using Apigee Proxy
dataURL URL String URL to the API endpoint for Callback.
Important
The base URL for your API endpoints is:

https://gapi-<region>.genesyscloud.com/engagement/v3

You will receive the <region> information from Genesys at the same time that you receive your API key.
 n/a n/a Always
apiVersion string Version of Callback API.
Important
This value determines the version of Callback API.
 'v3' 'v1' Yes, if using Callback v3 dataURL
serviceName string Name of the Callback virtual queue. n/a n/a Yes, if using Callback v3 dataURL
userData object Arbitrary attached data to include while scheduling a callback. n/a {}  
ajaxTimeout number Number of milliseconds to wait before AJAX timeout. n/a 3000  

Localization

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

oMyPlugin.command('CallbackService.schedule', {

	userData: {},
	firstname: 'Bob',
	lastname: 'Jones',
	email: 'b.jones@mail.com',
	subject: 'product questions',
	desiredTime: '2017-04-04T00:24:17.804Z',
	phonenumber: '4151110000'
});

configure

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

schedule

Schedule a callback service with the callback schedule API.

Example

oMyPlugin.command('CallbackService.schedule', {

	userData: {},
	serviceName: 'service' // service name from callback API v3 version,
	firstname: 'Bob',
	lastname: 'Jones',
	email: 'b.jones@mail.com',
	subject: 'product questions',
	desiredTime: '2017-03-03T00:24:17.804Z',
	phonenumber: '4151110000'

});

Options

Option Type Description
firstname string Receive a Call entry Form Data: 'firstname'.
lastname string Receive a Call entry Form Data: 'lastname'.
phonenumber string Receive a Call entry Form Data: 'phonenumber'.
subject string Receive a Call entry Form Data: 'notes'.
email string Receive a Call entry Form Data: 'email'.
desiredtime string The preferred desired time user would like to get the callback scheduled. Time should be in UTC format.
userData object Arbitrary data that is to be attached with callback schedule. Properties defined here will be merged with default userData set in the configuration object.
serviceName string Service Name of Callback API to be passed if the apiVersion is v3.


Resolutions

Status When Returns
resolved Server confirms callback is scheduled 200 OK AJAX Response - Schedule Callback 
For Callback API v3, refer to 'Responses' in Schedule Callback V3
rejected Selected time slot is not available 400 Bad Request AJAX Error Response 
For Callback API v3, refer to 'Responses' in Schedule Callback V3
rejected AJAX exception occurs 429 Too Many Requests AJAX Error Response 
For Callback API v3, refer to 'Responses' in Schedule Callback V3
rejected Server exception occurs 500 Internal Server Error Response 
For Callback API v3, refer to 'Responses' in Schedule Callback V3
rejected No form data is found to schedule callback 'No data found to schedule callback'


availability

Get the list of available callback time slots using the callback service.

Example

oMyPlugin.command('CallbackService.availability', {

	serviceName: 'service' // service name from callback API v3 version,
	startDate: '2017-04-03T00:24:17.804Z',
	numberOfDays: '5',
	maxTimeSlots: 20

}).done(function(e){

	// CallbackService successfully showing availability

}).fail(function(e){

	// CallbackService failed to show availability
});


Options

Option Type Description
startDate string The start date is specified in ISO 8601 format, using UTC as the timezone (yyyy-MM-ddTHH:mm:ss.SSSZ).
endDate string The end date is specified in ISO 8601 format, using UTC as timezone (yyyy-MM-ddTHH:mm:ss.SSSZ). If neither endDate nor numberOfDays is specified, the end date is assumed to be the same as the start date.
numberOfDays string Used as an alternative to the end date. If neither endDate nor numberOfDays is specified, the end date is assumed to be the same as the start date.
maxTimeSlots number The maximum number of time slots to be included in the response.
serviceName string Service Name of Callback API to be passed if the apiVersion is v3.


Resolutions

Status When Returns
resolved Server confirms the list of available callback time slots 200 OK AJAX Response - Query Callback Availability 
For Callback API v3, refer to 'Responses' in Availability Callback V3
rejected Time slots are not available for selected period 400 Bad Request AJAX Response 
For Callback API v3, refer to 'Responses' in Availability Callback V3
rejected AJAX exception occurs 400 Bad Request AJAX Response 
For Callback API v3, refer to 'Responses' in Availability Callback V3
rejected Server exception occurs 500 Internal Server Error Response 
For Callback API v3, refer to 'Responses' in Availability Callback V3
rejected No query data is found 'No query parameters passed for callback availability service'

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

oMyPlugin.subscribe('CallbackService.ready', function(e){});
Name Description Data
ready CallbackService is initialized and ready to accept commands. n/a
scheduled Callback is scheduled successfully. 200 OK AJAX Response - Schedule Callback 
For Callback API v3, refer to 'Responses' in Schedule Callback V3
scheduleError An error occurred between the client and the server during a callback schedule. The JSON data returned by Callback server. 
For Callback API v3, refer to 'Responses' in Schedule Callback V3
availableSlots Callback available slots fetched successfully. 200 OK AJAX Response - Query Callback Availability 
For Callback API v3, refer to 'Responses' in Availability Callback V3
availabilityError An error occurred between the client and the server while fetching the available timeslots. The JSON data returned by Callback server. 
For Callback API v3, refer to 'Responses' in Availability Callback V3
Retrieved from "https://all.docs.genesys.com/WID/Current/SDK/CallbackService-combined (2025-06-20 16:42:58)"
Comments or questions about this documentation? Contact us for support!