Event Interfaces and Events

Event Interfaces and Events

This chapter describes the CTI OS Client Interface Library event publications mechanism. Programs written to take advantage of CTI interfaces are generally event driven, meaning that a code module in the application is run when an external event arrives. The CIL interface provides a rich set of event interfaces and events for use by client programmers.

Events are generated asynchronously, either by the telephony equipment (for example, phone, PBX, and ACD) or by the CTI environment (CTI Server, or CTI OS Server). Each event passes an Arguments structure of key-value pairs that contains all of the event parameters. These parameters are discussed in greater detail in this chapter.

Event Publication Model


Note


The CIL event interfaces discussed in this section and the following sections apply only to the C++, COM, and VB interfaces. For more information about a discussion of Java CIL counterpart events and event handling in the Java CIL, see Events in Java CIL. For more information about a discussion of .NET CIL event handling, see Events in .NET CIL.


The Client Interface Library provides a publisher-subscriber model for notifying clients of events. Client applications using the CIL can subscribe to one or more of the CIL event interfaces. For more information and examples on how to subscribe and unsubscribe for events, see Building Your Custom CTI Application

The published CIL event interfaces are organized around the different classes of CTI objects that the CIL provides. The event interfaces described in this chapter are:

  • ISessionEvents. This interface publishes the events that relate to actions on the Session object.

  • ICallEvents. This interface publishes the events that relate to actions on Call objects.

  • IAgentEvents. This interface publishes the events that relate to actions on Agent objects.

  • ISkillGroupEvents. This interface publishes the events that relate to actions on SkillGroup objects.

  • IButtonEnablementEvents. This interface publishes the events that relate to changes in the enable-disable status of softphone buttons.

  • ISilentMonitorEvents. This interface sends events to subscribers of the Silent Monitor interface.

  • IMonitoredAgentEventsInterface. This interface fires Agent events to a supervisor for his team members.

  • IMonitoredCallEventsInterface. This interface sends Call events to a supervisor for one of his agent team members.

  • LogEventsAdapter (Java only). This class provides the default implementation for the message handlers in ILogEvents.

  • IGenericEvents. This interface sends generic events to subscribers of the IGenericEvents interface.

The remainder of this chapter provides the detailed description of each event interface available from the CIL.


Note


The data type listed for each keyword is the standardized data type discussed in the section CTI OS CIL Data Types in CIL Coding Conventions For more information about the appropriate language specific types for these keywords, see Table 1.


ISessionEvents Interface

The Session object fires events on the ISessionEvents interface. The following events are published to subscribers of the ISessionEvents interface.

OnConnection

The OnConnection event is generated after the Connect method succeeds. It returns the name of the connected server and the connection time of day. The client application need not take any special action but can use it to display connection status.

Syntax


C++: void OnConnection(Arguments& args)
COM: void OnConnection (IArguments * args)
VB:  session_OnConnection (ByVal args As CtiosCLIENTLib.IArguments)

Parameters

args

Arguments array containing the following fields.

Table 1. ISession Event Parameters

Keyword

Type

Description

EventTime

INT

Integer value with time of day expressed in milliseconds.

CurrentServer

STRING

Name or TCP/IP address of the current connected CTI OS server.

OnConnectionClosed

The OnConnectionClosed message is generated when a connection is terminated by the client. This message has no fields. This event indicates successful completion of an action that the client (CIL or application using the CIL) initiated. By contrast, the OnConnectionFailure event is generated when the connection terminated for reasons other than that the client closed the connection.

OnConnectionFailure

The OnConnectionFailure event is generated when an established connection fails. It returns the name of the failed connected server and the failure time of day. Retry is automatic and is followed by an OnConnection event when connection is successfully reestablished. The client application need not take any special action but can use this event to display connection status.

Syntax

C++
void OnConnectionFailure(Arguments& args)
COM
void OnConnectionFailure (IArguments * args)
VB
session_OnConnectionFailure (ByVal args As CtiosCLIENTLib.IArguments)

Parameters

args

Arguments array containing the following fields.

Table 2. OnConnectionFailure Event Parameters

Keyword

Type

Description

EventTime

INT

Integer value with time of day expressed in milliseconds.

FailedServer

STRING

Name or TCP/IP address of the server that failed to respond. See ReasonCode.

ReasonCode

SHORT

Reason code 0 : eProtocolMismatch

Reason code 1 : eMissedHeartbeats

Reason code 2 : eTransportError

Reason code 3 : eConnectFail

Reason code 4 : eOtherError

OnConnectionRejected

The OnConnectionRejected event indicates that the client tried to make a connection using incompatible versions of the CTI OS Server and CTI OS CIL.

Syntax


C++:  void OnConnectionRejected (Arguments& args)
COM:  void OnConnectionRejected (IArguments * args)
VB:   Session_OnConnectionRejected (ByVal args As CtiosCLIENTLib.IArguments)

Parameters

args

Not currently used, reserved for future use.

OnCTIOSFailure

The OnCTIOSFailure event indicates that the CTI Server fired either a FailureConf or a SystemEvent.


Note


CTI OS CIL sends the disconnect request to CTI OS Server when the login attempt fails. Hence, CTI OS Server closes the client connection.


Syntax


C++:  void OnCTIOSFailure (Arguments& args)
COM:  void OnCTIOSFailure (IArguments * args)
VB:   Session_OnCTIOSFailure (ByVal args As CtiosCLIENTLib.IArguments)

Parameters

args

Arguments array containing the following fields.

Table 3. OnCTIOSFailure Event Parameters

Keyword

Type

Description

FailureCode

INT

A value according to an enumerated value, as shown immediately following this table.

SystemEventID

INT

Present only if FailureCode equals ServerConnectionStatus. Contains a value according to an enumerated value, as shown immediately following this table.

SystemEventArg1

INT

Present only if SystemEventID equals SysPeripheralOnline or SysPeripheralOffline. Contains the peripheral ID of the affected peripheral.

ErrorMessage

STRING

An error message.

Following are the enumerated values for FailureCode:

enum enumCTIOS_FailureCode
{
eDriverOutOfService = 1,
eServiceNotSupported = eDriverOutOfService + 1,
eOperationNotSupported = eServiceNotSupported + 1,
eInvalidPriviledge = eOperationNotSupported + 1,
eUnknownRequestID = eInvalidPriviledge + 1,
eUnknownEventID = eUnknownRequestID + 1,
eUnknownObjectID = eUnknownEventID + 1,
eRequiredArgMissing = eUnknownObjectID + 1,
eInvalidObjectState = eRequiredArgMissing + 1,
eServerConnectionStatus = eInvalidObjectState + 1,
eInconsistentAgentData = eServerConnectionStatus + 1,
eAgentAlreadyLoggedIn = eInconsistentAgentData + 1,
eForcedNotReadyForConfigError = eAgentAlreadyLoggedIn + 1
eMonitorModeConnectionDenied = eForcedNotReadyForConfigError + 1
};

Following are the enumerated values for SystemEventID:

enum enumCTIOS_SystemEventID
{ eSysCentralControllerOnline = 1,
eSysCentralControllerOffline = 2,
eSysPeripheralOnline = 3,
eSysPeripheralOffline = 4,
eSysTextFYI = 5,
eSysPeripheralGatewayOffline = 6,
eSysCtiServerOffline = 7,
eSysCTIOSServerOnline = 8,
eSysHalfHourChange = 9,
eSysInstrumentOutOfService = 10,
eSysInstrumentBackInService = 11,
eSysCtiServerDriverOnline = eSysInstrumentBackInService + 1,
eSysCtiServerDriverOffline = eSysCtiServerDriveOnline + 1,
eSysCTIOSServerOffline = eSysCtiServerDriverOffline + 1,
eSysCTIOSServerOnline = eSysCTIOSServerOffline + 1,
eSysAgentSummaryStatusOnline = eSysCTIOSServerOnline + 1,
eSysAgentSummaryStatusOffline = eSysAgentSummaryStatusOnline + 1
}

Remarks

See the descriptions of the CtiOs_Enums.FailureCode and CtiOs_Enums.SystemEvent interfaces in the Javadoc for information on Java CIL enumerations.

OnCurrentAgentReset

The OnCurrentAgentReset message is generated when the current agent is removed from the session.

Syntax

C++
void OnCurrentAgentReset(Arguments& args)
COM
void OnCurrentAgentReset (IArguments * args)
VB
session_OnCurrentAgentReset (ByVal args As CtiosCLIENTLib.IArguments)

Parameters

args

Arguments array containing the following fields.

Table 4. OnCurrentAgentReset Parameters

Keyword

Type

Description

UniqueObjectID

STRING

Unique object ID (if any) of the old current agent that was just removed.

OnCurrentCallChanged

The OnCurrentCallChanged message is generated when the current call changes to another call.

Syntax

C++
void OnCurrentCallChanged(Arguments& args)
COM
void OnCurrentCallChanged (IArguments * args)
VB
session_OnCurrentCallChanged (ByVal args As CtiosCLIENTLib.IArguments)

Parameters

args

Arguments array containing the following fields.

Table 5. OnCurrentCallChanged Parameters
Keyword Type Description

UniqueObjectID

STRING

Unique object ID (if any) of the new current call.

OnFailure Event

Not supported.

OnGlobalSettingsDownloadConf

You can configure the client after you are in the CTI OS Server and then download this configuration to each CTI OS client desktop. When an application runs the RequestDesktopSettings method call on the Session, an eGlobalSettingsDownloadRequest event is sent to the server.

In response, the server sends an OnGlobalSettingsDownloadConf event back to the calling application. The Arguments object passed as a parameter in this event contains the Desktop Settings configuration information. The Arguments object is an array that can contain up to seven elements, each of which has the value of a nested Arguments array in a hierarchy that closely matches that of the CTI OS server configuration in the Windows registry.

Each of these Arguments arrays is a packed version of the configuration contained in the CTI OS Server. For more information, see CTI OS System Manager Guide for Cisco Unified ICM.

This section describes the contents of the Arguments array returned in the OnGlobalSettingsDownloadConf event. Custom applications can add values at the lowest level under each key. Custom values added in this way are passed to the client in this event. This section also identifies which keys and values in the CTI OS registry are passed to the client in this event.

For more information about what is available and how to configure these items, see the following sections in the CTI OS System Manager Guide for Cisco Unified ICM:

  • MainScreen

  • Defining Connection Profiles

  • Declaring ECC Variables

  • Configuring the Call Appearance Grid

  • Automatic Agent Statistics Grid Configuration

  • Automatic Skill Group Statistics Grid Configuration

Syntax

C++
void OnGlobalSettingsDownloadConf(Arguments & args)
COM
void OnGlobalSettingsDownloadConf(IArguments * args)
VB
session_OnGlobalSettingsDownloadConf(ByVal args As CtiosCLIENTLib.IArguments)

