10CTI Media Toolbar APIs

This chapter contains the following:

Overview of the Media Toolbar API

Media toolbar APIs are a set of JavaScript functions delivered by Oracle to enable Computer Telephony Integration (CTI) partners to integrate their media toolbars with Oracle Engagement Cloud. These APIs facilitate communication between the media toolbar and Oracle Engagement Cloud to exchange the following in response to inbound or outbound interaction requests:

  • Configuration information

  • Events

  • Payload data

When enabled, Oracle Engagement Cloud loads the toolbar and the media toolbar APIs in an iFrame within the browser.

How You Load the Media Toolbar API

Find toolbar API modules under the svcMca.tlb.api namespace to enable quick and clear identification, and to avoid conflicts with similar JavaScript functions. To load the API JavaScript file, concatenate the following two parameters to the iFrame source toolbar URL:

  • oraParentFrame: Represents the origin of Oracle Engagement Cloud, including the protocol and the port. For example, https://mypodinstance.oraclecloud.com:12345.

  • oraApiSource: Represents the path from where the toolbar API JavaScript file can be loaded, including the leading slash. For example, /service/js/mcaInteractionV1.js.

  • oraTbStyle: Indicates whether the toolbar is displayed on a Live Window. oraTbStyle=LiveWindow indicates the Toolbar is Displayed in the Live Window, otherwise the value is set to Embedded to indicate the display is on the Applications page.

Media Toolbar API Methods

Media toolbar APIs are divided into these methods:

  • Configuration methods: Enable the toolbar and Engagement Cloud to exchange configuration information, and saves changes in Engagement Cloud for retrieval by the toolbar when needed.

  • Interaction methods: Provide notification on the events occurring on the toolbar, as well as exchange information used by the toolbar or engagement Cloud.

  • Toolbar windows management methods: Manage the toolbar windows and facilitate communication between windows.

  • Event listeners: Allow the toolbar to register listeners for events triggered by Engagement Cloud.

The APIs provide a non-blocking interaction between the toolbar and Engagement Cloud. Each method has a callback function parameter that's invoked when a method on Engagement Cloud is complete, notifying the toolbar of the outcome.

Media Toolbar APIs

Use the media toolbar APIs with all toolbars that handle communication between agents and customers. The toolbar loads the APIs which are implemented in a JavaScript file format.

Note: Although media toolbar APIs are generic to all media channels, the 11.13.0.0 release supports only Phone and integration with CTI partner systems.

API Classification

The media toolbar APIs facilitate the initial configuration of the loaded toolbar. Use them to set up functionality for both the partner toolbar and Oracle Engagement Cloud. There are three main flows of the toolbar interaction:

  • Initial configuration of the partner toolbar and communication with Oracle Engagement Cloud.

  • Inbound communication handling.

  • Outbound communication handling.

The APIs are independent of communication channels, but use channel information as a parameter, passing it to Engagement Cloud to determine whether a toolbar supports multiple channels. You define and configure the channels using Functional Setup Manager. The APIs support both preconfigured and user-defined channels.

Data Flow Methods

The following figures show the flow of the methods that are called by the toolbar. The method calls can be mandatory or optional. If a call is mandatory, the toolbar implementation must make one call for each communication event, unless you specify otherwise. If a call is optional, the toolbar implementation can make a call whenever necessary, depending on the action needs.

The following figure shows the configuration workflow.

Graphic illustrating the configuration workflow.

This figure shows the inbound call workflow.

Graphic illustrating the inbound workflow.

This figure shows the outbound call workflow.

Graphic illustrating the outbound call workflow.

And this figure shows the end of call workflow.

Graphic illustrating the end of call workflow

Configuration APIs

Overview of Configuration APIs

The configuration APIs enable the toolbar and Engagement Cloud to exchange configuration data. They're listed in the following table.

Method Usage

getConfiguration

Sets up the toolbar. The method retrieves a list of features that are supported by Oracle Engagement Cloud.

disableFeature

Disables a feature that the toolbar doesn't support.

readyForOperation

Notifies Oracle Engagement Cloud that the toolbar is ready for use, and that the agent is logged on to the toolbar, and ready to handle communication.

getConfiguration Method

Call this mandatory method to get configuration information that enables the toolbar to evaluate the features supported by Engagement Cloud. Based on the evaluation, the toolbar informs Engagement Cloud of any features that must be disabled. For more information, see the disableFeature API method. The returned configuration information also contains details about the initial toolbar dimensions, status, tokens, pages, and the lookup objects for the rule sets used in configuration.

Here's a list of the getConfiguration method parameters:

Parameter Description

callback

Returns results to the caller toolbar, and retrieves configuration information in the form of a JSON formatted string.

configtype

The type of configuration information returned by Engagement Cloud. Possible values are TOOLBAR, TOKENS, PAGES, LOOKUP_OBJECTS, ALL, or FA_TOKEN. This is an optional parameter with a default value of TOOLBAR.

The return value is based on what the configType parameter passes. It includes the agent name along with the other information listed in the following table:

Parameter Description

TOOLBAR

Returns a list of features supported by Engagement Cloud. It also returns information about the toolbar, such as whether it's enabled, and if so, its dimensions. These values are preconfigured, but you can set up and modify them using Functional Setup Manager.

TOKENS

Returns information about both system and user-defined tokens. You can set up and modify these values using Functional Setup Manager.

PAGES

Returns information about both system and user-defined screen pop pages, including code, name, parameters, and associated tokens. You can set up and modify these values using Functional Setup Manager.

LOOKUP_OBJECTS

Returns information about business objects that are used to perform reverse lookup. Returns information about both system and user-defined screen pop pages, including code, name, parameters, and associated tokens. You can set up and modify these values using Functional Setup Manager.

ALL

Returns all of information as the other configType values, except that of FA_TOKEN type.

FA_TOKEN

Returns a JWT token to be used by toolbar implementation to authenticate against Engagement Cloud when calling the REST APIs. A specific call to this configType is required to obtain the JWT token.

Here's sample code to call the getConfiguration method

<html>
<head>
<script type="text/javascript" src="http://domain:port/ora_support/js/mcaInteractionV1.js"> 
</script>
<script type="text/javascript">
function callGetConfiguration() {
      svcMca.tlb.api.getConfiguration(function (response) {
        if (response.result == 'success') {
          alert('Success! Configuration is: ' + response.configuration);
        } else {
          alert('Operation finished with error: ' + response.error);
        }
});
    }</script>
</head>
<body>
<input type="button" value="Configuration" onclick="callGetConfiguration()"/>
</body>
</html>

Here's a sample response for configuration data with configType LOOKUP_OBJECTS

{
  "lookupObjects":[
    {"name":"ServiceRequest"},
    {"name":"Account"},
    {"name":"Contact"}
  ]
}

Here's a sample response for configuration data with configType FA_TOKEN

{
  " faTrustToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsIng1dCI6Im9ZcTdYODhqNXZwYWd3R2t2UGpMWjgxcloxdyJ9eyJleHAiOjE0MDg1NDAxMDIyNjEsImlzcyI6Ind3dy5vcmFjbGUuY29tIiwicHJuIjoiQ1VTVF9TRVJWSUNFX01HUiIsImlhdCI6MTQwODUyNTcwMjI2MX0TkJRAeQbF3xqG0IFZ0oy44aOJKMCpJ0CTxj5Iq19YKe6BAziydxlKTN8lwyr3YbcITqju-fU-i8vFx_XXx9E3iI9l5L_VDlVkXh96CLQPRYa5kW-ruLYeDOhhQL4M7ke8vPMArEp5rPoEOhJXnXYKKTJpCmE5RqJ_Zx00nPxJTY"
}

disableFeature Method

