Communication DN API

Overview

Outbound Contact provides a Communication DN (CommDN) API that enables third-party applications, such as an inbound agent desktop, to submit DoNotCall (DNC) and record-cancel requests. To use the API, a custom application must be able to access Genesys T-Server and Configuration Server, both of which have open APIs.

The Communication DN API also enables users to control campaigns and campaign sequences through third-party applications or scripts instead of OCM or Genesys Administrator. The third-party applications (customer applications) can be GUI applications or automated scripts that perform different kinds of scheduling, sequencing, and so on. For example, scripts can be customized to do such things as stop campaigns when all the records are dialed or mark some records as Cancelled.

In order for OCS to process requests from a third-party application, it is necessary to set up a connection between them. You can do this in either the third-party application or OCS.

Connection using OCS Application Object

1. Create an application of a type Third-Party Server in Genesys Administrator.
   
2. Add this application object to the Connection tab of the OCS application.
   

Connection using Third-Party Application Object

1. Create an application of a type Third-Party Application in Genesys Administrator.
   
2. Add the OCS application object to the Connection tab of this application.
   

OCS and API Requests

OCS accepts only those API requests that come from the following sources:

• Third-party servers included in the OCS Connections tab
  
• Third-party applications that include the OCS application object in their Connection tabs.
  

All other requests are disregarded.

Data Formats

OCS and third-party applications communicate through the Communication DN API by means of UserEvents (with attached user data) that are sent and received on a CommDN. The attached user data is encoded as a key-value pairs list (TKVList). Values can be either string or integer. These values are described in “User Data Enumeration Values" in User Data Enumeration Values. The communication is based on two types of messages: Request-Response and unsolicited notification.

Protocol Sequencing

OCS uses three types of messages to communicate:

• Requests
  
• Responses
  
• Notifications
  

Protocol Sequencing for the Communication DN API shows the messaging sequence of the Communication DN API protocol.
 

Protocol Sequencing for the Communication DN API

Mandatory Attributes

Requests or events sent through the CommDN must include the following mandatory attributes:

• OriginAppDBID (the DBID of the sender)

If the OriginAppDBID in a request pertains to a third-party application, you must configure it according to the common Communication DN protocol, as explained in Communication Protocols.

• TargetAppDBID (the DBID of the receiver)

Communication Structure shows the communication structure for the Communication DN API. If OCS receives an incorrect request or the wrong data or request sequence, it may send a CM_EvError event.
 

Communication Structure