Parameters

args

An Arguments array containing the Enterprise Desktop Settings configuration from a CTI OS server. For more information about the Enterprise Desktop Settings values listed below, see the CTI OS System Manager Guide for Cisco Unified ICM.

The following are the top level elements in the Enterprise Desktop Settings registry key. The CTI OS server passes configuration data for these elements to the client in the OnGlobalSettingsConf event:
  • ECC (Expanded Call Context) variables

  • Grid

  • IPCCSilentMonitor

  • Login

  • ScreenPreferences

  • SoundPreferences

Other keys or values that are added to the EnterpriseDesktopSettings/All Desktops key in the CTI OS server registry are passed to the client in the DesktopSettings Arguments array as empty Arguments arrays.

The following sections describe the contents of the args array:

  • ECC – Arguments array that contains the Expanded Call Context (ECC) variables declared on the CTI OS server in the "ECC/Name" registry subtree (the following figure).

    The CTI OS server does not send any registry information contained in the CTI OS registry keys representing the ECC scalar and array names. Thus the ECC Arguments arrays are empty in the OnGlobalSettingsDownloadConf event, regardless of the contents of those keys.

    Figure 1. ECC Arguments Array

    ECC arguments array

    Each ECC scalar configured in the CTI OS server registry is represented as an empty Arguments array with keyword "user.<name>", where <name> is the ECC name as configured on CTI OS server.

    Each ECC array configured in the CTI OS server registry is represented as multiple empty Arguments arrays with keywords "user.<name>[0]" to "user.<name>[n-1]", where <name> is the ECC name as configured on the CTI OS server and n is the size of the array as configured on the CTI OS server.

  • Grid – Arguments array contains information from the CTI OS server registry's Grid subtree. The grid element contains an Arguments array of up to three Arguments arrays:
    • AgentStatistics

    • CallAppearance

    • SkillGroupStatistics

    Each of these arrays contains the keyword "columns," an Arguments array that contains multiple nested Arguments arrays with key=<column_number>, where <column_number> corresponds to the name of a key within the Columns/Number registry subtree.

    The configuration information for any key or value added to the SkillGroupStatistics, AgentStatistics, or CallAppearance registry keys is not passed to the client in the OnGlobalSettingsDownloadConf event.

    The value for each column number in the AgentStatistics and SkillGroupStatistics element is an Arguments array containing the following key-value pairs:

    Table 6. Agent Statistics Column Number: Key Values

    Keyword

    Data Type

    Type

    string

    Header

    string

    Custom values1

    custom

    1 Other registry values added to the <column_number> registry key are passed in the OnGlobalSettingsDownloadConf event. Subkeys added to the <column_number> registry key are not passed in this event.

    The value for each column number in the CallAppearance element is an Arguments array containing the following key-value pairs:

    Table 7. CallAppearance Column Number: Key Values

    Keyword

    Data Type

    Type

    string

    Header

    string

    editable

    boolean

    maxchars

    integer

    Custom values2

    custom

    2 Other registry values added to the <column_number> registry key are passed in the OnGlobalSettingsDownloadConf event. Subkeys added to the <column_number> registry key are not passed in this event.

    You can add custom keys in the CTI OS Server registry's Grid subtree at the same level as the SkillGroupStatistics, AgentStatistics, and CallAppearance keys. The Grid Arguments array (see the following figure) within this event contain items corresponding to these custom keys. Any custom element that you add must follow the same hierarchy in the registry as that used by the existing top level elements.

    The custom element hierarchy format is as follows:

    Figure 2. Grid Arguments Array

    Grid arguments array
  • IPCCSilentMonitor – Arguments array that contains configuration information from the CTI OS server registry's IPCCSilentMonitor/ Name subtree.

    The IPCCSilentMonitor Arguments array contains a nested Arguments array with key="settings." This array contains the following key-value pairs:

    Table 8. IPCCSilentMonitor: Key Values

    Keyword

    Value

    MediaTerminationPort

    integer

    HeartBeatInterval

    integer

    TOS

    boolean

    MonitoringIPPort

    integer

    HeartbeatTimeout

    integer

    CCMBasedSilentMonitor

    boolean

    Configuration information for registry values added to the IPCCSilentMonitor/Settings registry key is passed to the client in the OnGlobalSettingsConf event. Configuration information for subkeys added to the Settings registry key is not passed in this event.

    You can add custom keys to the CTI OS registry in the IPCCSilentMonitor subtree at the same level as the Settings key. The IPCCSilentMonitor Arguments array within this event contain items corresponding to these custom keys. Any custom element that you add must follow the same hierarchy in the registry as that used by the existing top level elements.

    Two silent monitoring types are supported for Unified CCE:
    • CTI OS based

    • CCM based

    You configure the silent Monitor type used by CTI OS using the CCMBasedSilentMonitor registry key.

    If CCMBasedSilentMonitor is present and set to true, CTI OS is using Call Manager's silent monitor implementation. When this is the case, supervisor applications must initiate silent monitor using the Agent.SuperviseCall() method. Agent applications do not need to do anything. If CCMBasedSilentMonitor is not present or set to 0, CTI OS implementation of silent monitor is in use. When this is the case, supervisor and agent applications must invoke silent monitor using the SilentMonitorManager object.

    The format of the IPCCSilentMonitor Arguments array is shown in the following figure.

    Figure 3. IPCCSilentMonitor Arguments Array

    IPCCSilentMonitor Arguments Array
  • Login – Arguments array that contains the information from the CTI OS server registry's Login subtree. This array contains a nested Arguments array with key="ConnectionProfiles" and with an Arguments array value for each connection profile. The keyword of each array is the name for the Connection Profile listed in the CTI OS server's registry. The value is another Arguments array.

    The following key-value pairs are contained in each connection profile Arguments array:

    Table 9. Unified CCE Agent Statistics: Key Values

    Keyword

    Value

    CtiOsA

    string

    CtiOsB

    string

    PortA

    integer

    PortB

    integer

    Heartbeat

    integer

    MaxHeartbeats

    integer

    AutoLogin

    boolean

    WarnIfAlreadyLoggedIn

    boolean

    ShowFieldBitMask

    integer

    RejectIfAlreadyLoggedIn

    boolean

    PeripheralID

    integer

    IPCCSilentMonitorEnabled

    boolean

    TOS

    boolean

    SwitchCapabilityBitMask

    integer

    WarnIfSilentMonitored

    boolean

    RasCallMode3

    integer

    3

    Applicable only to RAS enabled Unified CCE Profiles

    Configuration information for keys or values that are added to the Login registry key in the CTI OS server's registry does not appear in the Login Arguments array.

    The format of the Login Arguments array is shown in the following figure.

    Figure 4. Login Arguments Array

    Login arguments array

    SilentMonitorService Subkey

    The <profile_name>/SilentMonitorService subkey contains parameters that clients use to connect to one of a set of silent monitor services. It contains the following keys:


    Note


    The SilentMonitorService subkey is only applicable to CTI OS based silent monitor.


    Table 10. SilentMonitorService Parameters

    Keyword

    Value

    Description

    ListenPort

    integer

    Port on which the silent monitor service is listening for incoming connections.

    TOS

    integer

    QOS setting for the connection.

    HeartbeatInterval

    integer

    Amount of time in milliseconds between heartbeats.

    HeartbeatRetries

    integer

    Number of missed heartbeats before the connection is abandoned.

    Cluster

    A key that contains a list of silent monitor services to which the CIL tries to connect. The CIL randomly chooses one of the services in this list. This key contains two subkeys:

    • 1 - index of the first silent monitor service
    • N - index of the Nth silent monitor service

    All subkeys contain the following keyword:

    • SilentMonitorService - host name or IP adress of the silent monitor service.

    The following figure illustrates the hierarchy of the SilentMonitorService subkey.

    Figure 5. SilentMonitorService Subkey Hierarchy

    SilentMonitorService subkey hierarchy
  • ScreenPreferences – Arguments array that contains the information configured in the CTI OS server registry's ScreenPreferences/Name subtree. The ScreenPreferences array contains an element MainScreen, which is an Arguments array that contains the following key-value pairs:

    Table 11. ScreenPreferences: Key Values

    Keyword

    Value

    AgentStatisticsIntervalSec

    integer

    BringToFrontOnCall

    boolean

    FlashOnCall

    boolean

    RecordingEnabled

    boolean

    You can add custom keys to the CTI OS registry in the ScreenPreferences subtree at the same level as the "MainScreen" key. The ScreenPreferences Arguments array within this event contains items corresponding to these custom keys. Any custom key that you add must follow the same hierarchy in the registry as that used by the existing top level keys.

    Registry values added to the MainScreen registry key on the CTI OS server are passed to the client in the OnGlobalSettingsDownloadConf event. Subkeys added to the MainScreen registry key are not passed in this event.

    The format of the ScreenPreferences Arguments array is shown in the following figure.

    Figure 6. ScreenPreferences Arguments Array

    Screenpreferences arguments array
  • SoundPreferences – Arguments array that contains information configured on the CTI OS server in the SoundPreferences/Name subtree. This array includes a nested Arguments array that includes a setting for each sound, including .wav files to be played, and whether or not each one is mute. It can also include custom name/value pairs for a custom application.

    The SoundPreferences array contains the following key-value pairs:

    Table 12. SoundPreferences: Key Values

    Keyword

    Value

    Subtree

    DTMF*

    Arguments array

    SoundPreferences/Name/DTMF

    DialTone*

    Arguments array

    SoundPreferences/Name/DialTone

    OriginatingTone*

    Arguments array

    SoundPreferences/Name/OriginatingTone

    RingInTone*

    Arguments array

    SoundPreferences/Name/RingInTone

    All*

    Arguments array

    SoundPreferences/Name/All

    * Registry values added to this registry key in the CTI OS server registry are included in the Arguments array. Subkeys added to this registry key are not present.

    The DTMF, DialTone, OriginatingTone, RingInTone, and All arrays each contain the keyword Mute, which has a boolean value. Custom registry values added to the DialTone DTMF, DialTone, OriginatingTone, RingInTone, and All registry keys are present in the array. Subkeys added to the these registry keys are not present in the array.

    You can add custom keys in the SoundPreferences subtree at the same level as the All, DTMF, DialTone, OriginatingTone, and RingInTone keys. The SoundPreferences array contains items corresponding to these custom keys. Any custom element that you add must follow the same hierarchy in the registry as that used by the existing top level elements.

    The format of the SoundPreferences Arguments array is shown in the following figure.

    Figure 7. SoundPreferences Arguments Array

    Soundpreferences arguments array

    This configuration is stored in the Windows System Registry database and many of the values are set when the CTI OS Server Setup is run. You can set custom configuration at a later time by using the Windows Registry Editor.