This method informs Engagement Cloud that a subset of available functionality must be disabled because the toolbar hasn't implemented it. By default, the features sent by the getConfiguration API method are considered enabled. There's no return value with this method. The method parameters are described in the following table.

Parameter Description

features

A string that contains the comma-separated feature names. For a list of features, see API Features: Explained.

callback

A method callback which returns results to the toolbar.

Here's sample code used to call the method:

<html>
<head>
<script type="text/javascript" src="http://domain:port/ora_support/js/mcaInteractionV1.js"> 
</script>
<script type="text/javascript">
 function disableOutgoingCall() {
      svcMca.tlb.api.disableFeature('OUTBOUND_CALL', function (response) {
        if (response.result == 'success') {
          alert('Success! Feature disabled!');
        } else {
          alert('Operation finished with error: ' + response.error);
        }
      });
    }</script>
</head>
<body>
<input ="button" value="Disable outgoing call" onclick="disableOutgoingCall()"/>
</body>
</html>

readyForOperation Method

This method notifies Engagement Cloud that the toolbar is ready for operation. A minimum of one call to this method is mandatory. The toolbar is disabled by default, and is enabled when this method is called with the readiness parameter set to TRUE. There's no return value with this method. The following table has all the other relevant details.

Parameter Description

readiness

Boolean value that specifies whether the toolbar is ready to operate.

callback

Callback which informs the toolbar that Engagement Cloud has received the readiness status message.

Here's sample code to call the readyForOperation method

<html>
<head>
<script type="text/javascript" src="http://domain:port/ora_support/js/mcaInteractionV1.js"> 
</script>
<script type="text/javascript">
  function setReady() {
      svcMca.tlb.api.readyForOperation(true, function (response) {
        if (response.result == 'success') {
          alert('Success!');
        } else {
          alert('Operation finished with error: ' + response.error);
        }
      });
    }</script>
</head>
<body>
<input type="button" value="Get state" onclick="getDisplayState()"/>
</body>
</html>

Interaction APIs

Overview of Interaction APIs

Interaction API facilitate communication between the toolbar and Oracle Engagement Cloud during an interaction. The API triggers customer identification by using reverse lookup, screen pop and user-defined tokens. All methods of the interaction API have a channel for which they make the call as a parameter. You configure the channels with Functional Setup Manager. For a list of provided channel names, see Channel Type Data. The following table lists the Interaction API methods.

Method Usage

newCommEvent

Notifies the application that the toolbar has received a new CommEvent. This means that new communication has been assigned to or was initiated by the current agent. This call is mandatory.

startCommEvent

Notifies the application that the toolbar has started a CommEvent, where an agent has accepted the event.

closeCommEvent

Notifies the application that the toolbar has closed the CommEvent. This means that the agent has rejected or ended the event. This call is mandatory.

invokeScreenPop

Sends request to the application to do a specific screen pop irrespective of the configured rules.

getCustomerData

Retrieves customer or related data.

upgradeCommEvent

Notifies Engagement Cloud that a new channel was added to an existing engagement. For instance, an agent is chatting with a customer and decides to start a video conference with the customer.

downgradeCommEvent

Notifies Engagement Cloud that a channel was removed from an existing engagement. For instance, an agent chatting and video conferencing with a customer disconnects the video conference. Note that if a closeCommEvent is received for the initial or primary channel of communication it's assumed that any attached communications are disconnected as well.

newCommEvent Method

This method is called by the toolbar to inform Engagement Cloud that a new communication event has been received. This is the first API call that the toolbar makes during for a communication event. This method must provide through the eventId parameter, either a unique identifier or the media event identifier to be used for the communication event. The primary purpose of the call is to identify customers by using reverse lookup functionality. The toolbar uses tokens to pass all the information from the Interactive Voice Response systems. All customer information retrieved is sent back to the toolbar using system tokens. This method call is mandatory.

Here's a list of the newCommEvent parameters.

Parameter Description

channel

Name of the channel for which the method is called. For more information on what channels are available, see Channel Type Data.

appClassification

Name of the application classification defined for the current toolbar. If this parameter is passed as null, it's assumed that there's no application classification. For a list of preconfigured values, see Application Classification Code.

eventId

A toolbar-generated media event identifier. The same parameter value must be used for all method invocations for a communication. This parameter is stored with the internal interaction record.

inData

An object containing information about incoming events for customer identifiable data, along with attributes containing the names of system or user-defined defined tokens.

To specify a timeout value for an incoming call notification, add the following pair to this parameter:SVCMCA_OFFER_TIMEOUT_SEC, #OFSECOND

Replace the #OFSECONDS value with the actual number of seconds where you want to start the timer. When the timer expires the onDataUpdated() method is invoked with the updateType parameter set to OFFER_TIMEOUT. The toolbar then invokes the closeCommEvent() method to end the interaction.

callback

Returns results to the caller toolbar.

lookupObject

A business object used to run the reverse lookup. Use this optional parameter to get customer information. The default value of Contact. For more information about the list of system lookup objects, see System Business Objects.

channelType

The type of channel for which the method is being called. Note that if, for example, the channel is PHONE but the channelType isn't provided, the default value is set to ORA_SVC_PHONE. For more information, see Channel Type Data.

Here's a list of member attributes of the response object. The object has no return value.

Member Attribute Description

result

The server side running status. Result values are success or error.

outData

Represents an object containing possible identified data from Engagement Cloud for the contact or for the organization. This attribute contains the names of system tokens.

error

Contains error message if the result value is an error. If not, then the value is undefined. For more information about error message codes, see Error Messages: Explained.

Note: The newCommEvent method triggers the creation of an interaction object. This object contains information related to communication, and objects that are related to communication. The identifier for the interaction is passed back with the callback response as the value for the SVCMCA_INTERACTION_ID token. Subsequent invocations of the method must send this token and its value, along with other IVR data to Engagement Cloud.

When the newCommEvent method is invoked for a transfer, the toolbar uses the SVCMCA_PARENT_INTERACTION_ID token to send IVR data and the originating communication interaction ID to Engagement Cloud which associates the communication events. In addition, you must also specify the SVCMCA_2NDARY_CALL_TYPE token to indicate whether this call is a Transfer, a Consultation, or a Conference.

Here's an example of code used to call this method.

<html>
<head>
<script type="text/javascript" src="http://domain:port/ora_support/js/mcaInteractionV1.js"> 
</script>
<script type="text/javascript">
function inboundCallNotification() {
      var inData = {};
      inData.SVCMCA_ANI = '5551234';
      inData.SVCMCA_CONTACT_ID = '1234567890';
      svcMca.tlb.api.newCommEvent('PHONE', 'ORA_SERVICE', '12345-1234-67890', inData, null, function (response) {
        if (response.result == 'success') {
          console.log('Customer: '+response.outData.SVCMCA_CONTACT_NAME +' ('+response.outData.SVCMCA_CONTACT_ID +')');
          console.log('Account: '+response.outData.SVCMCA_ORG_NAME +' ('+response.outData.SVCMCA_ORG_ID +')');
          alert('Success! Results available in log.');
        } else {
          alert('Operation finished with error: ' + response.error);
        }
      },'ORA_SVC_PHONE');
    }</script>
</head>
<body>
<input type="button" value="Get customer data" onclick="inboundCallNotification()"/>
</body>
</html>

startCommEvent Method

The toolbar makes this mandatory method call when an agent accepts a new communication that was triggered by the newCommEvent() call.