Request	Response/Notification	Mandatory Attributes
CM_ReqLoadCampaign	CM_EvCampaignLoaded	CampaignDBID or Properties OCS checks CampaignDBID . If the value is 0 , the request or event must have the proper schedule in the Properties attribute. GroupDBID DialMode OptimizeBy OptimizeGoa l
CM_ReqUnloadCampaign	CM_EvCampaignUnloaded	CampaignDBID GroupDBID
CM_ReqGetCampaignStatus	CM_EvCampaignStatus	Request CampaignDBID or Properties OCS checks CampaignDBID. If the value is 0, the request or event must have the proper schedule in theProperties attribute. If CM_ReqGetCampaignStatus CampaignDBID equals0 , OCS responds with the sequence status. GroupDBID Response or Notification CampaignDBID or Properties GroupDBID DialMode OptimizeBy OptimizeGoal GroupCampStatus. If a campaign belongs to a Sequence, then the attribute GroupCampStatus status represents the part of each scheduleItem (<n> in the Sequence. See User Event Structure for the Communication DN API.
CM_ReqSetDialingMode	CM_EvDialingModeChanged	CampaignDBID or Properties GroupDBID DialMode OptimizeBy OptimizeGoal
CM_ReqStartDialing	CM_EvDialingStarted	CampaignDBID or Properties GroupDBID DialMode OptimizeBy OptimizeGoal
CM_ReqStopDialing	CM_EvDialingStopped	CampaignDBID or Properties GroupDBID
CM_ReqDoNotCall	CM_EvDoNotCallProcessed	Phone CustomerID
CM_ReqCancelRecord	CM_EvRecordCanceled or CMEvError	OriginAppDBID (the DBID of the sender) TargetAppDBID (the DBID of the receiver) Phone For CM_ReqCancelRecor d, the TargetAppDBID may be 0 , which means that all Outbound Contact Servers that monitor the communication DN will process this request and submit a response.

Special OCS Option

Usually OCS works with all existing CommDNs in the Configuration Database. You can reduce the number of CommDNs OCS uses by assigning the outbound_contact_server option to these DNs. Set this option’s value totrue if you want OCS to communicate with third-party applications through a specified DN. To configure this option, see outbound_contact_server in the Outbound Contact 8.1 Deployment Guide for more information.

The following three examples describe how to apply the outbound_contact_server option.

• You can set at least one CommDN to a value of true for this option. OCS works only with those CommDNs set to true. OCS disregards all CommDNs not set to true.
  

Example 1:

CommDN_1: outbound_contact_server = true

CommDN_2: outbound_contact_server = false

CommDN_3: outbound_contact_server = undefined

In this configuration, OCS uses only CommDN_1.

• You can set some CommDNs to a value of false and set others to a value ofundefined. In this set up, all CommDNs with a value of falseare excluded from OCS, while the undefined values remain available to OCS.
  

Example 2:

CommDN_1: outbound_contact_server = false

CommDN_2: outbound_contact_server = undefined

CommDN_3:outbound_contact_server = undefined

In this configuration, OCS uses CommDN_2 and CommDN_3.

• You can set all CommDNs to an undefined value (default value) for this option to make CommDNs available for OCS.
  

Example 3:

CommDN_1: outbound_contact_server = undefined

CommDN_2: outbound_contact_server = undefined

CommDN_3: outbound_contact_server = undefined

In this configuration, OCS uses all CommDNs.

User Event Structure

User Event Structure for the Communication DN API shows the user event structure for communication between third-party applications and the Communication DN API.

User Event Structure for the Communication DN API

Note:

The event scheduleItem-<n > (<n > represents an integer) is formed by the prefix “scheduleItem-" and the number (converted to string), which equals 1 ...n Items. For more information about the user event, campaign_schedule, see User Event Attributes for campaign_schedule (TKVList).

User Data Enumeration Values

Some of the Genesys mandatory fields are represented as predefined integer constants. When these fields are attached to user events or telephony events as key-value pairs, the values of these fields are sent as integers (sometimes also called Enumeration values or internal representations). User Event Attributes for User Data (TKVList) lists the Genesys user event attributes sent with user data through the Communication DN API.

 

User Event Attributes for User Data (TKVList)

Key	Type	Description
GSW_CM_MessageType	Int	See the Enum values for GSW_CM_MessageType on Data Enumeration Values for GSW_CM_MessageType.
GSW_CM_AttrDialMode	Int	See the Enum values for GSW_CM_AttrDialMode on Enumeration Values for GSW_CM_AttrDialMode.
GSW_CM_AttrOptimizeBy	Int	See GSW_CM_AttrOptimizeBy Enum values on Enumeration Values for GSW_CM_AttrOptimizeBy.
GSW_CM_AttrOptimizeGoal	Int	Values from 0 - 100 percent, or from 0 to <as required> seconds, represent target values for the Optimization parameter.
GSW_CM_AttrGroupCampStatus	Int	See the Enum values for GSW_CM_AttrGroupCampStatus on page Enumeration Values for GSW_CM_AttrGroupCampStatus.
GSW_CM_AttrCampaignID	Int	Target Campaign DBID.
GSW_CM_AttrGroupID	Int	Target Group DBID.
GSW_CM_AttrError	Int	If no error, value is 0. See Enum values for GSW_CM_AttrError on Enumeration Values for GSW_CM_AttrError.
GSW_CM_AttrErrorMessage	String	String describing the error that occurred.
GSW_CM_AttrOriginAppID	Int	Application DBID.
GSW_CM_AttrTargetAppID	Int	Application DBID.
GSW_CM_AttrProperties	TKVList	Attribute’s properties.
GSW_AUTO_COMPLETION	Int	This attribute is used with CampaignLoad, SetDialingMode, and StartDialing events. A value of 1 indicates that OCS should stop the Campaign Group automatically, via Stop and Unload actions, after all records in a calling list are depleted. If the value is 0, the functionality is disabled. See Campaign Group Auto Completion for more information.

User Event Attribute for GSW_CM_AttrProperties (TKVList) shows UserEvent attributes for GSW_CM_AttrProperties (TKVList).
 

User Event Attribute for GSW_CM_AttrProperties (TKVList)

Key	Type	Description
campaign_schedule	TKVList	Contains information about a Campaign Sequence.
cancel_record	TKVList	Contains additional request attributes
dialing_priority	TKVList	Contains information about the dialing priority of specific record types.
do_not_call	TKVList	Contains additional request attributes

User Event Attributes for campaign_schedule (TKVList) shows UserEvent attributes for campaign_schedule (TKVList).
 

User Event Attributes for campaign_schedule (TKVList)

Key	Type	Description
Description	String	Description of Campaign Sequence
startTime	Int	Time to start the Sequence (UTC)
nItems	Int	Number of items in the Sequence
scheduleItem-<n>	TKVList	Properties of the Sequence item <n>

User Event Attributes for dialing_priority (TKVList) shows UserEvent attributes for dialing_priority (TKVList).
 

User Event Attributes for dialing_priority (TKVList)

Key	Type	Description
General	TKVList	Contains a list of the following key-value pairs: priority =<value> n_records=<value>
CampaignRescheduled	TKVList	Contains a list of the following key-value pairs: priority =<value> n_records=<value>
CampaignCallBack	TKVList	Contains a list of the following key-value pairs: priority =<value> n_records=<value>

User Event Attributes for scheduleItem-<n> shows the UserEvent attributes for scheduleItem-<n>.

User Event Attributes for scheduleItem-<n>

Key	Type	Description
stopAtTime	Int	Stop the campaign at a specified time.
stopAtContacts	Int	Stop the campaign when the predefined number of customers is contacted (number of transferred calls).
stopAtDials	Int	Stop the campaign when the specified number of dial attempts are made.
sleepBeforeNextStart	Int	The wait time, in minutes, before the start of this campaign/campaign group.
campaignDBID	Int	DBID of the campaign.
dialMode	Int	Dial mode for the campaign. See the Enum values for GSW_CM_AttrDialMode on Enumeration Values for GSW_CM_AttrDialMode.
optMethod	Int	Optimization method for the campaign. See the Enum values for GSW_CM_AttrOptimizeBy on Enumeration Values for GSW_CM_AttrOptimizeBy.
optMethodValue	Int	Values from 0-100 percent represent target value for the Optimization parameter.
status	Int	Status of the campaign. See the Enum values for GSW_CM_AttrGroupCampStatus on Enumeration Values for GSW_CM_AttrGroupCampStatus.

The Enumeration (Enum) values for the user event attributes in this chapter are listed in Data Enumeration Values for GSW_CM_MessageType based on their user data type.

Data Enumeration Values for GSW_CM_MessageType displays the Enumeration values for the user data GSW_CM_MessageType, separated by responses and requests, and it includes error messages.The table also indicates that some values are not applicable, which means that they are not used by the CommDN API in Outbound Contact.
 

Data Enumeration Values for GSW_CM_MessageType

Data	Value	Comment
Messages That OCM/Genesys Administrator Uses to Communicate with OCS
MSGCFG_NONE	0	not applicable
MSGCFG_UNKNOWN	1	not applicable
MSGCFG_ERROR	2	not applicable
MSGCFG_CLIENTREGISTER	3	not applicable
MSGCFG_DISCONNECTED	4	not applicable
CM_UnknownMessage	5	not applicable
Requests
CM_ReqRegisterClient	6	not applicable
CM_ReqLoadCampaign	7	Request to load a campaign.
CM_ReqUnloadCampaign	8	Request to unload a campaign.
CM_ReqStartDialing	9	Request to start dialing a campaign.
CM_ReqStopDialing	10	Request to stop dialing a campaign.
CM_ReqSetDialingMode	11	Request to change dialing parameters for a campaign.
CM_ReqGetCampaignStatus	12	Request for campaign status.
CM_ReqCampaignRegistered	13	not applicable
CM_ReqCampaignUnregistered	14	not applicable
CM_ReqForceUnloadCampaign	29	Request to force campaign unloading.
CM_ReqCancelRecord	30	Request to cancel record from third-party application
CM_ReqDoNotCall	32	Request to add phone number of customer ID to Do-Not-Call List.
Responses
CM_EvServerConnected	15	not applicable
CM_EvServerDisconnected	16	not applicable
CM_EvClientDisconnected	17	not applicable
CM_EvClientRegistered	18	not applicable
CM_EvCampaignLoaded	19	Acknowledge for request CM_ReqLoadCampaign.
CM_EvCampaignUnloaded	20	Acknowledge for request CM_ReqUnloadCampaign.
CM_EvDialingStarted	21	Acknowledge for request CM_ReqStartDialing.
CM_EvDialingStopped	22	Acknowledge for request CM_ReqStopDialing.
CM_EvDialingModeChanged	23	Acknowledge for request CM_ReqSetDialingMode
CM_EvCampaignStatus	24	Response or Notification when campaign mode is changed.
CM_EvCampaignRegistered	25	not applicable
CM_EvCampaignUnregistered	26	not applicable
CM_EvError	27	Wrong event error received.
GSW_CM_ReqCommDNGetCampaignData	28	not applicable
GSW_CM_ReqForceUnloadCampaign	29	Request to force the campaign to unload.
CM_EvRecordCanceled	31	Acknowledgement for request CM_ReqCancelRecord
CM_EvDoNotCallProcessed	33	Acknowledgement of request CM_ReqDoNotCall

Enumeration Values for GSW_CM_AttrError displays the Enumeration values for the user data GSW_CM_AttrError.
 

Enumeration Values for GSW_CM_AttrError

Error	Value	Comment
CM_ERROR_NO	0	not applicable
CM_ERROR_SERVER_CONNECTED	1	not applicable
CM_ERROR_REGISTER_CLIENT	2	not applicable
CM_ERROR_CAMPAIGN_NOT_FOUND	3	Requested campaign not found in configuration.
CM_ERROR_CAMPAIGN_NOT_LOADED	4	Requested campaign not loaded.
CM_ERROR_CAMPAIGN_ALREADY_LOADED	5	Requested campaign already loaded.
CM_ERROR_CAMPAIGN_NOT_STARTED	6	Request to change runtime parameters for a campaign that has not started.
CM_ERROR_CAMPAIGN_ALREADY_STARTED	7	Request to start an already started campaign/campaign group.
CM_ERROR_GROUP_NOT_FOUND	8	Requested group not found in configuration.
CM_ERROR_GROUP_CAMP_NOT_FOUND	9	Requested campaign is not configured for the requested group.
CM_ERROR_INVALID_PARAMETER	10	Invalid parameter in the CM_ReqSetDialingMode request.
CM_ERROR_INVALID_CAMPAIGN_MODE	11	Invalid mode is requested for running campaign.
CM_ERROR_INVALID_CAMPAIGN_SCHEDULE	12	Wrong Campaign Sequence is received.
CM_ERROR_CAMPAIGN_SCHEDULE_NOT_FOUND	13	Campaign Sequence is not found among loaded or running Sequences.
CM_ERROR_INVALID_CAMPAIGN_SCHEDULE_MODE	14	Invalid mode is requested for running Campaign Sequence.
CM_ERROR_LICENSE_VIOLATION	15	Dial mode is not supported by current license.

Enumeration Values for GSW_CM_AttrDialMode shows the Enumeration values for the user data GSW_CM_AttrDialMode.
 

Enumeration Values for GSW_CM_AttrDialMode

Enumeration	Value	Comment
CFGDMPredict	1	Predictive mode
CFGDMProgress	2	Progressive mode
CFGDMPreview	3	Preview mode
CFGDMProgressAndSeize	4	Progressive with engage mode
CFGDMPredictAndSeize	5	Predictive with engage mode
CFGDMPushPreview	8	Push Preview
CFGDMProgressGVP	9	Progressive GVP
CFGDMPowerGVP	11	Power GVP

Enumeration Values for GSW_CM_AttrOptimizeBy shows the Enumeration values for the user data GSW_CM_AttrOptimizeBy.
 

Enumeration Values for GSW_CM_AttrOptimizeBy

Enumeration	Value	Comment
CFGOMBusyFactor	1	Optimize busy factor
CFGOMOverdialRate	2	Optimize overdial rate
CFGOMWaitTime	3	Optimize wait time

Enumeration Values for GSW_CM_AttrGroupCampStatus shows the Enumeration values for the user data GSW_CM_AttrGroupCampStatus.
 

Enumeration Values for GSW_CM_AttrGroupCampStatus

Enumeration	Value	Comment
CM_GCS_NotLoaded	0	Status not loaded
CM_GCS_WaitingUnload	1	Status waiting unload
CM_GCS_UnloadInProgress	2	Status unload in progress
CM_GCS_InActive	3	Status inactive
CM_GCS_Active	4	Status active
CM_GCS_Running	5	Status running

Record Cancellation from a Third-Party Application

From a third-party application, agents who are not participating in a particular Outbound campaign may cancel a record by phone number (and optionally, by customer ID) in that campaign.

An extended Communication DN Protocol for OCS gives end users this additional control over campaigns.

A custom, third-party application needs access to a Genesys T-Server and Configuration Server, both of which have an open API. Communication is conducted by the means of UserEvents sent and received on a Communication DN. T-Server conveys UserData attached to an event. The data are encoded in the key-value pairs list (TKVList).

OCS communicates with third-party applications by means of request-response.

• Request: CM_ReqCancelRecord
  
• Response: CM_EvRecordCanceled
  

The mandatory attributes are Phone, OriginAppDBID, and TargetAppDBID:

• The OriginAppDBID attribute is the DBID of the sender. If, in the request, the OriginAppDBID attribute pertains to the third-party application, this application should be configured according to the common Communication DN protocol policy.
  
• TheTargetAppDBID attribute is the DBID of the receiver. Note that for CM_ReqCancelRecord, the value of TargetAppDBID may be 0, which signifies that all OCS servers monitoring the communication DN will process this request and submit a response.
  

UserEvent Structure

The following depicts the event structure for the T-Server events pertaining to the cancellation of calling records from a third-party application:

UserEvent

I UserData

I "GSW_CM_MessageType" 30

["GSW_CM_AttrError" 0]

"GSW_CM_AttrOriginAppID" <value>

"GSW_CM_AttrTargetAppID" <value>

"GSW_CM_AttrProperties"

I

"cancel_record"

I

"GSW_PHONE" <value>

["GSW_CAMPAIGN_NAME" <value>]

["GSW_CHAIN_ATTR" <value>]

["GSW_MESSAGE" Incomplete processing: record(s) on desktop]

Note:

The user event might also include GSW_CUSTOMER_ID (an optional attribute) that you can add to a third-party cancellation request.

The values can be of two types: String or Integer.

See User Event Attributes for User Data (TKVList) and Reserved Keys.

UserEvent Attributes

The UserEvent attributes in UserData (TKVList) pertain to the Record Cancel feature. GSW_CM_AttrProperties (TKVList) and cancel_record (TKVList) provide information on GSW_CM_AttrProperties and cancel_record. Also see User Event Attributes for User Data (TKVList).
 

UserData (TKVList)

Key	Type	Description
GSW_CM_MessageType	Integer	See GSW_CM_MessageType Enum below.
GSW_CM_AttrError	Integer	0 if no error. See GSW_CM_AttrError Enum below.
GSW_CM_AttrOriginAppID	Integer	Sender's DBID
GSW_CM_AttrTargetAppID	Integer	Receiver's DBID
GSW_CM_AttrProperties	TKVList	See GSW_CM_MessageType Enum below.

 

GSW_CM_AttrProperties (TKVList)

Key	Type	Description
cancel_record	TKVList	Contains additional request attributes

cancel_record (TKVList)

Key	Type	Description
GSW_PHONE	String	Phone Number
GSW_CAMPAIGN_NAME	String	Campaign Name If specified, only records in this campaign will be canceled.
GSW_CHAIN_ATTR	String	AllChain, RecordOnly Specifies the scope of the request. AllChain is the default value
GSW_CUSTOMER_ID	String	(Optional) A user-defined field in the Calling List table that serves as a customer identifier.
GSW_MESSAGE	String	OCS message (“Incomplete processing: record(s) on desktop") notifying the RequestRecordCancel requester (agent desktop or third-party) about OCS’s inability to completely handle the cancellation request, because calls records are still active on an agent’s desktop. Note: This only affects cancellation by phone and customer ID. It does not affect RequestRecordCancel request made by the record handle or DoNotCall requests.

Data Enums

GSW_CM_MessageType

These data enumerations apply to the GSW_CM_MessageType for the Record Cancel feature. Data Enumerations and GSW_CM_AttrError Errors provide information on data enumerations and GSW_CMAttrError respectively. In addition, see Data Enumeration Values for GSW_CM_MessageType.
 

Data Enumerations

Message	Value	Description
Requests
CM_ReqCancelRecord	30	Request to cancel records by phone.
Responses
CM_EvRecordCanceled	31	Acknowledgement for request CM_ReqCancelRecord
CMEvError	27	An error occurred. See error codes below.

 

GSW_CM_AttrError Errors

Error	Value Type	Description
CM_ERROR_CAMPAIGN_NOT_FOUND	3	Campaign was not loaded.
CM_ERROR_INVALID_PARAMETER	10	Some parameters are invalid.

DoNotCall Requests from a Third-Party Application

DoNotCall (DNC) requests restrict the dialing of particular phone numbers or to particular customers. A field in the Calling List table, as specified by the value of the customer_id option, serves as the customer ID.

On startup, OCS reads all the records from the table referenced in the gsw_donotcall_list Table Access Point and populates separate tables in memory with the unique values from the phone and customer_id fields. DoNotCall requests from the desktop can also populate those tables.

Outbound Contact supports the submission of DNC requests from third-party applications, for example, from the desktop application of an agent handling inbound calls. OCS enables this functionality through an extension of the CommDN API. Recall that to use the API, a custom application must have access to a Genesys T-Server and Configuration Server, both of which have an open API.

The communication is performed by means of UserEvents sent and received on a Communication DN. All the data is sent as UserData attached to the event. The data is encoded in a key-value pairs list (TKVList). The values can be of two types: string or integer.

The communication between OCS and third-party applications is facilitated by a request-response system.

DNC Messages

The communication by means of T-Server events is based on request-response. They are as follows:

• Request: CM_ReqDoNotCall

Request to add a phone number or customer ID to DoNotCall (DNC) list.

• Response: CM_EvDoNotCallProcessed

Acknowledgement of requestCM_ReqDoNotCall

• Error message: CM_EvError

Error message sent if the request has incorrect user data.

Mandatory Attributes

The mandatory attributes of DNC messages include:

• Phone or CustomerID
• OriginAppDBID
• TargetAppDBID:

For CM_ReqDoNotCall, the value of TargetAppDBID may be 0, which signifies that all the OCS servers monitoring the communication DN will process this request and submit a response.

UserEvent Structure

The following depicts the event structure for T-Server to convey a DNC request (CM_ReqDoNotCall) from a third-party application:

UserEvent

I

UserData

I

"GSW_CM_MessageType" 32

["GSW_CM_AttrError" 0]

"GSW_CM_AttrOriginAppID" <value=sender’s ID>

"GSW_CM_AttrTargetAppID" <value=receiver’s ID>

"GSW_CM_AttrProperties"

I

"do_not_call"

I

"GSW_PHONE" <value>

["GSW_CUSTOMER_ID" <value>]

["GSW_CHAIN_ATTR" <value>]

In this example, under UserData, the value of GSW_CM_MessageType is 32 for the request CM_ReqDoNotCall. The value would be33 for the response/notification CM_EvDoNotCallProcessed or 27 for the error message CM_EvError, and “do_not_call" under GSW_CM_AttrProperties would be replaced accordingly by the proper message types.

Note:

The GSW_CUSTOMER_ID attribute identifies the customer. The value of GSW_CUSTOMER_ID is a field in the Calling List table as specified by the option customer_id. At least one of these attributes — GSW_CUSTOMER_ID or GSW_PHONE — must be present.