OnHeartbeat

The OnHeartbeat event is generated when a heartbeat response is received from a CTI OS server. It returns the time of day.

Syntax

C++
void OnHeartbeat(Arguments& args)
COM
void Onheartbeat (IArguments * args)
VB
session_OnHeartbeat (ByVal args As CtiosCLIENTLib.IArguments)

Parameters

args

Arguments array containing the following fields.

Table 13.
Keyword Type Description

EventTime

INT

Integer value with time of day expressed in milliseconds.

OnMissingHeartbeat

The OnMissingHeartbeat event is generated when an expected heartbeat is not received. It returns the number of consecutive heartbeats missed and time of day. When the number of heartbeats missed equals or exceeds the maximum number of heartbeats allowed (set in the MaxHeartbeats property), an OnConnectionFailure event is generated instead of an OnMissingHeartbeat event, and the CIL automatically attempts to reconnect to the CTI OS server, alternating between the CtiosA and CtiosB servers passed as parameters in the Connect method.

Syntax

C++
void OnMissingHeartbeat(Arguments& args)
COM
void OnMissingHeartbeat (IArguments * args)
VB
session_OnMissingHeartbeat (ByVal args As CtiosCLIENTLib.IArguments)

Parameters

args

Arguments array containing the following fields.

Table 14. OnMissingHeartbeat Parameters

Keyword

Type

Description

EventTime

INT

Integer value with time of day expressed in milliseconds.

Consecutive MissedHeartbeats

INT

Integer value with the number of heartbeats missed.

HeartbeatInterval

INT

Integer value with the heartbeat interval, in milliseconds.

OnMonitorModeEstablished

The OnMonitorModeEstablished event is generated when Monitor Mode is established.

Syntax

C++
void OnMonitorModeEstablished(Arguments& args)
COM
void OnMonitorModeEstablished (IArguments * args)
VB
session_OnMonitorModeEstablished (ByVal args As CtiosCLIENTLib.IArguments)

Parameters

args

Arguments array containing the following fields.

Table 15. OnMonitorModeEstablished Parameters

Keyword

Type

Description

CIL ConnectionID

STRING

ID of the client connection on the server.

StatusSystem

ARGUMENTS

Arguments array containing the following elements:

  • StatusCTIServer
  • StatusCtiServerDriver
  • StatusCentralController
  • StatusPeripherals (Arguments array with a peripheral ID for each key and a boolean true/false value indicating if that peripheral is online.)

OnSnapshotDeviceConf

The OnSnapshotDeviceConf confirmation message is fired to the client as part of a snapshot operation. For AgentMode clients, the OnSnapshotDeviceConf arrives at startup time, after the OnQueryAgentStateConf message. The OnSnapshotDeviceConf indicates the number of calls present at the device, and their UniqueObjectIDs.

Syntax

C++
void OnSnapshotDeviceConf (Arguments & args);
COM
HRESULT OnSnapshotDeviceConf ([in] IArguments * args);
VB
OnSnapshotDeviceConf (ByVal args as CTIOSCLIENTLIB.IArguments)

Parameters

args

Arguments array containing the following fields.

Table 16. OnSnapshotDeviceConf Parameters

Keyword

Description

Type

UniqueObjectID

Unique ID of the device object on the server. There are no device objects in the CIL, so this keyword cannot be used to retrieve a device object at this point.

STRING

NumCalls

The number of active calls associated with this device, up to a maximum of 16.

SHORT

ValidCalls

An Arguments array containing the list of calls on the device. The Unique ObjectID of each call is a key in the Arguments object. The value is a boolean indicating if the call is valid. Calls not listed are not valid calls on the device.

ARGUMENTS

Remarks

The CIL uses this event to rectify the list of calls on a device when logging in after a failover, in case the status of calls on the device changes during the failure period. An example of such a scenario is an agent talking on a call on a hardphone and a CTI failure occurs. The agent hangs up the call before CTI is recovered. After CTI and the CIL recover, they use the snapshot to discover that the call it currently has is no longer on the device. CTI then fires an EndCall event to remove the call from its call list.

OnSnapshotSkillGroupList

Not supported.

OnTranslationRoute

The OnTranslationRoute event is a pre-call indication. The event indicates the pending arrival of a call, and provides early access to the call context information. From a call flow perspective, this event can be used to begin an application or database lookup for the call context data before the call actually arrives at the agent's teleset.

The contact is uniquely identified by the ICMEnterpriseUniqueID, which is a field based on the Unified ICM 64-bit unique key (RouterCallKeyDay and RouterCallKeyCallID). This event does not indicate the creation of a Call object on the CTI OS server—only that the contact is being tracked. This is sufficient to get and set data, which enables some powerful data-prefetching applications. When a OnCallBeginEvent follows for this same contact, the ICMEnterpriseUniqueID field is sent with the call data. At that point, a custom application can set the call data on the appropriate call object.

Syntax

C++
void OnTranslationRoute(Arguments& args)
COM
oid OnTranslationRoute(IArguments * args)
VB
session_OnTranslationRoute(ByVal args As CtiosCLIENTLib.IArguments)

Parameters

args

Arguments array containing the following fields.
Table 17. OnTranslationRoute Parameters

Keyword

Type

Description

ICMEnterpriseUniqueID

STRING

This string is a globally unique key for this contact, which corresponds to the Unified ICM 64 bit key. You can use this parameter to match this contact to a follow-on call event.

RouterCallKeyDay

INT

Together with the RouterCallKeyCallID field forms the unique 64-bit key for locating this call's records in the Unified ICM database. Only provided for Post-routed and Translation-routed calls.

RouterCalKeyCallID

INT

The call key created by the Unified ICM . The Unified ICM resets this counter at midnight.

RouterCallKey SequenceNumber

INT

Together with RouterCallKeyDay and RouterCallKeyCallID fields forms the TaskID.

NumNamedVariables

SHORT

Number of Named variables.

NumNamedArrays

SHORT

Number of Named Arrays.

ANI

STRING

The calling line ID of the caller.

UserToUserInfo

STRING

The ISDN user-to-user information element.

DNIS

STRING

The DNIS number to which this call will arrive on the ACD/PBX.

DialedNumber

STRING

The number dialed.

CallerEnteredDigits

STRING

The digits entered by the caller in response to VRU prompting.

CallVariable1

STRING

Call-related variable data.

...

STRING

...

CallVariable10

STRING

Call-related variable data.

ECC

ARGUMENTS

A nested Arguments structure of key-value pairs for all of the ECC data arriving with this call.

ICallEvents Interface

The Call object fires events on the ICallEvents interface. The following events are published to subscribers of the ICallEvents interface.


Note


Many of the parameters that CTI OS receives from the CTI Server are inconsequential to most customer applications. The most important parameters for doing a screenpop are included with the events described in this section. The more inconsequential parameters are suppressed at the CTI OS Server, to minimize network traffic to the clients. However, you can enable the complete set of available event arguments by setting the following registry setting:



Note


[HKLM\Cisco Systems\CTIOS\Server\CallObject\MinimizeEventArgs = 0].


OnAgentPrecallEvent


Note


The OnAgentPrecallEvent event is applicable to Unified CCE only. The equivalent on all other TDM events is TranslationRouteEvent.


The OnAgentPrecallEvent event is a pre-call indication that indicates the pending arrival of a call and provides early access to the call context information. From a call flow perspective, you can use this event to begin an application or database lookup for the call context data before the call actually arrives at the agent's teleset.

The contact is uniquely identified by the ICMEnterpriseUniqueID, which is a field based on the Unified ICM 64-bit unique key (RouterCallKeyDay and RouterCallKeyCallID). This event does not indicate the creation of a Call object on the CTI OS server—only that the contact is being tracked. This is sufficient to get and set data, which enables some powerful data-prefetching applications. When an OnCallBeginEvent follows for this same contact, the ICMEnterpriseUniqueID field is sent along with the call data. At that point, a custom application can set the call data on the appropriate call object.

Syntax

C++
void OnAgentPrecallEvent(Arguments& args)
COM
void OnAgentPrecallEvent (IArguments * args)
VB
session_OnAgentPrecallEvent (ByVal args As CtiosCLIENTLib.IArguments)

Parameters

args

Arguments array containing the following fields.
Table 18. OnAgentPrecallEvent Parameters

Keyword

Type

Description

ICMEnterpriseUniqueID

STRING

This string is a globally unique key for this contact, which corresponds to the Unified ICM 64 bit key. You can use this parameter to match this contact to a follow-on call event.

RouterCallKeyDay

INT

Together with the RouterCallKeyCallID field forms the unique 64-bit key for locating this call's records in the Unified ICM database. Only provided for Post-routed and Translation-routed calls.

RouterCalKeyCallID

INT

The call key created by the Unified ICM. The Unified ICM resets this counter at midnight.

AgentInstrument

STRING

The agent instrument that the call is routed to.

NumNamedVariables

SHORT

Number of Named variables.

NumNamedArrays

SHORT

Number of Named Arrays.

ServiceNumber

INT

The service that the call is attributed to, as known to the peripheral.

ServiceID

INT

The Unified ICM ServiceID of the service that the call is attributed to.

SkillGroupNumber

INT

An optional, user-defined number of the agent SkillGroup the call is attributed to, as known to the peripheral.

SkillGroupID

INT

The system-assigned identifier of the agent SkillGroup the call is attributed to.

SkillGroupPriority

SHORT

The priority of the skill group, or 0 when skill group priority is not applicable or not available.

ANI

STRING

The calling line ID of the caller.

UserToUserInfo

STRING

The ISDN user-to-user information element.

DNIS

STRING

The DNIS number to which this call will arrive on the ACD/PBX.

DialedNumber

STRING

The number dialed.

CallerEnteredDigits

STRING

The digits entered by the caller in response to VRU prompting.

CallVariable1

STRING

Call-related variable data.

...

STRING

...

CallVariable10

STRING

Call-related variable data.

ECC

ARGUMENTS

A nested Arguments structure of key-value pairs for all of the ECC data arriving with this call.

CallTypeIDTag

INT

Specifies CallType of the call and indicates that the agent is reserved via LegacyPreCall.

PreCallInvokeIDTag

INT

Specifies the invoking of the LegacyPreCall.

OnAgentPrecallAbortEvent


Note


The OnAgentPrecallAbortEvent event is applicable to Unified CCE only.


The OnAgentPrecallAbortEvent event is received only if a previously indicated routing (OnAgentPrecallEvent) decision is reversed. The contact is uniquely identified by the ICMEnterpriseUniqueID, which is a field based on the Unified ICM 64-bit unique key (RouterCallKeyDay and RouterCallKeyCallID). Upon receipt of an OnAgentPrecallAbortEvent, any data pre-fetch work that was started on an OnAgentPrecallEvent should be cleaned up.