This method invokes the Identify Contact flow, then triggers the Customer Validation flow, and then runs the screen pop which the following explains:

  1. The method first triggers the Customer Validation flow.

    This flow queries the communication data to determine if a contact has already been identified. If not, the Contact Search window is displayed allowing the agent to search for or create a contact. Once found, the contact information is returned to the toolbar. Toolbars can bypass this flow by identifying the contact prior to the startCommEvent call or by passing the SVCMCA_BYPASS_IDENTIFY_CONTACT. Toolbars can then use the getCustomerData() method to manually request contact identification.

  2. The method then triggers the Customer Verification flow, an optional flow that opens the customer verification page. If the agent doesn't verify the caller, no screen pop is performed. Customer verification can be bypassed by passing in the SVCMCA_BYPASS_CUSTOMER_VERIFICATION token in the call data.

  3. Finally, the method runs a screen pop using your predefined rules. If you want the toolbar to prevent the screen pop, you can add the SVCMCA_BYPASS_AUTO_SCREENPOP token into the call data, and use the invokeScreenPop() method to manually trigger the pop.

Note: A callback passed with the startCommEvent method can be invoked multiple times if the Identify Contact and Customer Verification flows triggered. The outData information from the response can contain updated customer information.

Here's the method details:

Parameter Description

channel

The name of the channel for which the method is called. For more information on what channels are available, see Channel Type Data.

appClassification

The name of the application classification defined for the current toolbar. If this parameter is passed as null, it's assumed that there is no application classification. For a list of preconfigured values, see Application Classification Code.

eventId

The toolbar generated media event identifier. The same parameter value must be used for all method invocations for a communication. This parameter is stored with internal interaction record.

inData

An object containing information about incoming events for customer identifiable data, as well as attributes containing the names of system or user-defined defined tokens.

callback

Returns results to the caller toolbar.

channelType

The type of channel for which the method is being called. Note that if, for example, the channel is PHONE but the channelType isn't provided, the default value is set to ORA_SVC_PHONE. For more information, see Channel Type Data.

Here's the member attributes of the response object. The object has no return value.

Member Attribute Description

result

The server side running status. Result values are success or error.

outData

Represents an object containing possible identified data from Engagement Cloud for the contact or for the organization. This attribute contains the names of system tokens.

error

Contains the error message if the result value is an error. If not, then the value is undefined. For more information about error message codes, see Error Messages.

<html>
<head>
<script type="text/javascript" src="http://domain:port/ora_support/js/mcaInteractionV1.js"> 
</script>
<script type="text/javascript">
function startCommEvent() {
      var inData = {};
      inData.SVCMCA_ANI = '5551234';
      inData.SVCMCA_CONTACT_ID = '1234567890';
      inData.SVCMCA_CONTACT_NAME = 'John Smith';
      inData.createSr = 'yes';
      svcMca.tlb.api.startCommEvent('PHONE', 'ORA_SERVICE', '12345-1234-67890', inData, function (response) {
        if (response.result == 'success') {
          console.log('Created service request: '+response.SVCMCA_SR_NUMBER);
          alert('Success! Results available in log.');
        } else {
          alert('Operation finished with error: ' + response.error);
        }
      },'ORA_SVC_PHONE');
    }</script>
</head>
<body>
<input type="button" value="Call started" onclick="startCommEvent()"/>
</body>
</html>

closeCommEvent

The toolbar calls this method when a communication is rejected, disconnected, ends normally, or enters wrap-up mode. This method call is mandatory when a communication request is accepted and the startCommEvent method is triggered. The method is called with the following reason values:

  • REJECT: When an agent rejects a communication.

  • WRAPUP: Displays the Wrap Up window to indicate to the agent that the communication must come to a close.

  • ENDCOMMUNICATION: Indicates that the communication ended and if Engagement Cloud is in wrap-up mode it then must close the wrap-up page.

Here's the parameters for this method:

Parameter Description

channel

The name of the channel for which the method is called. For more information on what channels are available, see Channel Type Data.

appClassification

The name of the application classification defined for the current toolbar. If this parameter is passed as null, it's assumed that there is no application classification. For a list of preconfigured values, see Application Classification Code.

eventId

Toolbar generated media event identifier. The same parameter value must be used for all method invocations for a communication. This parameter is stored with internal interaction record.

inData

An object containing information about incoming events for customer identifiable data, along with attributes containing the names of system or user-defined defined tokens.

reason

REJECT, WRAPUP, or ENDCOMMUNICATION.

callback

Returns results to the caller toolbar.

channelType

The type of channel for which the method is being called. Note that if, for example, the channel is PHONE but the channelType isn't provided, the default value is set to ORA_SVC_PHONE. For more information, see Channel Type Data.

Here's the member attributes of the response object. The object has no return value.

Member Attribute Description

result

The server side running status. Result values are success or error.

outData

Represents an object containing possible identified data from Engagement Cloud for the contact or for the organization. This attribute contains the names of system tokens.

error

Contains the error message if the result value is an error. If not, then the value is undefined. For more information about error message codes, see Error Messages.

Here's sample code for this method:

<html>
<head>
<script type="text/javascript" src="http://domain:port/ora_support/js/mcaInteractionV1.js"> 
</script>
<script type="text/javascript">
function closeCommEvent() {
      var inData = {};
      inData.SVCMCA_ANI = '5551234';
      inData.SVCMCA_CONTACT_ID = '1234567890';
      inData.SVCMCA_CONTACT_NAME = 'John Smith';
      svcMca.tlb.api.closeCommEvent('PHONE', 'ORA_SERVICE', '12345-1234-67890', inData, 'WRAPUP', function (response) {
        if (response.result == 'success') {
          alert('Success! Call ended.');
        } else {
          alert('Operation finished with error: ' + response.error);
        }
      },'ORA_SVC_PHONE');
    }</script>
</head>
<body>
<input type="button" value="End call" onclick="closeCommEvent()"/>
</body>
</html>

transferCommEvent Method

This method is called by the toolbar to inform Engagement Cloud that a transfer of the communication has been initiated. Engagement Cloud records the notification, but provides no response. After a call is made to this method, the toolbar calls the closeCommEvent() method with the reason code of TRANSFERRED.

Here's the parameters for this method:

Parameter Description

channel

The name of the channel for which the method is called.

appClassification

The name of the application classification defined for the current toolbar. If this parameter is passed as null, it's assumed that there is no application classification. For a list of preconfigured values, see Application Classification Code.

eventId

A toolbar generated media event identifier. The same parameter value must be used for all method invocations for a communication. This parameter is stored with internal interaction record.

inData

An object containing information about incoming events for customer identifiable data, as well as attributes containing the names of system or user-defined defined tokens.

callback

Returns results to the caller toolbar.

channelType

The type of channel for which the method is being called. Note that if, for example, the channel is PHONE but the channelType isn't provided, the default value is set to ORA_SVC_PHONE. For more information, see Channel Type Data.

Here's the member attributes of the response object. The object has no return value.

Member Attribute Description

result

The server side running status. Result values are success or error.

error

Contains the error message if the result value is an error. If not, then the value is undefined. For more information about error message codes, see Error Messages: Explained.

Here's sample code for this method:

<html>
<head>
<script type="text/javascript" src="http://domain:port/ora_support/js/mcaInteractionV1.js"> 
</script>
<script type="text/javascript">
function transferCommEvent() {
      var inData = {};
      inData.SVCMCA_ANI = '5551234';
      inData.SVCMCA_CONTACT_ID = '1234567890';
      inData.SVCMCA_CONTACT_NAME = 'John Smith';
      inData.transferredId = '5550987';
      svcMca.tlb.api.transferCommEvent('PHONE', 'ORA_SERVICE', '12345-1234-67890', inData, function (response) {
        if (response.result == 'success') {
          alert('Success! Call transferred to other agent.');
        } else {
          alert('Operation finished with error: ' + response.error);
        }
      },'ORA_SVC_PHONE');
    }</script>
</head>
<body>
<input type="button" value="Notify transfer" onclick="transferCommEvent()"/>
</body>
</html>

upgradeCommEvent

This method is called by the toolbar to inform Engagement Cloud that a new channel has been added to an existing engagement. For example, an agent is chatting with a customer and decides to start a video conference to clarify a concept.

