Jump to: navigation, search

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.

This page was last edited on November 8, 2021, at 23:22.
Comments or questions about this documentation? Contact us for support!