Syntax

C++
void OnAgentPrecallAbortEvent(Arguments& args)
COM
void OnAgentPrecallAbortEvent (IArguments * args)
VB
session_OnAgentPrecallAbortEvent (ByVal args As CtiosCLIENTLib.IArguments)

Parameters

args

Arguments array containing the following fields.
Table 19. OnAgentPrecallAbortEvent Parameters

Keyword

Type

Description

ICMEnterpriseUniqueID

STRING

This string is a globally unique key for this contact, which corresponds to the Unified ICM 64 bit key. You can use This parameter to match this contact to a follow-on call event.

RouterCallKeyDay

INT

Together with the RouterCallKey CallID field forms the unique 64-bit key for locating this call's records in the Unified ICM database. Only provided for Post-routed and Translation- routed calls.

RouterCalKeyCallID

INT

The call key created by the Unified ICM. The Unified ICM resets this counter at midnight.

AgentInstrument

STRING

The agent instrument that the call will be routed to.

OnAlternateCallConf

The OnAlternateCallConf event is fired to the client to indicate that an Alternate request was received by the CTI Server

Syntax

C++
void OnAlternateCallConf (Arguments & args);
COM
HRESULT OnAlternateCallConf ([in] IArguments * args);
VB
Session_ OnAlternateCallConf (ByVal args as CTIOSCLIENTLIB.IArguments)

Parameters

args

Arguments array containing the following field.

Table 20. OnAlternateCallConf Parameters

Keyword

Type

Description

UniqueObjectID

STRING

An object ID that uniquely identifies the Call object.

OnAnswerCallConf

The OnAnswerCallConf event is fired to the client to indicate that an Answer request was received by the CTI Server.

Syntax

C++
void OnAnswerCallConf (Arguments & args);
COM
HRESULT OnAnswerCallConf ([in] IArguments * args);
VB
Session_ OnAnswerCallConf (ByVal args as CTIOSCLIENTLIB.IArguments)

Parameters

args

Arguments array containing the following field.

Table 21. OnAnswerCallConf Parameters

Keyword

Type

Description

UniqueObjectID

STRING

An object ID that uniquely identifies the Call object.

OnCallBegin

The OnCallBegin event is generated at the first association between a call and the CTI Client. The event passes the call identifier and the initial call context data. The ConnectionCallID identifies the call. This message always precedes any other event messages for that call.

Subsequent changes to the call context data (if any) are signaled by an OnCallDataUpdate event containing the changed call data.


Note


There can be multiple calls with the same ConnectionCallID value.


Syntax

C++
void OnCallBegin(Arguments& args)
COM
void OnCallBegin (IArguments * args)
VB
session_OnCallBegin (ByVal args As CtiosCLIENTLib.IArguments)

Parameters

args

Arguments array containing the following fields.

Table 22. OnCallBegin Parameters

Keyword

Type

Description

PeripheralID

INT

The Unified ICM PeripheralID of the ACD where the call activity occurred.

PeripheralType

SHORT

The type of the peripheral.

CallType

SHORT

The general classification of the call type.

UniqueObjectID

STRING

An object ID that uniquely identifies the Call object.

RouterCallKeyDay

INT

Together with the RouterCallKeyCallID field forms the unique 64-bit key for locating this call's records in the Unified ICM database. Only provided for Post-routed and Translation-routed calls.

RouterCalKeyCallID

INT

The call key created by the Unified ICM . The Unified ICM resets this counter at midnight.

RouterCallKey SequenceNumber

INT

Together with RouterCallKeyDay and RouterCallKeyCallID fields forms the TaskID.

ConnectionCallID

UINT

The Call ID value assigned to this call by the peripheral or the Unified ICM .

ANI (optional)

STRING

The calling line ID of the caller.

DNIS (optional)

STRING

The DNIS provided with the call.

UserToUserInfo (Optional)

STRING

The ISDN user-to-user information element. unspecified, up to 131 bytes.

DialedNumber (Optional)

STRING

The number dialed.

CallerEnteredDigits (Optional)

STRING

The digits entered by the caller in response to VRU prompting.

ServiceNumber (Optional)

INT

The service that the call is attributed to, as known to the peripheral. May contain the special value NULL_SERVICE when not applicable or not available.

ServiceID (Optional)

INT

The Unified ICM ServiceID of the service that the call is attributed to. May contain the special value NULL_SERVICE when not applicable or not available.

SkillGroupNumber (Optional)

INT

An optional, user-defined number of the agent SkillGroup the call is attributed to, as known to the peripheral. May contain the special value NULL_SKILL_GROUP when not applicable or not available.

SkillGroupID (Optional)

INT

The system-generated identifier of the agent SkillGroup the call is attributed to. May contain the special value NULL_SKILL_GROUP when not applicable or not available.

SkillGroupPriority (Optional)

SHORT

The priority of the skill group, or 0 when skill group priority is not applicable or not available.

CallWrapupData (Optional)

STRING

Call-related wrap-up data.

CallVariable1 (Optional)

STRING

Call-related variable data.

...

STRING

...

CallVariable10 (Optional)

STRING

Call-related variable data.

CallStatus (optional)

SHORT

The current status of the call.

ECC (optional)

ARGUMENTS

Arguments array that contains all of the Expanded Call Context variables in use; for example: user.ArrayVariable[0]user.ArrayVariable[1] ...user.ArrayVariable[n]user.ScalarVariable

CTIClients (optional)

ARGUMENTS

Arguments array that contains the information about the number of clients that are using the Call object; for example:

CTIClient[1]

CTIClientSignatureCTIClientTimestamp

ICMEnterprise UniqueID (optional)

STRING

Required only when the call is pre-routed.

OnCallCleared

An OnCallCleared event is generated when the voice portion of all parties on a call is terminated, normally when the last device disconnects from a call. With this event the connection status becomes LCS_NULL.


Note


If the CallCleared event is received after having received a CallFailed event, the event does not include a CallStatus because it is important to preserve the fact that the call failed (maintaining the CallStatus of LSC_Fail). Because of this exception, the CallStatus of the CallCleared event is optional.


Syntax

C++
void OnCallDelivered(Arguments& args)
COM
void OnCallCleared (IArguments * args)
VB
session_OnCallCleared (ByVal args As CtiosCLIENTLib.IArguments)

Parameters

args

Arguments array containing the following fields.
Table 23. OnCallCleared Parameters

Keyword

Type

Description

EnablementMask

INT

Contains the bit-mask that specifies what buttons can be enabled or disabled when this call is the current call.

UniqueObjectID

STRING

An object ID that uniquely identifies the Call object.

CallStatus

SHORT

The current status of the call.

ICMEnterprise UniqueID (Optional)

STRING

Required only when the call is pre-routed.

OnCallConnectionCleared

An OnCallConnectionCleared event is generated when a party drops from a call. With this event the connection status becomes LCS_NULL.


Note


If the CallConnectionCleared event is received after having received a CallFailed event, the event does not include a CallStatus because it is important to preserve the fact that the call failed (maintaining the CallStatus of LSC_Fail). Because of this exception, the CallStatus of the CallConnectionCleared event is optional.


Syntax

C++
void OnCallConnectionCleared(Arguments& args)
COM
void OnCallConnectionCleared (IArguments * args)
VB
session_OnCallConectionCleared (ByVal args As CtiosCLIENTLib.IArguments)

Parameters

args

Arguments array containing the following fields.
Table 24. OnCallConnectionCleared Parameters

Keyword

Type

Description

EnablementMask

INT

Contains the bit-mask that specifies what buttons can be enabled or disabled when this call is the current call.

UniqueObjectID

STRING

An object ID that uniquely identifies the Call object.

CallStatus

SHORT

The current status of the call.

ICMEnterprise UniqueID (Optional)

STRING

Required only when the call is pre-routed.

OnCallConferenced

The joining of calls into a conference call or the adding of a new call joining a conference can generate an OnCallConferenced event. With this event, the connections at the controller's device merge to become one connection with a status of LCS_CONNECT, and the status of the connections at the original caller's device and at the consulted device remain unchanged.

Syntax

C++
void OnCallConferenced(Arguments& args)
COM
void OnCallConferenced (IArguments * args)
VB
session_OnCallConferenced (ByVal args As CtiosCLIENTLib.IArguments)

Parameters

args

Arguments array containing the following fields.

Table 25. OnCallConferenced Parameters

Keyword

Type

Description

PeripheralID

INT

The Unified ICM PeripheralID of the ACD where the call activity occurred.

PeripheralType

SHORT

The type of the peripheral.

CallType

SHORT

The general classification of the call type.

UniqueObjectID

STRING

An object ID that uniquely identifies the Call object.

RouterCallKeyDay

INT

Together with the RouterCallKeyCallID field forms the unique 64-bit key for locating this call's records in the Unified ICM database. Only provided for Post-routed and Translation-routed calls.

RouterCalKeyCallID

INT

The call key created by the Unified ICM. The Unified ICM resets this counter at midnight.

ConnectionCallID

UINT

The Call ID value assigned to this call by the peripheral or the Unified ICM.

ANI (optional)

STRING

The calling line ID of the caller.

DNIS (optional)

STRING

The DNIS provided with the call.

UserToUserInfo (Optional)

STRING

The ISDN user-to-user information element. unspecified, up to 131 bytes.

DialedNumber (Optional)

STRING

The number dialed.

CallerEnteredDigits (Optional)

STRING

The digits entered by the caller in response to VRU prompting.

ServiceNumber (Optional)

INT

The service that the call is attributed to, as known to the peripheral. May contain the special value NULL_SERVICE when not applicable or not available.

ServiceID (Optional)

INT

The Unified ICM ServiceID of the service that the call is attributed to. May contain the special value NULL_SERVICE when not applicable or not available.

SkillGroupNumber (Optional)

INT

An optional, user-defined number of the agent SkillGroup the call is attributed to, as known to the peripheral. as known to the peripheral. May contain the special value NULL_SKILL_GROUP when not applicable or not available.

SkillGroupID (Optional)

INT

The system-assigned identifier of the agent SkillGroup the call is attributed to. May contain the special value NULL_SKILL_GROUP when not applicable or not available.

SkillGroupPriority (Optional)

SHORT

The priority of the skill group, or 0 when skill group priority is not applicable or not available.

CallWrapupData (Optional)

STRING

Call-related wrap-up data.

CallVariable1 (Optional)

STRING

Call-related variable data.

...

STRING

...

CallVariable10 (Optional)

STRING

Call-related variable data.

CallStatus (optional)

SHORT

The current status of the call.

ECC (optional)

ARGUMENTS

Arguments array that contains all of the Expanded Call Context variables in use; for example: user.ArrayVariable[0]user.ArrayVariable[1] ...user.ArrayVariable[n]user.ScalarVariable