Here's the upgradeCommEvent parameters.

Parameter Description

channel

Name of the channel for which the method is called. For more information on what channels are available, see Channel Type Data.

eventId

Toolbar generated media event identifier. The same parameter value must be used for all method invocations for a communication. This parameter is stored with internal interaction record.

channelType

The type of channel for which the method is being called. For more information, see Channel Type Data.

upgradeChannel

The name of the newly added channel.

upgradeChannelType

The type of the newly added channel.

upgradeEventId

The unique media item identifier for the new communication method.

Note: Engagement Cloud doesn't expect newCommEvent, startCommEvent, or closeCommEvent for these attached engagements.

inData

An object containing information about incoming events for customer identifiable data, as well as attributes containing the names of system or user-defined defined tokens.

callback

Returns results to the caller toolbar.

downgradeCommEvent

This method is called by the toolbar to inform Engagement Cloud that a new channel has been removed from an existing engagement. For instance, an agent who's chatting or video conferencing with a customer, has a disconnection..

Note: If a closeCommEvent is received for the initial or primary channel of communication it's assumed that any attached communications are also disconnected.

Here's the downgradeCommEvent parameters:

Parameter Description

channel

Name of the channel for which the method is called. For more information on what channels are available, see Channel Type Data..

eventId

A toolbar generated media event identifier. The same parameter value must be used for all method invocations for a communication. This parameter is stored with internal interaction record.

channelType

The type of channel for which the method is being called. For more information, see Channel Type Data.

downgradeChannel

The name of the newly added channel.

downChannelType

The type of the newly added channel.

downEventId

The unique media item identifier for the new communication method.

Note: Engagement Cloud doesn't expect newCommEvent, startCommEvent, or closeCommEvent for these attached engagements.

inData

An object containing information about incoming events for customer identifiable data, along with attributes containing the names of system or user-defined defined tokens.

callback

Returns results to the caller toolbar.

invokeScreenPop Method

The toolbar calls this method to trigger the display of a screen pop page. The toolbar provides the page code that's derived from the configuration, and the required tokens configured as parameters for the page.

Here's the parameters for this method:

Parameter Description

channel

Name of the channel for which the method is called.

appClassification

Name of the application classification defined for the current toolbar. If this parameter is passed as null, it's assumed that there is no application classification. For a list of preconfigured values, see Application Classification Code.

eventId

A toolbar generated media event identifier. The same parameter value must be used for all method invocations for a communication. This parameter is stored with internal interaction record.

pageCode

Defined in the application to bring up the screen pop. For more information, see System Pages.

pageData

An object containing information retrieved from IVR or other systems that process incoming events for customer identifiable data. It also contains data received from previous calls to the toolbar API method which is used by Engagement Cloud to process the event. The pageData object has attributes with the names of system or user-defined tokens. When the method is called, the transcript value is stored in the SVCMCA_TRANSCRIPT token.

callback

Returns results to the caller toolbar.

channelType

The type of channel for which the method is being called. Note that if, for example, the channel is PHONE but the channelType isn't provided, the default value is set to ORA_SVC_PHONE. For more information, see Channel Type Data.

The following table lists the member attributes of the response object. The object has no return value.

Member Attribute Description

result

The server side running status. Result values are success or error.

outData

An object containing the system-defined or user-defined tokens returned by an action.

error

Contains error message if the result value is an error. If not, then the value is undefined. For more information about error message codes, see Error Messages.

Here's sample code for this method:

<html>
<head>
<script type="text/javascript" src="http://domain:port/ora_support/js/mcaInteractionV1.js"> 
</script>
<script type="text/javascript">
function invokeScreenPop() {
      var inData = {};
      inData.SVCMCA_ANI = '5551234';
      inData.SVCMCA_CONTACT_ID = '1234567890';
      inData.SVCMCA_CONTACT_NAME = 'John Smith';
      svcMca.tlb.api.invokeScreenPop('PHONE', 'ORA_SERVICE', '12345-1234-67890', 'Edit_Contact', inData, function (response) {
        if (response.result == 'success') {
          alert('Success! Edit Contact page popped.');
        } else {
          alert('Operation finished with error: ' + response.error);
        }
      },'ORA_SVC_PHONE');
    }</script>
</head>
<body>
<input type="button" value="Update event" onclick="invokeScreenPop()"/>
</body>
</html>

getCustomerData Method

This optional method call is called by the toolbar to perform reverse lookup operations during a communication life cycle.

Here's the parameters for this method:

Parameter Description

channel

Name of the channel for which the method is called.

appClassification

Name of the application classification defined for the current toolbar. If this parameter is passed as null, it's assumed that there is no application classification. For a list of preconfigured values, see Application Classification Code.

eventId

A toolbar generated media event identifier. The same parameter value must be used for all method invocations for a communication. This parameter is stored with internal interaction record.

inData

An object containing information about incoming events for customer identifiable data, along with attributes containing the names of system or user-defined defined tokens.

lookupObject

The business object used to run the reverse lookup. This parameter is optional and a default value of Contact is used for customer information. For more information about the list of system lookup objects, see System Business Objects.

callback

Returns results to the caller toolbar.

channelType

The type of channel for which the method is being called. Note that if, for example, the channel is PHONE but the channelType isn't provided, the default value is set to ORA_SVC_PHONE. For more information, see Channel Type Data.

The following table shows a list of member attributes of the response object. The object has no return value.

Member Attribute Description

result

The server side running status. Result values are success or error.

outData

An object containing possible identified data from Engagement Cloud for the contact or organization. This attribute contains the names of system tokens.

error

Contains error message if the result value is an error. If not, then the value is undefined. For more information about error message codes, see Error Messages.

Here's sample code for this method:

<html>
<head>
<script type="text/javascript" src="http://domain:port/ora_support/js/mcaInteractionV1.js"> 
</script>
<script type="text/javascript">
function getCustomerData() {
      var inData = {};
      inData.SVCMCA_ANI = '5551234';
      inData.SVCMCA_CONTACT_ID = '1234567890';
      svcMca.tlb.api.getCustomerData('PHONE', 'ORA_SERVICE', '12345-1234-67890', inData, null, function (response) {
        if (response.result == 'success') {
          console.log('Customer: '+response.outData.SVCMCA_CONTACT_NAME +' ('+response.outData.SVCMCA_CONTACT_ID +')');
          console.log('Account:'+response.outData.SVCMCA_ORG_NAME+'('+response.outData.SVCMCA_ORG_ID+')');
          alert('Success! Results available in log.');
        } else {
          alert('Operation finished with error: ' + response.error);
        }
      },'ORA_SVC_PHONE');
    }</script>
</head>
<body>
<input type="button" value="Get customer data" onclick="getCustomerData()"/>
</body>
</html>

Window Management API

Overview of Window Management APIs

The Window Management API facilitates additional toolbar management from the main horizontal toolbar. Engagement Cloud acts as a message bus for communication between horizontal, vertical, and notification toolbars, and enables opening and closing of the vertical toolbar. The Window Management API is broken up into three groups, Embedded (Horizontal) Toolbar APIs, Live Window Controller (Vertical) Toolbar APIs, and Inter-Toolbar Communication APIs.

Embedded Toolbar API

The following table lists the Embedded Toolbar APIs and their usage.

Note: Although the Embedded (horizontal) Toolbar API functionality is still supported, you will find a more complete set of functionality if you use the Live Window Controller (Vertical) Toolbar APIs. Live Window is also where all new features will be developed and deployed going forward. For more information, see the Live Window Controller topic which follows this one.
Method Description

openFloatingToolbar

Requests Engagement Cloud to programmatically open a floating toolbar.

isFloatingToolbarOpen

Requests Engagement Cloud to determine whether the floating toolbar is open or not.

closeFloatingToolbar