CTIClients (Optional)

ARGUMENTS

Arguments array that contains the information about the number of clients that are using the Call object; for example:

CTIClient[1]

CTIClientSignatureCTIClientTimestamp

ICMEnterpriseUnique ID (Optional)

STRING

Required only when the call is pre-routed.

OnCallDataUpdate

Changes to the call context data generate an OnCallDataUpdate event. Only the changed items are in the event argument array. The initial call context is provided in the OnCallBegin event.

Syntax

C++
void OnCallDataUpdate(Arguments& args)
COM
void OnCallDataUpdate (IArguments * args)
VB
session_OnCallDataUpdate (ByVal args As CtiosCLIENTLib.IArguments)

Parameters

args

Arguments array containing the following fields.

Table 26. OnCallUpdate Parameters

Keyword

Type

Description

PeripheralID

INT

The Unified ICM PeripheralID of the ACD where the call activity occurred.

PeripheralType

SHORT

The type of the peripheral.

CallType

SHORT

The general classification of the call type.

UniqueObjectID

STRING

An object ID that uniquely identifies the Call object.

RouterCallKeyDay

INT

Together with the RouterCallKeyCallID field forms the unique 64-bit key for locating this call's records in the Unified ICM database. Only provided for Post-routed and Translation-routed calls.

RouterCalKeyCallID

INT

The call key created by the Unified ICM. The Unified ICM resets this counter at midnight.

RouterCallKey SequenceNumber

INT

Together with RouterCallKeyDay and RouterCallKeyCallID fields forms the TaskID.

ConnectionCallID

UINT

The Call ID value assigned to this call by the peripheral or the Unified ICM.

ANI (optional)

STRING

The calling line ID of the caller.

DNIS (optional)

STRING

The DNIS provided with the call.

UserToUserInfo (Optional)

STRING

The ISDN user-to-user information element. unspecified, up to 131 bytes.

DialedNumber (Optional)

STRING

The number dialed.

CallerEnteredDigits (Optional)

STRING

The digits entered by the caller in response to VRU prompting.

ServiceNumber (Optional)

INT

The service that the call is attributed to, as known to the peripheral. May contain the special value NULL_SERVICE when not applicable or not available.

ServiceID (Optional)

INT

The Unified ICM ServiceID of the service that the call is attributed to. May contain the special value NULL_SERVICE when not applicable or not available.

SkillGroupNumber (Optional)

INT

An optional, user-defined number of the agent SkillGroup the call is attributed to, as known to the peripheral. May contain the special value NULL_SKILL_GROUP when not applicable or not available.

SkillGroupID (Optional)

INT

The system-assigned identifier of the agent SkillGroup the call is attributed to. May contain the special value NULL_SKILL_GROUP when not applicable or not available.

SkillGroupPriority (Optional)

SHORT

The priority of the skill group, or 0 when skill group priority is not applicable or not available.

CallWrapupData (Optional)

STRING

Call-related wrap-up data.

CallVariable1 (Optional)

STRING

Call-related variable data.

...

STRING

...

CallVariable10 (Optional)

STRING

Call-related variable data.

CallStatus (optional)

SHORT

The current status of the call.

ECC (optional)

ARGUMENTS

Arguments array that contains all of the Expanded Call Context variables in use; for example: user.ArrayVariable[0]user.ArrayVariable[1]...user. ArrayVariable[n]user.ScalarVariable

CTIClients (Optional)

ARGUMENTS

Arguments array that contains the information about the number of clients that are using the Call object; for example:

CTIClient[1]

CTIClientSignatureCTIClientTimestamp

ICMEnterprise UniqueID (Optional)

STRING

Required only when the call is pre-routed.

OnCallDelivered

The OnCallDelivered event may be generated when the call arrives at the agent's teleset. Both parties (call connections) receive this event. With this event, the called party's connection status becomes LCS_ALERTING but the calling party's connection status remains LCS_INITIATE.


Note


With certain switches, when a call is made outside of the ACD, this event may not be received. For more information, see OnCallReachedNetwork.


Syntax

C++
void OnCallDelivered(Arguments& args)
COM
void OnCallDelivered (IArguments * args)
VB
session_OnCallDelivered (ByVal args As CtiosCLIENTLib.IArguments)

Parameters

args

Arguments array containing the following fields.

Table 27. OnCallDelivered Parameters

Keyword

Type

Description

ServiceNumber

INT

The service that the call is attributed to, as known to the peripheral. May contain the special value NULL_SERVICE when not applicable or not available.

ServiceID

INT

The Unified ICM ServiceID of the service that the call is attributed to. May contain the special value NULL_SERVICE when not applicable or not available.

SkillGroupNumber (Optional)

INT

An optional, user-defined number of the agent SkillGroup the call is attributed to, as known to the peripheral. May contain the special value NULL_SKILL_GROUP when not applicable or not available.

SkillGroupID (Optional)

INT

The system-assigned identifier of the agent SkillGroup the call is attributed to. May contain the special value NULL_SKILL_GROUP when not applicable or not available.

SkillGroupPriority (Optional)

SHORT

The priority of the skill group, or 0 when skill group priority is not applicable or not available.

LineType

SHORT

Indicates the type of the teleset line.

EnablementMask

INT

Contains the bit-mask that specifies what buttons can be enabled or disabled when this call is the current call. See Table 1.

UniqueObjectID

STRING

An object ID that uniquely identifies the Call object.

CallStatus

SHORT

The current status of the call.

ICMEnterpriseUniqueID (Optional)

STRING

Required only when the call is pre-routed.

TrunkNumber (optional)

INT

The number representing a trunk.

TrunkGroup Number (optional)

INT

The number representing a trunk group.

OnCallDequeuedEvent

The explicit removal of a call from the ACD queue can generate a OnCallDequeuedEvent message to the CTI Client.

Syntax

C++
void OnCallDequeuedEvent(Arguments& args)
COM
void OnCallDequeuedEvent (IArguments * args)
VB
session_OnCallDequeuedEvent (ByVal args As CtiosCLIENTLib.IArguments)

Parameters

args

Arguments array containing the following fields.

Table 28. OnCallDequeuedEvent Parameters

Keyword

Type

Description

Connection DeviceID

INT

The identifier of the connection between the call and the device.

ConnectionDevice IDType

SHORT

Indicates the type of the connection identifier supplied in the ConnectionDeviceID.

LocalConnection State

SHORT

The state of the local end of the connection.

EventCause

SHORT

Indicates a reason or explanation for the occurrence of the event.

LineHandle

SHORT

Identifies the teleset line being used.

LineType

SHORT

Indicates the type of the teleset line.

ServiceID

INT

The Unified ICM ServiceID of the service that the call is attributed to.

ServiceNumber

INT

The service that the call is attributed to, as known to the peripheral.

NumQueued

SHORT

The number of calls in the queue for this service.

NumSkillGroups

SHORT

The number of Skill Groups that the call has been removed from, up to a maximum of 99.

OnCallDiverted

The removal of a call from one delivery target and forwarded to a different target can generate an OnCallDiverted event.

Syntax

C++
void OnCallDiverted(Arguments& args)
COM
void OnCallDiverted (IArguments * args)
VB
session_OnCallDiverted (ByVal args As CtiosCLIENTLib.IArguments)

Parameters

args

Arguments array containing the following fields.

Table 29. OnCallDiverted Parameters

Keyword

Type

Description

UniqueObjectID

STRING

Unique reference generated for a call at client.

PeripheralID

INT

The Unified ICM PeripheralID of the ACD where the call activity occurred.

PeripheralType

SHORT

The type of the peripheral.

ConnectionDevice IDType

SHORT

Indicates the type of ConnectionDeviceID value.

Connection DeviceID

INT

The device identifier of the connection between the call and the device.

ConnectionCallID

UINT

The Call ID value assigned to this call by the peripheral or the Unified ICM.

ServiceNumber

INT

The service that the call is attributed to, as known to the peripheral. May contain the special value NULL_SERVICE when not applicable or not available.

ServiceID

INT

The Unified ICM ServiceID of the service that the call is attributed to. May contain the special value NULL_SERVICE when not applicable or not available.

DivertingDevice Type

SHORT

Indicates the type of the device identifier supplied in the DivertingDeviceID field.

CalledDeviceType

SHORT

Indicates the type of the device identifier supplied in the CalledDeviceID field.

LocalConnection State

SHORT

The state of the local end of the connection.

EventCause

SHORT

Indicates a reason or explanation for the occurrence of the event.

DivertingDeviceID (Optional)

STRING

The device identifier of the device from which the call was diverted.

CalledDeviceID (Optional)

STRING

The device identifier of the device to which the call was diverted.

OnCallEnd

The OnCallEnd event is generated when the association between a call and the CTI Client is dissolved. The OnCallEnd event is the last event received for a Call.

Syntax

C++
void OnCallEnd(Arguments& args)
COM
void OnCallEnd (IArguments * args)
VB
session_OnCallEnd (ByVal args As CtiosCLIENTLib.IArguments)

Parameters

args

Arguments array containing the following fields.

Table 30. OnCallEnd Parameters

Keyword

Type

Description

UniqueObjectID

STRING

An object ID that uniquely identifies the Call object.

CallStatus (optional)

SHORT

The current status of the call.

ICMEnterprise UniqueID (optional)

STRING

Required only when the call is pre-routed.

OnCallEstablished

The OnCallEstablished event is generated when the call is answered at the agent's teleset. Both parties (call connections) receive this event when the call is answered. With this event, the call status of both parties becomes LCS_CONNECT.


Note


With certain switches, when a call is made outside of the ACD, this event may not be received. See OnCallReachedNetwork for more detail.


Syntax

C++
void OnCallEstablished(Arguments& args)
COM
void OnCallEstablished (IArguments * args)
VB
session_OnCallEstablished (ByVal args As CtiosCLIENTLib.IArguments)

Parameters

args

Arguments array containing the following fields.

Table 31. OnCallEstablished Parameters

Keyword

Type

Description

ServiceNumber

INT

The service that the call is attributed to, as known to the peripheral. May contain the special value NULL_ SERVICE when not applicable or not available.

ServiceID

INT

The Unified ICM ServiceID of the service that the call is attributed to. May contain the special value NULL_SERVICE when not applicable or not available.

SkillGroupNumber (Optional)

INT

An optional, user-defined number of the agent SkillGroup the call is attributed to, as known to the peripheral. May contain the special value NULL_SKILL_GROUP when not applicable or not available.

SkillGroupID (Optional)

INT

The system-assigned identifier of the agent SkillGroup the call is attributed to. May contain the special value NULL_SKILL_GROUP when not applicable or not available.

SkillGroupPriority (Optional)

SHORT

The priority of the skill group, or 0 when skill group priority is not applicable or not available.