Requests Engagement Cloud to programmatically close the floating toolbar.

setToolbarDimensions

Sets toolbar dimensions for horizontal and vertical toolbars.

Live Window Controller API

This table lists the Live Window Controller (Vertical) Toolbar APIs and their usage.

Method Description

openCompanionPanel

Requests Engagement Cloud to programmatically open a companion panel.

isCompanionPanelOpen

Requests Engagement Cloud to determine whether the companion panel is open or not.

closeCompanionPanel

Requests Engagement Cloud to programmatically close the companion panel.

Inter-Toolbar Communication API

This table lists the Inter-Toolbar Communication APIs and their usage.

Method Description

postToolbarMessage

Sends a message from one toolbar, such as the horizontal toolbar, to another, such as the floating toolbar using Engagement Cloud as a message bus.

onToolbarMessage

Registers a callback for the messages exchanged between toolbars.

openFloatingToolbar Method

The toolbar calls this optional method to programmatically open an additional toolbar.

The parameters for this method as listed in the following table. The method has no return value.

Parameter Description

url

The URL of the page opened in the iFrame of the floating toolbar. If this value is null, Engagement Cloud attempts to locate the URL in the configuration.

height

The initial height of the additional toolbar.

Note: Height is limited to 470 pixels. Exceeding this will result in an error.

width

The initial width of the additional toolbar

Note: Width is limited to 470 pixels. Exceeding this will result in an error.

inData

An object containing information about incoming events for the floating dialog box. The inData object has attributes with the names of system or user-defined tokens.

callback

Method callback to inform the caller toolbar of the results.

result

The server side status of the running method. This attribute has values of success or error.

error

Contains error messages. If there's no error, the value is undefined. For more information about error message codes, see Error Messages.

Note: The width and height attribute values are limited to 470 pixels. Using a higher value in method attributes returns an error message.

closeFloatingToolbar Method

The toolbar calls this optional method to programmatically close an additional toolbar.

The method parameters as listed in the following table. This method has no return value.

Parameter Description

callback

Method callback to inform the caller toolbar of the results.

result

The server side status of the running method. This attribute has values of success or error.

error

Contains error messages. If there's no error, the value is undefined. For more information about error message codes, see Error Messages: Explained.

postToolbarMessage Method

The toolbar calls this method to send messages from one toolbar to another. Engagement Cloud sends a payload message to all opened toolbars, except to the toolbar that has sent the message.

The parameters for this method as listed in the following table. The method has no return value.

Parameter Description

messagePayload

Payload to be passed to the other toolbars.

callback

Method callback to inform the caller toolbar of the results.

result

The server side status of the running method. This attribute has values of success or error.

error

Contains error messages. If there's no error, the value is undefined. For more information about error message codes, see Error Messages.

onToolbarMessage

This method registers a callback for messages exchanged between toolbars. The callback is registered only for the toolbar that sent the message.

The following table shows the parameters for this method. The method has no return value.

Parameter Description

callback

Method called when a message is received from other toolbars.

result

The server side status of the running method. This attribute has values of success or error.

messagePayload

Payload from toolbar.

error

Contains error messages. If there's no error, the value is undefined. For more information about error message codes, see Error Messages.

setToolbarDimensions Method

The toolbar calls this optional method to change the current dimensions of the toolbar which are represented by barType parameter. If the wanted screen dimension isn't available, the maximum screen space that's available is allocated and an error message is sent back to toolbar.

The parameters for this method as listed in the following table. The method has no return value.

Parameter Description

barType

Type of toolbar to which the changes apply. Possible values are: MAIN_HORIZONTAL, FLOAT_VERTICAL, or NOTIFICATION.

height

The toolbar height.

width

The toolbar width. This parameter doesn't apply to MAIN_HORIZONTAL toolbars.

callback

Method callback to inform the caller toolbar of the results.

result

The server side status of the running method. This attribute has values of success or error.

error

Contains error messages. If there's no error, the value is undefined. For more information about error message codes, see Error Messages.

Note: The width and height attribute values are limited depending on the toolbar for which the method is invoked. For horizontal toolbars, the height has a maximum value of 70 pixels, and width value is ignored. For vertical toolbars, the height and width must not be more than 470 pixels. For notification toolbars, the height has a maximum value of 180 pixels and width has a maximum value of 350 pixels. Using a bigger value in method attributes leads to capping to maximum value and returning an error message.

Here's sample code to call this method.

<html>
<head>
<script type="text/javascript" src="http://domain:port/ora_support/js/mcaInteractionV1.js"> 
</script>
<script type="text/javascript">
function setHeight(newHeight) {
      svcMca.tlb.api.setToolbarDimensions("MAIN_HORIZONTAL", newHeight, 0, function (response) {
        if (response.result == 'success') {
          alert('Success! New height set!');
        } else {
          alert('Operation finished with error: ' + response.error);
        }
      });
    }</script>
</head>
<body>
<input type="button" value="Change height" onclick="setHeight(50)"/>
</body>
</html>

Event Listener API

Overview of Event Listener APIs

The event listener API allows the toolbar register listeners to track events that are triggered by Engagement Cloud. This allows Engagement Cloud to initiate outbound interaction events and send updates to the toolbar.

Here's a list of the Event Listener APIs and their usage.

Method Usage

agentStateEvent

Notifies Engagement Cloud of changes in a user's signed in or availability status for the specified channel.

onDataUpdated

Registers a callback for customer data update events to be transmitted to the media toolbar with the updated information.

focusInteractionEvent

Notifies Engagement Cloud that the toolbar has changed the previously active interaction slot to a different interaction slot.

onOutgoingEvent

Registers a toolbar-initiated callback for the start of an outgoing event triggered from Engagement Cloud.

outboundCommError

Notifies Engagement Cloud that an error occurred during initiation of the outbound event.

onToolbarAgentCommand

Registers a listener with Engagement Cloud to provide agent control functionality.

onToolbarInteractionCommand

Registers a listener with Engagement Cloud to provide interaction control functionality.

agentStateEvent Method

This method notifies Engagement Cloud of a change in the user's signed in or availability status for the specified channel.

Here's a list of the method parameters:

Parameter Description

channel

Name of the channel.

eventId

Unique identifier for the event.

isAvailable

Boolean to indicate if the user is available to receive routed assignments for the specified channel.

isLoggedIn

Boolean to indicate if the user is signed in to the specified channel.

stateCd

System code to indicate the current availability status of the user.

stateDisplayString

Translatable string to display on the the availability status of the user on the Engagement Cloud UI.

reasonCd

(Optional) System code to indicate the reason for the current availability status.

reasonDisplayString

(Optional) Translatable string to display the reason for the current status on the Engagement Cloud UI.

inData

Object containing the name value pairs if additional details are required.

callback

Function on the toolbar to indicate event receipt by Engagement Cloud.

channelType

The type of channel.

The following is sample code to call this method.

<html>
<head>
<script type="text/javascript" src="http://domain:port/ora_support/js/mcaInteractionV1.js">
</script>
<script type="text/javascript">
   function agentStateEvent() {
      svcMcaTlb.api.agentStateEvent("PHONE","1",true,true,"AVAILABLE","Available",null,null,{}, 
         function(response){
            if (response.result == 'success') {
               alert("success response for agentStateEvent received");
            } else {
               alert("error response for agentStateEvent received: "+response.error);
            }
         }, 'ORA_SVC_PHONE');
   }
</script>
<body>
   <input type="button" value="Fire agentStateEvent" onclick="agentStateEvent()"/>
</body>
</html>

onDataUpdated Method

The toolbar calls this method to register the callback listener for a data update which occurred in Engagement Cloud which must be transmitted to the toolbar. Using this listener, Engagement Cloud can send notifications about updates of Engagement Cloud contact information which will then be reflected in the toolbar. Additionally, Engagement Cloud can use this method to notify the toolbar that Engagement Cloud actions, such as a Wrap-up, have been completed.

Here's the parameters for this method:

Parameter Description

channel

Name of the channel for which the method is called.

appClassification

Name of the application classification defined for the current toolbar. If this parameter is passed as null, it's assumed that there are no application classifications. For a list of ready to use values, see Application Classification Code.

callback

Method callback to inform the caller toolbar of the results.

channelType

The type of channel for which the method is being called. For instance, if the channel is PHONE and the channelType isn't provided, the default value is set to ORA_SVC_PHONE. For more information, see Channel Type Data.

The response object has the following member attributes.

Attribute Description

updateType

Type of update. The values can be CUSTOMER_DATA or WRAPUP_CLOSED or OFFER_TIMEOUT.

eventId

Media event identifier that's used to identify which communication event is targeted by this update.

outData

Object that has attributes with the names of system token, such as SVCMCA_CONTACT_ID, SVCMCA_CONTACT_NAME, SVCMCA_ORG_ID, and SVCMCA_ORG_NAME.

Here's sample code to call the method:

<html>
<head>
<script type="text/javascript" src="http://domain:port/ora_support/js/mcaInteractionV1.js"> 
</script>
<script type="text/javascript">
function onDataUpdated() {
      svcMca.tlb.api.onDataUpdated('PHONE','ORA_SERVICE', function (response) {
        console.log('Media Event: '+response.eventId);
        console.log('Contact number: '+response.outData.SVCMCA_CONTACT_ID);
        console.log('Contact name: '+response.outData.SVCMCA_CONTACT_NAME);
        console.log('Organization number: '+response.outData.SVCMCA_ORG_ID);
        console.log('Organization name: '+response.outData.SVCMCA_ORG_NAME);
        alert('Customer data got updated, see in the log.');
      },'ORA_SVC_PHONE');
    }</script>
</head>
<body>
<input type="button" value="Register data update listener" onclick="onDataUpdated()"/>
</body>
</html>

focusCommEvent Method

This optional method notifies Engagement Cloud that the toolbar has changed the previously active communication slot to a different communication slot.

Here's the parameters for this method:

Parameter Description

eventId

A unique media item identifier. The value must match the value supplied by the toolbar in the newCommEvent.

channel

Name of the channel for which the method is called. For more information on what channels are available, see Channel Type Data.

channelType

The type of channel for which the method is being called.

inData

Object containing additional event details. An empty object may be passed. This parameter is reserved for future use.

callback

Function used by Engagement Cloud on the toolbar which indicates receipt of an Engagement Cloud event.

Sample code to call the method:

<html>
<head>
<script type="text/javascript" src="http://domain:port/ora_support/js/mcaInteractionV1.js">
</script>
<script type="text/javascript">
   function focusCommEvent() {
      svcMcaTlb.api.focusCommEvent("1","PHONE","ORA_SVC_PHONE",{},function(response){
         if (response.result == 'success') {
            alert("success response for focusCommEvent received");
         } else {
            alert("error response for focusCommEvent received: "+response.error);
         }
       }, );
   }
</script>
<body>
   <input type="button" value="Fire focusCommEvent" onclick="focusCommEvent()"/>
</body>
</html>

onOutgoingEvent Method

The toolbar calls this method to register the callback listener for Engagement Cloud which triggers an outgoing communication event. Using this callback Engagement Cloud passes the information required for the toolbar to perform the outgoing event.

Here's the parameters for this method:

Parameter Description

channel

Name of the channel for which the method is called.

appClassification

Name of the application classification defined for the current toolbar. If this parameter is passed as null, it's assumed that there are no application classifications. For a list of ready to use values, see Application Classification Code.

callback

Function used by Engagement Cloud on the toolbar which indicates receipt of an Engagement Cloud event.

channelType

The type of channel for which the method is being called. For instance, if the channel is PHONE and the channelType isn't provided, the default value is set to ORA_SVC_PHONE. For more information, see Channel Type Data.

The response passed in the callback has attributes with system token names, such as SVCMCA_ANI, SVCMCA_EMAIL, SVCMCA_CONTACT_ID, and SVCMCA_CONTACT_NAME. There are no returns.

Here's sample code to call the method:

<html>
<head>
<script type="text/javascript" src="http://domain:port/ora_support/js/mcaInteractionV1.js"> 
</script>
<script type="text/javascript">
function onOutgoingEvent() {
      svcMca.tlb.api.onOutgoingEvent('PHONE','ORA_SERVICE', function (response) {
        console.log('Calling: '+response.SVCMCA_ANI);
        console.log('Contact name: '+response.SVCMCA_CUSTOMER_NAME);
        alert('Initiating outgoing call, see information in the log.');
      },'ORA_SVC_PHONE');
    }d>
<body>
<input type="button" value="Register outcall listener" onclick="onOutgoingEvent()"/>
</body>
</html>

outboundCommError Method

The toolbar calls this method to notify Engagement Cloud that an error occurred during initiation of the outbound event. The error occurs if the identifier of the event, such as phone number, or email can't be used to establish a connection.

Here's the parameters for this method:

Parameter Description

channel

Name of the channel for which the method is called.

commUuid

A unique identifier sent from Engagement Cloud to the toolbar containing the outgoing event notification.

errorCode

Code to identify the exception that can be used by the agent to identify the nature of the error to contact toolbar support.

errorMsg

Error message displayed to the user.

callback

Function used by Engagement Cloud on the toolbar which indicates receipt of an Engagement Cloud event.

channelType

The type of channel for which the method is being called. For instance, if the channel is PHONE and the channelType isn't provided, the default value is set to ORA_SVC_PHONE. For more information, see Channel Type Data.

The response object has the following member attributes. There are no returns.

Attribute Description

result

Represents the status of the method on the server side. Values are success and error.

error

Contains error messages. If there's no error, the value is undefined. For more information about error message codes, see Error Messages.

Here's sample code to call the method:

<html>
<head>
<script type="text/javascript" src="http://domain:port/ora_support/js/mcaInteractionV1.js"> 
</script>
<script type="text/javascript">
function onTestError() {
      svcMca.tlb.api.outboundCommError('PHONE','123456789', '233', 'Could not establish connection, bad number!', function (response) {
        alert('Error message delivered, status: '+response.result);
      },'ORA_SVC_PHONE');
    }</script>
</head>
<body>
<input type="button" value="Register data update listener" onclick="onTestError()"/>
</body>
</html>

onToolbarAgentCommand Method

This method registers a listener with Engagement Cloud to give the agent control functionality. The method is only called once during initialization.

Here's the parameters for this method:

Parameter Description

channel

Name of the channel for which the method is called.

channelType

The type of channel for which the method is being called. For instance, if the channel is PHONE and the channelType isn't provided, the default value is set to ORA_SVC_PHONE. For more information, see Channel Type Data..

executor

The function implemented by the toolbar which is used by the agentCommandPrototype object.

The agentCommandPrototype object has these attributes:

Attribute Description

eventId

Represents the status of the method on the server side. Values are success and error.

command

Contains error messages. If there is no error, the value is undefined. For more information about error message codes, see Error Messages.

The following commands are available:

  • getCurrentAgentState

  • getActiveEngagements: The outData must contain the activeCount number and the engagements array value. For example: { activeCount:1, engagements:[ {eventId:"1234"} ] }. If there are no active engagements, the engagements parameter must be an empty array.

  • makeAvailable

  • makeUnavailable

channel

The channel name.

channeltype

The type of channel.

inData

The object containing the name value pairs for the command parameters.

result

Populated by the toolbar after the command process has completed successfully. If there was a failure, the reason will be displayed.

resultDisplayString

Error displayed to the user, and populated by the toolbar.

outdata

Populated by the toolbar if the command required output data.

sendResponse