LineType

SHORT

Indicates the type of the teleset line.

EnablementMask

INT

Contains the bit-mask that specifies what buttons can be enabled or disabled when this call is the current call. See Table 1.

UniqueObjectID

STRING

An object ID that uniquely identifies the Call object.

CallStatus

SHORT

The current status of the call.

ICMEnterpriseUniqueID (Optional)

STRING

Required only when the call is pre-routed.

TrunkNumber (optional)

INT

The number representing a trunk.

TrunkGroup Number (optional)

INT

The number representing a trunk group.

OnCallFailed

The OnCallFailed event is generated when a call is not completed. With this event the connection status becomes LCS_FAIL. This usually happens as a result of a MakeCall or a MakeConsultCall request, but can occur at any other point in the call's lifetime if the call fails on an ACD. In this case, you should perform any required cleanup prior to arrival of an EndCall event.


Note


The events (CallConnectionCleared and CallCleared) received after the CallFailed event does not include a CallStatus because, until the call has ended, it is important to preserve the fact that this is a failed call.


Syntax

C++
void OnCallFailed(Arguments& args)
COM
void OnCallFailed (IArguments * args)
VB
session_OnCallFailed (ByVal args As CtiosCLIENTLib.IArguments

Parameters

args

Arguments array containing the following fields.
Table 32. OnCallFailed Parameters

Keyword

Type

Description

EnablementMask

INT

Contains the bit mask that specifies what buttons can be enabled or disabled when this call is the current call.

UniqueObjectID

STRING

An object ID that uniquely identifies the Call object.

CallStatus

SHORT

The current status of the call.

OnCallHeld

Placing a call on hold at the agent's teleset can generate an OnCallHeld event. With this event the connection status becomes LCS_HELD.

Syntax

C++
void OnCallHeld(Arguments& args)
COM
void OnCallHeld (IArguments * args)
VB
session_OnCallHeld (ByVal args As CtiosCLIENTLib.IArguments)

Parameters

args

Arguments array containing the following fields.

Table 33. OnCallHeld Parameters

Keyword

Type

Description

EnablementMask

INT

Contains the bit-mask that specifies what buttons can be enabled or disabled when this call is the current call.

UniqueObjectID

STRING

An object ID that uniquely identifies the Call object.

CallStatus

SHORT

The current status of the call.

ICMEnterpriseUniqueID (Optional)

STRING

Required only when the call is pre-routed.

OnCallOriginated

The initiation of a call from the peripheral can generate an OnCallOriginated event. Only the connection making the call receives this event. With this event the connection status becomes LCS_INITIATE.

Syntax

C++
void OnCallOriginated(Arguments& args)
COM
void OnCallOriginated (IArguments * args)
VB
session_OnCallOriginated (ByVal args As CtiosCLIENTLib.IArguments

Parameters

args

Arguments array containing the following fields.

Table 34. OnCallOriginated Parameters

Keyword

Type

Description

ServiceNumber

INT

The service that the call is attributed to, as known to the peripheral. May contain the special value NULL_SERVICE when not applicable or not available.

ServiceID

INT

The Unified ICM ServiceID of the service that the call is attributed to. May contain the special value NULL_SERVICE when not applicable or not available.

SkillGroupNumber (Optional)

INT

The user-defined number of the agent SkillGroup the call is attributed to, as known to the peripheral. May contain the special value NULL_SKILL_GROUP when not applicable or not available.

SkillGroupID (Optional)

INT

The system-assigned identifier of the agent SkillGroup the call is attributed to. May contain the special value NULL_SKILL_ GROUP when not applicable or not available.

SkillGroupPriority (Optional)

SHORT

The priority of the skill group, or 0 when skill group priority is not applicable or not available.

LineType

SHORT

Indicates the type of the teleset line.

EnablementMask

INT

Contains the bit-mask that specifies what buttons can be enabled or disabled when this call is the current call.

UniqueObjectID

STRING

An object ID that uniquely identifies the Call object.

CallStatus

SHORT

The current status of the call.

OnCallQueuedEvent

The placing of a call in a queue pending the availability of some resource can generate an OnCallQueuedEvent message to the CTI Client. Clients with Client Events Service can receive this message when an outbound call is queued waiting for a trunk or other resource. Clients with All Events Service can also receive this message when inbound calls are queued.

Syntax

C++
void OnCallQueuedEvent(Arguments& args)
COM
void OnCallQueuedEvent (IArguments * args)
VB
session_OnCallQueuedEvent (ByVal args As CtiosCLIENTLib.IArguments)

Parameters

args

Arguments array containing the following fields.

Table 35. OnCallQueuedEvent Parameters

Keyword

Type

Description

Connection DeviceID

INT

The identifier of the connection between the call and the device.

ConnectionDevice IDType

SHORT

Indicates the type of the connection identifier supplied in the ConnectionDeviceID.

QueuedDeviceID

STRING

The device identifier of the queuing device.

QueuedDeviceIDType

SHORT

Indicates the type of the device identifier supplied in the QueuedDeviceID.

CallingDeviceID

STRING

The device identifier of the calling device.

CallingDeviceIDType

SHORT

Indicates the type of the device identifier supplied in the CalledDeviceID.

CalledDeviceID

STRING

The device identifier of the called device.

CalledDeviceIDType

SHORT

Indicates the type of the device identifier supplied in the CalledDeviceID.

LastRedirectedDeviceID

STRING

The device identifier of the redirecting device.

LastRedirected DeviceIDType

SHORT

Indicates the type of the device identifier supplied in the LastRedirectDeviceID.

LocalConnection State

SHORT

The state of the local end of the connection.

EventCause

SHORT

Indicates a reason or explanation for the occurrence of the event.

LineHandle

SHORT

Identifies the teleset line being used.

LineType

SHORT

Indicates the type of the teleset line.

ServiceID

INT

The Unified ICM ServiceID of the service that the call is attributed to.

ServiceNumber

INT

The service that the call is attributed to, as known to the peripheral.

NumQueued

SHORT

The number of calls in the queue for this service.

NumSkillGroups

SHORT

The number of Skill Group queues that the call has queued to, up to a maximum of 50.

OnCallReachedNetworkEvent

The connection of an outbound call to another network can generate an OnCallReachedNetworkEvent. With some switches outside the ACD, this can be the last event the outbound connection receives. For these switches, you cannot assume that when the called party receives and answers the call that the OnCallDelivered and OnCallEstablished events is received.

Syntax

C++
void OnCallReachedNetworkEvent(Arguments& args)
COM
void OnCallReachedNetworkEvent (IArguments * args)
VB
session_OnCallReachedNetworkEvent (ByVal args As CtiosCLIENTLib.IArguments)

Parameters

args

Arguments array containing the following fields.

Table 36. OnCallReachedNetworkEvent Parameters

Keyword

Type

Description

Connection DeviceID

STRING

The identifier of the connection between the call and the device.

ConnectionDevice IDType

SHORT

Indicates the type of the connection identifier supplied in the ConnectionDeviceID.

TrunkUsedDeviceID

STRING

The device identifier of the selected trunk.

TrunkUsedDeviceIDType

SHORT

Indicates the type of the device identifier supplied in the TrunkUsedDeviceID.

CalledDeviceID

STRING

The device identifier of the called device.

CalledDeviceIDType

SHORT

Indicates the type of the device identifier supplied in the CalledDeviceID.

LocalConnection State

SHORT

The state of the local end of the connection.

EventCause

SHORT

Indicates a reason or explanation for the occurrence of the event.

LineHandle

SHORT

Identifies the teleset line being used.

LineType

SHORT

Indicates the type of the teleset line.

TrunkNumber (optional)

INT

The number representing a trunk.

TrunkGroup Number (optional)

INT

The number representing a trunk group.

OnCallRetrieved

Resuming a call previously placed on hold at the agent's teleset can generate an OnCallRetrieved event. With this event the connection status becomes LCS_CONNECT.

Syntax

C++
void OnCallRetrieved(Arguments& args)
COM
void OnCallRetrieved (IArguments * args)
VB
session_OnCallRetrieved (ByVal args As CtiosCLIENTLib.IArguments

Parameters

args

Arguments array containing the following fields.

Table 37. OnCallRetrieved Parameters

Keyword

Type

Description

EnablementMask

INT

Contains the bit-mask that specifies what buttons can be enabled or disabled when this call is the current call.

UniqueObjectID

STRING

An object ID that uniquely identifies the Call object.

CallStatus

SHORT

The current status of the call.

OnCallServiceInitiatedEvent

The initiation of telecommunications service ("dial tone") at the agent's teleset can generate an OnCallServiceInitiatedEvent to the CTI Client. However, when the call is made through the software, there is no way to detect the equivalent of the phone off hook. Therefore, after a call is made this event is received in sequence along with the OnCallOriginated and OnCallDelivered events. With this event the connection status becomes LCS_INITIATE.

Syntax

C++
void OnCallServiceInitiatedEvent(Arguments& args)
COM
void OnCallServiceInitiatedEvent (IArguments * args)
VB
session_OnCallServiceInitiatedEvent (ByVal args As CtiosCLIENTLib.IArguments)

Parameters

args

Arguments array containing the following fields.

Table 38. OnCallServiceInitiatedEvent Parameters

Keyword

Type

Description

ServiceNumber

INT

The service that the call is attributed to, as known to the peripheral. May contain the special value NULL_SERVICE when not applicable or not available.

ServiceID

INT

The Unified ICM ServiceID of the service that the call is attributed to. May contain the special value NULL_SERVICE when not applicable or not available.

SkillGroupNumber (Optional)

INT

The optional, user-defined number of the agent SkillGroup the call is attributed to, as known to the peripheral. May contain the special value NULL_SKILL_GROUP when not applicable or not available.

SkillGroupID (Optional)

INT

The system-assigned identifier of the agent SkillGroup the call is attributed to. May contain the special value NULL_SKILL_GROUP when not applicable or not available.

SkillGroupPriority (Optional)

SHORT

The priority of the skill group, or 0 when skill group priority is not applicable or not available.

LineType

SHORT

Indicates the type of the teleset line.

EnablementMask

INT

Contains the bit-mask that specifies what buttons can be enabled or disabled when this call is the current call.

UniqueObjectID

STRING

An object ID that uniquely identifies the Call object.

CallStatus

SHORT

The current status of the call.

OnCallStartRecordingConf

The OnCallStartRecordingConf event is fired to the client to indicate that the CTI server received a StartRecord request.

Syntax

C++
void OnCallStartRecordingConf (Arguments & args);
COM
HRESULT OnCallStartRecordingConf ([in] IArguments * args);
VB
Session_ OnCallStartRecordingConf (ByVal args as CTIOSCLIENTLIB.IArguments)

Parameters

args

Arguments array containing the following field.

Table 39. OnCallStartRecordingConf Parameters

Keyword

Type

Description

UniqueObjectID

STRING

An object ID that uniquely identifies the Call object.

OnCallStopRecordingConf

The OnCallStopRecordingConf event is fired to the client to indicate that a the CTI server received a StopRecord request.

Syntax

C++
void OnCallStopRecordingConf (Arguments & args);
COM
HRESULT OnCallStopRecordingConf ([in] IArguments * args);
VB
Session_ OnCallStopRecordingConf (ByVal args as CTIOSCLIENTLIB.IArguments)

Parameters

args

Arguments array containing the following field.

Table 40. OnCallStopRecordingConf Parameters

Keyword

Type

Description

UniqueObjectID

STRING

An object ID that uniquely identifies the Call object.

OnCallTransferred

The transfer of a call to another destination can generate an OnCallTransferred event. With this event the two connections at the controller's device end and the status of the connections at the original caller's device and the consulted device are unchanged.

Syntax

C++
void OnCallTransferred(Arguments& args)
COM
void OnCallTransferred (IArguments * args)
VB
session_OnCallTransferred (ByVal args As CtiosCLIENTLib.IArguments)

Parameters

args

Arguments array containing the following fields.

Table 41. OnCallTransferred Parameters

Keyword

Type

Description

PeripheralID

INT

The Unified ICM PeripheralID of the ACD where the call activity occurred.

PeripheralType

SHORT

The type of the peripheral.

CallType

SHORT

The general classification of the call type.

UniqueObjectID

STRING

An object ID that uniquely identifies the Call object.

RouterCallKeyDay

INT

Together with the RouterCallKeyCallID field forms the unique 64-bit key for locating this call's records in the Unified ICM database. Only provided for Post-routed and Translation-routed calls.

RouterCalKeyCallID

INT

The call key created by the Unified ICM. The Unified ICM resets this counter at midnight.

ConnectionCallID

UINT

The Call ID value assigned to this call by the peripheral or the Unified ICM.

ANI (optional)

STRING

The calling line ID of the caller.

DNIS (optional)

STRING

The DNIS provided with the call.

UserToUserInfo (Optional)

STRING

The ISDN user-to-user information element. unspecified, up to 131 bytes.

DialedNumber (Optional)

STRING

The number dialed.

CallerEnteredDigits (Optional)

STRING

The digits entered by the caller in response to VRU prompting.

ServiceNumber (Optional)

INT

The service that the call is attributed to, as known to the peripheral. May contain the special value NULL_SERVICE when not applicable or not available.

ServiceID (Optional)

INT

The Unified ICM ServiceID of the service that the call is attributed to. May contain the special value NULL_SERVICE when not applicable or not available.

SkillGroupNumber (Optional)

INT

The optional, user-defined number of the agent SkillGroup the call is attributed to, as known to the peripheral. May contain the special value NULL_SKILL_GROUP when not applicable or not available.

SkillGroupID (Optional)

INT

The system-assigned identifier of the agent SkillGroup the call is attributed to. May contain the special value NULL_SKILL_GROUP when not applicable or not available.

SkillGroupPriority (Optional)

SHORT

The priority of the skill group, or 0 when skill group priority is not applicable or not available.

CallWrapupData (Optional)

STRING

Call-related wrap-up data.

CallVariable1 (Optional)

STRING

Call-related variable data.

...

STRING

...

CallVariable10 (Optional)

STRING

Call-related variable data.

CallStatus (Optional)

SHORT

The current status of the call.

ECC (optional)

ARGUMENTS

Arguments array that contains all of the Expanded Call Context variables in use; for example: user.ArrayVariable[0]user.ArrayVariable[1] ...user.ArrayVariable[n]user.ScalarVariable

CTIClients (Optional)

ARGUMENTS

Arguments array that contains the information about the number of clients that are using the Call object; for example:

CTIClient[1]

CTIClientSignatureCTIClientTimestamp

ICMEnterpriseUniqueID (Optional)

STRING

Required only when the call is pre-routed.

OnClearCallConf

The OnClearCallConf event is fired to the client to indicate that the CTI server received a Clear request.

Syntax

C++
void OnClearCallConf (Arguments & args);
COM
HRESULT OnClearCallConf ([in] IArguments * args);
VB
OnClearCallConf (ByVal args as CTIOSCLIENTLIB.IArguments)

Parameters

args

Arguments array containing the following field.

Table 42. OnClearCallConf Parameters

Keyword

Type

Description

UniqueObjectID

STRING

An object ID that uniquely identifies the Call object.

OnClearConnectionConf

The OnClearConnectionConf event is fired to the client to indicate that the CTI server received a ClearConnection request.

Syntax

C++
void OnClearConnectionConf (Arguments & args);
COM
HRESULT OnClearConnectionConf ([in] IArguments * args);
VB
Session_ OnClearConnectionConf (ByVal args as CTIOSCLIENTLIB.IArguments)

Parameters

args

Arguments array containing the following field.

Table 43. OnClearConnectionConf Parameters

Keyword

Type

Description

UniqueObjectID

STRING

An object ID that uniquely identifies the Call object.

OnConferenceCallConf

The OnConferenceCallConf event is fired to the client to indicate that the CTI server received a ConferenceCall or SingleStepConferenceCall request.

Syntax

C++
void OnConferenceCallConf (Arguments & args);
COM
HRESULT OnConferenceCallConf ([in] IArguments * args);
VB
Session_ OnConferenceCallConf (ByVal args as CTIOSCLIENTLIB.IArguments)

Parameters

args

Arguments array containing the following field.

Table 44. OnConferenceCallConf Parameters

Keyword

Type

Description

UniqueObjectID

STRING

An object ID that uniquely identifies the Call object.

OnConsultationCallConf

The OnConsultationCallConf event is fired to the client to indicate that the CTI server received a MakeConsultCall request.

Syntax

C++
void OnConsultationCallConf (Arguments & args);
COM
HRESULT OnConsultationCallConf ([in] IArguments * args);
VB
OnConsultationCallConf (ByVal args as CTIOSCLIENTLIB.IArguments)Parameters

Parameters

args

Arguments array containing the following field.

Table 45. OnConsulationCallConf Parameters

Keyword

Type

Description

UniqueObjectID

STRING

An object ID that uniquely identifies the Call object.

OnControlFailureConf

The OnControlFailureConf event is generated when a request to the peripheral (the ACD) fails.

Syntax

C++
void OnControlFailureConf(Arguments& args)
COM
void OnControlFailureConf (IArguments * args)
VB
session_OnControlFailureConf (ByVal args As CtiosCLIENTLib.IArguments)

Parameters

args

Arguments array containing the following fields.

Table 46. OnControlFailureConf Parameters

Keyword

Type

Description

PeripheralID

INT

Peripheral ID.

FailureCode

SHORT

Code ID.

PeripheralError Code

INT

Peripheral-specific error data, if available. Zero otherwise.

AgentID

STRING

Agent ID that represents a specific client.

UniqueObjectID

STRING

An object ID that uniquely identifies the Call object.

MessageType

INT

Contains the CTI OS Command Request ID that failed to run. The message types included in this parameter are those to used to control Call, Agent State and Supervisor actions. For more information, see CTI OS Keywords and Enumerated Types.

ErrorMessage

STRING

String text containing the description of the failure.

OnHoldCallConf

The OnHoldCallConf event is fired to the client to indicate that the CTI server received a Hold request.

Syntax

C++
void OnHoldCallConf (Arguments & args);
COM
HRESULT OnHoldCallConf ([in] IArguments * args);
VB
Session_ OnHoldCallConf (ByVal args as CTIOSCLIENTLIB.IArguments)

Parameters

args

Arguments array containing the following field.

Table 47. OnHoldCallConf Parameters

Keyword

Type

Description

UniqueObjectID

STRING

An object ID that uniquely identifies the Call object.

OnMakePredictiveCallConf

Not supported.

OnReconnectCallConf

The OnReconnectCallConf event is fired to the client to indicate that the CTI server received a Reconnect request.

Syntax

C++
void OnReconnectCallConf (Arguments & args);
COM
HRESULT OnReconnectCallConf ([in] IArguments * args);
VB
OnReconnectCallConf (ByVal args as CTIOSCLIENTLIB.IArguments)

Parameters

args

Arguments array containing the following field.

Table 48. OnMakePredictiveCallConf Parameters

Keyword

Type

Description

UniqueObjectID

STRING

An object ID that uniquely identifies the Call object.

OnReleaseCallConf

Not supported.

OnRetrieveCallConf

The OnRetrieveCallConf event is fired to the client to indicate that the CTI server received a RetrieveCall request.

Syntax

C++
void OnRetrieveCallConf (Arguments & args);
COM
HRESULT OnRetrieveCallConf ([in] IArguments * args);
VB
Session_ OnRetrieveCallConf (ByVal args as CTIOSCLIENTLIB.IArguments)

Parameters

args

Arguments array containing the following field.

Table 49. OnReleaseCallConf Parameters

Keyword

Type

Description

UniqueObjectID

STRING

An object ID that uniquely identifies the Call object.

OnSendDTMFConf

The OnSendDTMFConf event is fired to the client to indicate that the CTI server received a SendDTMF request.

Syntax

C++
void OnSendDTMFConf (Arguments & args);
COM
HRESULT OnSendDTMFConf ([in] IArguments * args);
VB
Session_ OnSendDTMFConf (ByVal args as CTIOSCLIENTLIB.IArguments)

Parameters

args

Not used; reserved for future use.

OnSetCallDataConf

The OnSetCallDataConf event is fired to the client to indicate that the CTI server received a SetCallData request.

Syntax

C++
void OnSetCallConf (Arguments & args);
COM
HRESULT OnClearCallConf ([in] IArguments * args);
VB
OnClearCallConf (ByVal args as CTIOSCLIENTLIB.IArguments)

Parameters

args

Arguments array containing the following field.

Table 50. OnReleaseCallConf Parameters

Keyword

Type

Description

UniqueObjectID

STRING

An object ID that uniquely identifies the Call object.

OnSnapshotCallConf

The OnSnapshotCallConf event is generated when a SnapshotCall request for a specific call is successful. It contains all the information known about the specific connection at that point in time.

Syntax

C++
void OnSnapshotCallConf(Arguments& args)
COM
void OnSnapshotCallConf (IArguments * args)
VB
session_OnSnapshotCallConf (ByVal args As CtiosCLIENTLib.IArguments)

Parameters

args

Arguments array containing the following fields.

Table 51. OnSnapShotCallConf Parameters

Keyword

Type

Description

PeripheralID

INT

The Unified ICM PeripheralID of the ACD where the call activity occurred.

CallType

SHORT

The general classification of the call type.

UniqueObjectID

STRING

An object ID that uniquely identifies the call object.

DialedNumber

STRING

The number dialed.

CallerEnteredDigits

STRING

The digits entered by the caller in response to VRU prompting.

CallWrapupData

STRING

Call-related wrap-up data.

CallVariable1 (Optional)

STRING

Call-related variable data.

...

STRING

...

CallVariable10 (Optional)

STRING

Call-related variable data.

CustomerPhone Number

STRING

The customer phone number associated with the call.

CustomerAccount Number

STRING

The customer account number associated with the call.

ECC

ARGUMENTS

Arguments array that contains all of the Expanded Call Context variables in use; for example: user.ArrayVariable[0]user.ArrayVariable[1] ...user.ArrayVariable[n]user.ScalarVariable

CTIClients (Optional)

ARGUMENTS

Arguments array that contains the information about the number of clients that are using the Call object; for example:

CTIClient[1]

CTIClientSignatureCTIClientTimestamp

RouterCallKeyDay

INT

Together with the RouterCallKeyCallID field forms the unique 64-bit key for locating this call's records in the Unified ICM database. Only provided for Post-routed and Translation-routed calls.

RouterCallKeyCallID

INT

The call key created by the Unified ICM. The Unified ICM resets this counter at midnight.

NumNamedVariables

SHORT

Number of Named variables.

NumNamedArrays

SHORT

Number of Named Arrays.

NumCallDevices

SHORT

Number of devices associated with the call.

CalledDeviceID

STRING

The device identifier of the called device.

ConnectionCallID

UINT

The Call ID value assigned to this call by the peripheral or the Unified ICM.

CallStatus

SHORT

The current status of the call.

The following fields appear if they have information in them.

ANI

STRING

The calling line ID of the caller.

UserToUserInfo

STRING

The ISDN user-to-user information element associated with the call.

DNIS

STRING

The DNIS provided with the call.

If the MinimizeEventArgs registry entry is set to 0, the SnapshotCallConf event contains the following additional fields.

Table 52. SnapshotCallConf Additional Fields

Keyword

Type

Description

ICMEnterpriseUnique ID

STRING

This string is a globally unique key for this contact, which corresponds to the Unified ICM 64 bit key. This parameter can be used to match this contact to a follow-on call event.

CallConnectionCallID (optional)

UINT

The CallID value assigned to the call.

CallConnectionDeviceID Type (optional)

SHORT

Indicates the type of the connection identifier supplied in the following CallConnectionDeviceID floating field. This field always immediately follows the corresponding CallConnectionCallID field.

CallConnectionDeviceID (optional)

STRING

The identifier of the call connection. This field always immediately follows the corresponding CallConnectionDeviceIDType field.

CallDeviceConnection State

SHORT

The active state of the call. This field always immediately follows the corresponding CallConnection DeviceID field.

CallDeviceType

SHORT

Indicates the type of the device identifier supplied in the CallDeviceID field.

OnTransferCallConf

The OnTransferCallConf event is fired to the client to indicate that the CTI server received a TransferCall or SingleStepTransferCall request.

Syntax

C++
void OnTransferCallConf (Arguments & args);
COM
HRESULT OnTransferCallConf ([in] IArguments * args);
VB
Session_ OnTransferCallConf (ByVal args as CTIOSCLIENTLIB.IArguments)

Parameters

args

Arguments array containing the following field.

Table 53. OnTransferCallConf Parameters

Keyword

Type

Description

UniqueObjectID

STRING

An object ID that uniquely identifies the Call object.

IAgentEvents Interface

The Agent object fires events on the IAgentEvents interface. The following events are published to subscribers of the IAgentEvents interface.

OnAgentDeskSettingsConf

The OnAgentDeskSettingsConf event confirms successful completion of the request and provides the query response.

Syntax

C++
void OnAgentDeskSettings(Arguments& args)
COM
void OnAgentDeskSettings (IArguments * args)
VB
session_OnAgentDeskSettings (ByVal args As CtiosCLIENTLib.IArguments)

Parameters

args

Arguments array containing the following fields.

Table 54. OnAgentDeskSettingsConf Parameters

Keyword

Type

Description

InvokeID

UINT

Set to the same value as the InvokeID from the corresponding request message.

PeripheralID

UINT

The Unified ICM PeripheralID of the ACD where the device is located.

DeskSettingsMask

UINT

A bitwise combination of the Boolean desk setting Masks listed in the table below.

WrapupData IncomingMode

UINT

Indicates whether the agent is allowed or required to enter wrap-up data after an inbound call: 0 = Required, 1 = Optional, 2 = Not allowed, 3 = Required With WrapupData.

WrapupData OutgoingMode

UINT

Indicates whether the agent is allowed or required to enter wrap-up data after an outbound call: 0 = Required, 1 = Optional, 2 = Not allowed.

LogoutNon ActivityTime

UINT

Number of seconds of non-activity at the desktop after which the Unified ICM automatically logs out the agent.

QualityRecordingRate

UINT

Indicates how frequently calls to the agent are recorded.

RingNoAnswer Time

UINT

Number of seconds a call can ring at the agent's station before being redirected.

SilentMonitor WarningMessage

UINT

Set for a warning message box to prompt on agent desktop when silent monitor starts.

SilentMonitor AudibleIndication

UINT

Set for an audio click at beginning of the silent monitor.

SupervisorAssist CallMethod

UINT

Set for PIM to create a blind conference call for supervisor assist request; otherwise creates consultative call.

EmergencyCall Method

UINT

Set for PIM to create a blind conference call for emergency call request; otherwise creates a consultative call.

AutoRecordOn Emergency

UINT

Set for automatically record when emergency call request.

RecordingMode

UINT

Set for the recording request to go through Call Manager/PIM.

WorkModeTimer

UINT

Auto Wrap-up time out.

RingNoAnswer DN

UINT

The dialed number identifier for new re-route destination in the case of ring no answer.

Table 55. DeskSettingsMasks values

Mask Name

Description

Numeric Value

DESK_AVAIL_AFTER_ INCOMING_MASK

Set for automatically consider the agent available after handling an incoming call.

0x00000001

DESK_AVAIL_AFTER_OUTGOING_MASK

Set for automatically consider the agent available after handling an outbound call.

0x00000002

DESK_AUTO_ ANSWER_ENABLED_ MASK

Set when calls to the agent are automatically answered.

0x00000004

DESK_IDLE_REASON_REQUIRED_MASK

Set when the agent must enter a reason before entering the Idle state.

0x00000008

DESK_LOGOUT_ REASON_REQUIRED_MASK

Set when the agent must enter a reason before logging out.

0x00000010

DESK_SUPERVISOR_ CALLS_ALLOWED_MASK

Set when the agent can initiate supervisor assisted calls.

0x00000020

DESK_AGENT_TO_ AGENT_CALLS_ ALLOWED

Set when calls to other agents are allowed.

0x00000040

DESK_OUTBOUND_ACCESS_INTERNATIONAL_MASK

Set when the agent can initiate international calls.

0x00000080

DESK_OUTBOUND_ACCESS_PUBLIC_NET_MASK

Set when the agent can initiate calls through the public network.

0x00000100

DESK_OUTBOUND_ACCESS_PRIVATE_NET_MASK

Set when the agent can initiate calls through the private network.

0x00000200

DESK_OUTBOUND_ACCESS_OPERATOR_ASSISTED_MASK

Set when the agent can initiate operator assisted calls.

0x00000400

DESK_OUTBOUND_ACCESS_PBX_MASK

Set when the agent can initiate outbound PBX calls.

0x00000800

DESK_NON_ACD_CALLS_ALLOWED_MASK

Set when the agent can place or handle non-ACD calls.

0x00001000

DESK_AGENT_CAN_SELECT_GROUP_MASK

Set when the agent can select which groups they are logged into.

0x00002000

OnAgentGreetingControlConf

The OnAgentGreetingControlConf event confirms the successful completion of the SetAgentGreetingAction request.

Syntax

C++
void OnAgentGreetingControlConf(Arguments& args)
COM
void OnAgentGreetingControlConf (IArguments * args)
VB
session_OnAgentGreetingControlConf (ByVal args As CtiosCLIENTLib.IArguments)

Parameters

args

Arguments array containing the following fields.

Table 56. OnAgentIGreetingControlConfEvent Parameters

Keyword

Type

Description

MessageHeader

MHDR

Standard Message Header.

InvokeID

UINT

Set to the same value as the InvokeID from the corresponding request message.

OnAgentInfoEvent

The OnAgentInfoEvent event is generated as a response to a query to the Agent Name Lookup Service and carries the agent's name. The CTI OS server generates this query when it is configured to do agent name lookup. The OnAgentInfoEvent event is sent to the client if the server obtained the information.

Syntax

C++
void OnAgentInfoEvent(Arguments& args)
COM
void OnAgentInfoEvent (IArguments * args)
VB
session_OnAgentInfoEvent (ByVal args As CtiosCLIENTLib.IArguments)

Parameters

args

Arguments array containing the following fields.
Table 57. OnAgentInfoEvent Parameters

Keyword

Type

Description

UniqueObjectID

STRING

A unique object ID for the Agent object.

AgentLastName

STRING

Agent's last name.

AgentFirstName

STRING

Agent's first name.

OnAgentStateChange

The OnAgentStateChange event is generated when the agent state at the ACD changes. This can be as a response to a Login, Logout, or SetAgentState request.

Syntax

C++
void OnAgentStateChange(Arguments& args)
COM
void OnAgentStateChange (IArguments * args)
VB
session_OnAgentStateChange (ByVal args As CtiosCLIENTLib.IArguments)

Parameters

args

Arguments array containing the following fields.

Table 58. OnAgentIStateChange Parameters

Keyword

Type

Description

PeripheralID

INT

The Unified ICM PeripheralID of the ACD where the agent state change occurred.

PeripheralType

SHORT

The type of the peripheral.

AgentState

SHORT

One of the values in Table 2 representing the current overall state of the associated agent.

SkillGroupNumber

INT

The optional, user-defined number of the agent SkillGroup affected by the state change, as known to the peripheral. May contain the special value NULL_SKILL_GROUP when not applicable or not available.

SkillGroupID

INT

The system-assigned identifier of the agent SkillGroup affected by the state change. May contain the special value NULL_SKILL_ GROUP when not applicable or not available.

StateDuration

INT

The number of seconds since the agent entered this state (typically 0).

SkillGroupPriority

SHORT

The priority of the skill group, or 0 when skill group priority is not applicable or not available.

EventReasonCode

SHORT

A peripheral-specific code indicating the reason for the state change.

SkillGroupState

SHORT

Values representing the current state of the associated agent with respect to the indicated Agent Skill Group.

AgentID

STRING

The agent's ACD login ID.

AgentExtension

STRING