Callback function used upon completion of the command processing. The sendResponse method must be passed to the command object with the result populated. Also the outData and resultDisplayString attributes must be populated if required.

Here's sample code to call the method:

<html>
<head>
<script type="text/javascript" src="http://domain:port/ora_support/js/mcaInteractionV1.js">
</script>
<script type="text/javascript">
   function agentCommandExecutor(command) {
       var cmd = command.command;
       switch(cmd) {
          case "getCurrentAgentState":
             command.outData = {
                'channel':command.channel,
                'channelType':command.channelType,
                'isAvailable':true,
                'isLoggedIn':true,
                'state':"AVAILABLE",
                'stateDisplayString':"Available",
                'reason':null,
                'reasonDisplayString':null};
             break;
          case "getActiveEngagements":
             command.outData = {'activeCount':1,'engagements' : [ {eventId:"1234"} ] };
             break;
          case "makeAvailable":
             alert("makeAvailable command invoked");
             break;
          case "makeUnavailable":
             alert("makeUnavailable command invoked");
       }
       command.result = 'success';
       command.sendResponse(command);
   }

   function registerAgentCommandListener() {
      svcMcaTlb.api.onToolbarAgentCommand("PHONE", "ORA_SVC_PHONE", agentCommandExecutor);
   }
</script>
<body>
   <input type="button" value="Register interaction command listener" onclick="registerAgentCommandListener()"/>
</body>
</html>

onToolbarInteractionCommand Method

Registers a listener with Engagement Cloud to provide interaction control functionality. This must be called once during initialization. The executor function is used with an interactionCommandPrototype object.

The interactionCommandPrototype object has the following attributes:

Attribute Description

eventId

Unique media item identifier supplied by the toolbar during the newCommEvent.

command

Name of the command to execute. The following commands are available:

  • accept: Accepts the incoming engagement.

  • reject: Rejects the incoming engagement.

  • setActive: Discloses the specified engagement slot to the toolbar.

slot

An optional toolbar identifier supplied by the toolbar during the newCommEvent.

inData

The object containing the name value pairs for the command parameters.

result

Populated by the toolbar after the command process has completed successfully. If there was a failure, the reason will be displayed.

resultDisplayString

Error displayed to the user, and populated by the toolbar if the command

outdata

Populated by the toolbar if the command required output data.

sendResponse

Callback function used upon completion of the command processing. The sendResponse method must be passed to the command object with the result populated. Also the outData and resultDisplayString attributes must be populated if required.

The following is sample code to call the method:

<html>
<head>
<script type="text/javascript" src="http://domain:port/ora_support/js/mcaInteractionV1.js">
</script>
<script type="text/javascript">
   
   function interactionCommandExecutor(command) {
      switch(command.command)
      case "accept":
         alert("Received accept command");
         break;
      case "reject":
         alert("Received reject command");
         break;
      case "setActive":
         alert("Received setActive command");
         break;
      }
      command.result = 'success';
      command.sendResponse(command); 
   }

   function registerInteractionCommandListener() {
      svcMcaTlb.api.onToolbarInteractionCommand(interactionCommandExecutor);
   }
</script>
<body>
   <input type="button" value="Register interaction command listener" onclick="registerInteractionCommandListener()"/>
</body>
</html>

API Features

Features are functionality or sets of functionality that are supported by Oracle Engagement Cloud, and can be implemented by a toolbar. Features are supported by the API and underlying Oracle Engagement Cloud implementation. The following table lists the features of the API:

Feature Code What you can do with the Feature

INBOUND_CALL

Handle messages related to inbound calls.

OUTBOUND_CALL

Handle messages related to outbound calls. The API notifies the toolbar to initiate the call using the supplied information.

TRANSFER_CALL

Handle messages related to a call transfer.

CONFERENCE_CALL

Handle messages related to a call conference.

OUTBOUND_CALL_EXTENSIONS

Handle messages related to outbound calls. The API notifies the toolbar to initiate the call with the specified phone number and extension.

System Tokens

System tokens include the following tokens types.

  • Data tokens: Represent data values in the Multichannel Application

  • Control tokens: Control the flow of an interaction

The following table lists the data tokens.

Data Token Name Token Code Description

Asset Id

SVCMCA_ASSET_ID

Asset Identifier.

Asset Name

SVCMCA_ASSET_NAME

Asset Name.

Asset Number

SVCMCA_ASSET_NUM

Asset Number.

Channel Id

SVCMCA_CHANNEL_ID

Channel Identifier which is populated from Channel Name to be passed for page parameters.

Communication direction

SVCMCA_COMMUNICATION_DIRECTION

Communication direction, which can be inbound or outbound.

Communication Reason

SVCMCA_WRAPUP_COMM_REASON

Communication Reason of the Interaction

Contact First Name

SVCMCA_CONTACT_FIRST_NAME

Contact's first name.

Contact ID

SVCMCA_CONTACT_ID

Contact person identifier. This ID value may be available on the customer documentation or it can be retrieved from the application for use.

Contact Last Name

SVCMCA_CONTACT_LAST_NAME

Contact's last name.

Contact Name

SVCMCA_CONTACT_NAME

Contact name. Obtained from Engagement Cloud for use.

Contact Organization ID

SVCMCA_CONTACT_ORG_ID

Contact's primary organization ID.

Contact Organization Name

SVCMCA_CONTACT_PRIM_ORG_NAME

Contact's primary organization name.

Contact Phone Number

SVCMCA_CONTACT_PRIMARY_PHONE

Contact's primary phone number.

Display Name

SVCMCA_DISPLAY_NAME

Contact name or other identifying contact information to be displayed in supplier toolbars.

Email

SVCMCA_EMAIL

Contact email. Can be obtained from IVR or from Engagement Cloud for use.

Interaction identifier

SVCMCA_INTERACTION_ID

Interaction identifier. Obtained from the application for use. Can be sent from the application using the APIs to prevent creating duplicate interactions.

Interaction Notes

SVCMCA_WRAPUP_INTERACTION_NOTES

Notes of the Interaction

Lead ID

SVCMCA_LEAD_ID

Lead Id. Can be obtained from IVR system or from FA module and reused subsequently.

Lead Name

SVCMCA_LEAD_NAME

Lead name. Usually, will be obtained from FA module and reused subsequently.

Loyalty Member ID

SVCMCA_LOYALTY_MEMBER_ID

Loyalty Member Identifier

Loyalty Member Name

SVCMCA_LOYALTY_MEMBER_NAME

Loyalty Member Name

Loyalty Member Number

SVCMCA_LOYALTY_MEMBER_NUMBER

Loyalty Member Number

Mobile Phone Area Code

SVCMCA_MOBILE_AREA

Mobile Phone Area Code. Token value from the call data that can be passed to the contact picker when creating a contact.

Mobile Phone Country Code

SVCMCA_MOBILE_CC

Mobile Phone Country Code. Token value from the call data that can be passed to the contact picker when creating a contact.

Mobile Phone Local Number

SVCMCA_MOBILE_LOCAL

Mobile Phone Local Number. Token value from the call data that can be passed to the contact picker when creating a contact.

Object ID List

SVCMCA_OBJ_ID_LIST

Object Id List for filtered display of specific objects.

Opportunity ID

SVCMCA_OPPORTUNITY_ID

Opportunity Id. Can be obtained from IVR system or from FA module and reused subsequently.

Opportunity Name

SVCMCA_OPPORTUNITY_NAME

Opportunity name. Usually, will be obtained from FA module and reused subsequently.

Organization ID

SVCMCA_ORG_ID

Account or organization ID. The ID may be available on the customer documentation. The ID can be identified by Interactive Voice Response (IVR) or can be retrieved from Engagement Cloud for use.

Organization Name

SVCMCA_ORG_NAME

Account name. Obtained from Engagement Cloud for use.

Phone Area Code

SVCMCA_PHONE_AREA

Work Phone Area Code. Token value from the call data that can be passed to the contact picker when creating a contact.

Phone Country Code

SVCMCA_PHONE_CC

Work Phone Country Code. Token value from the call data that can be passed to the contact picker when creating a contact.

Phone Extension

SVCMCA_PHONE_EXT

Work Phone Extension. Token value from the call data that can be passed to the contact picker when creating a contact.

Phone Local Number

SVCMCA_PHONE_LOCAL

Work Phone Local Number. Token value from the call data that can be passed to the contact picker when creating a contact.

Phone Number

SVCMCA_ANI

Automatic Number Identification value sent from telephony provider.

Resolution Code

SVCMCA_WRAPUP_RESOLUTION_CODE

Resolution Code of the Interaction

Service Request Identifier

SVCMCA_SR_ID

Service request identifier. Obtained from Engagement Cloud for use.

Service request Number

SVCMCA_SR_NUM

Service request number to be passed whenever the number is available.

Service Request Title

SVCMCA_SR_TITLE

Service request title. Obtained from the application for use.

Task ID

SVCMCA_TASK_ID

Task ID.

Transfer Reason

SVCMCA_WRAPUP_TRANSFER_REASON

Transfer Reason of the Interaction

Universal Work Object Identifier

SVCMCA_UWO_ID

Specifies the universal work object identifier.

Work Order Id

SVCMCA_WORK_ORDER_ID

Work Order Identifier.

Work Order Number

SVCMCA_WORK_ORDER_NUM

Work Order Number.

The following table lists the data tokens for HR HelpDesk use.

Data Token Name Token Code Description

Person Email

SVCMCA_PER_EMAIL

Person Email address

Person Id

SVCMCA_PER_PERSON_ID

Person Unique Identifier

Person List Name

SVCMCA_PER_LIST_NAME

Person last name, first name

Person Name

SVCMCA_PER_NAME

Person display name

Person National Id Number

SVCMCA_PER_NAT_ID_NUM

Person's National Id Number

Person Number

SVCMCA_PER_NUMBER

Person Number

Person Phone

SVCMCA_PER_PHONE

Person Phone number

The following table lists the control tokens.

Control Token Name Token Code Description

Parent interaction identifier

SVCMCA_PARENT_INTERACTION_ID

Parent interaction identifier in the case of a transfer. Expected to be sent along a new communication event data of the second call.

Secondary Call Type

SVCMCA_2NDARY_CALL_TYPE

A type of secondary party call, which can be one of Transfer, Conference, and Consult. This value must be sent by the toolbar on a new communication event when transferring to the second agent.

Skip customer identification step

SVCMCA_BYPASS_IDENTIFY_CONTACT

Skips automatic customer identification upon receiving an inbound interaction. This token can be used with the startCommEvent() call.

Skip customer verification step

SVCMCA_BYPASS_CUSTOMER_VERIFICATION

Skips automatic customer verification screen to be made available to the agent. This token can be used with the startCommEvent() call.

Skip Reverse Lookup

SVCMCA_BYPASS_REVERSE_LOOKUP

Skip automatic reverse lookup of contact.

Skip the auto screen pop engine

SVCMCA_BYPASS_AUTO_SCREEN_POP

Skips the automatic run of screen pop engine upon accepting the interaction by the agent. This token can be used with the startCommEvent() call.

System Pages

The following table lists the pages that are available for screen pop. Use the page codes with the invokeScreenPop() method to open a screen pop page. For more information about the method, see "Interaction API: Explained".

Page Name Page Code What does it do

Create Account

Create_Account

Accepts details of an account.

Create Contact

Create_Contact

Accepts details of a contact.

Create Lead

Create_Lead

Accepts details for a lead.

Create Opportunity

Create_Opportunity

Accepts details for an opportunity.

Create Service Request

Create_Service_Request

Accepts details of a service request.

Create Work Order

Create_Work_Order

Accepts details of a work order.

Edit Account

Edit_Account

Displays the details of an account or organization information. The displayed page information can be changed based on the rights associated with agent role.

Edit Asset

Edit_Asset

Displays details of an asset.

Edit Contact

Edit_Contact

Displays details of a contact or customer information. The displayed information can be changed based on the rights associated with agent role.

Edit Contact - Leads

Edit_Contact_Leads_Tab

Displays details of a lead for a given contact or customer.

Edit Contact - Opportunities

Edit_Contact_Opportunities

Displays details of an opportunity for a given contact or customer.

Edit Contact - Service Requests

Edit_Contact_Service_Requests

Displays details of a service request for a given contact or customer.

Edit Lead

Edit_Lead

Displays details of a lead.

Edit Loyalty Member

Edit_Loyalty_Member

Displays details of a Loyalty member.

Edit Opportunity

Edit_Opportunity

Displays details of an opportunity.

Edit Service Request

Edit_Service_Request

Shows details of a service request. Page information can be edited according with the rights associated with agent role.

Edit Service Request - Work Order

Edit_Work_Order_From_SR

Shows details of a work order for a given service request.

Edit Work Order

Edit_Work_Order

Shows details of a work order.

Opportunity List

Opportunity_List

Shows details of an opportunity.

Service Request List

Service_Request_List

Shows details of a service request.

Work Order List

Work_Order_List

Shows details of a work order.

System Business Objects

The following table lists the business objects.

What would you like to do? How to do it

Describe account or organization information.

Select Account

Describe activity information

Select Activity

Describe asset information.

Select Asset

Describe the contact or customer information.

Select Contact

Describe lead information.

Select Lead

Describe loyalty member information.

Select Member

Describe opportunity information.

Select Opportunity

Describe person information.

Select Person Picker

Describe resource information.

Select Resource

Describe service request information.

Select ServiceRequest

Describe work order information.

Select WorkOrder

Describe wrap up information.

Select Wrap Up

Channels Code

Channels are configured using the Functional Setup Manager within Oracle Engagement Cloud. The following table lists the channel codes:

Channel Code Description

PHONE

Phone channel.

CHAT

Chat channel.

EMAIL

Email channel.

Application Classification Code

The following table lists the ready-to-use application classification codes that the application recognizes. The list of application classifications can be modified using Functional Setup Manager.

Application Classification Code Description

ORA_HRHD

Default classification for Human Resources Help Desk related setup for Lookup rules and Screen Pop rules.

ORA_SALES

Default classification for sales-related setup for Lookup rules and Screen Pop rules.

ORA_SERVICE

Default classification for service-related setup for Lookup rules and Screen Pop rules.

Error Messages

The following table lists the codes for error messages that are returned in case of an exception while running Oracle Engagement Cloud functionality in response to toolbar requests.

Error Message Code When is the error message returned?

SVCMCA_ERR_NOTIMPLEMENTED

Specified functionality isn't implemented.

SVCMCA_ERR_MISSING_CONFIGURATION

Specified functionality is based on a configuration information that's missing. For example, call for invokeScreenPop() method with a pageCode attribute that's not present in screen pop pages configuration in Setup and Maintenance.

SVCMCA_ERR_INVALID_DIMENSIONS

Specified dimension of the toolbars is invalid.

SVCMCA_ERR_INVALID_CONFIGTYPE

Specified configuration is of an invalid type.

SVCMCA_ERR_UNKNOWN_METHOD

Unknown method invoked on the API.

Channel Type Data

The following table lists the channel types, which are predefined lookups identified by the ORA_SVC_CHANNEL_TYPE_CD lookup type.

Channel Code What is it used for

ORA_SVC_CHAT

Chat channel

ORA_SVC_EMAIL

E-mail channel

ORA_SVC_PHONE

Phone channel

ORA_SVC_SOCIAL

Social channel

ORA_SVC_WEB

Web channel

ORA_SVC_NONE

None