CTI

CTI interface

CTI Modul

Module description

This module contains structures and operations for CTI (remote call control) on TAPI or Bluetooth phone lines in the server.

A client program has access to all lines owned by the logged in user and to additional lines it has dedicated access.

It is possible to monitor all actions on these lines and to call operations to initiate new calls, set forwards, change states and so on.

Prerequisites

In order to use the operations described in this document you have to make sure:

The server has lines configured and activated. (Install an appropriate TAPI-driver for your PBX system.)
There is at least one user activated on the server, who has lines configured to use.
The client program is connected to the server via UCServer Web Services using a websocket or directly to the server on the client port (default port 7222).
The client program encodes the data structures as estos JSON or ASN.1 BER.
The client program is logged in to the server with a user who has access to lines.

Additional prerequisites for a operation on the PBX and or the TAPI driver may be necessary.

Description of the Line-Call-Model

The remote call control and monitoring of the server is based on a line-call-model. This means, that users, lines and calls are organized in a tree like hierarchy.
Each node in this tree contains configuration data and dynamic data, which can be accessed and observed.

The Nodes are:

The user. This a more a kind of "meta" node, it just holds the list of lines, a client has access to if it is logged in as this user.
The line(s). Defined with the logged in user, a client can retrieve a list of lines, the user has access to. With these lines, the client can (one time) pull information or can attach itself on to get initial data and events if these data changes over time (get-and-subscribe mechanism).
The line information contains configuration information and dynamic data about the lines status, including current calls.
Note: A line is identified by its URI tel:number@pbxsystem. The parameter is often named as "u8sLinePhoneNumber".
The "u8sPhoneNumber" is the phone number of a line, but for technical reasons that is not a distinct property of a line. It is possible to have multiple lines with the same phone number!
The call(s). A line has a list of current calls, which are currently "on" the line. If the client is attached to a line for events, new calls will be announced via events. Changes to these calls are also announced via events.
There is no need to attach to calls explicitly, this is already done by attaching to the line. Call changing events are then sent to the client too.
Note: A call is identified by its connection identifier often named as "ConnectionID".

Remarks

Some operations return an empty result object if they are executed successfully. So in this cases, the business logic should wait for result/error before do additional actions.
Phone numbers are normally used and provided in a so called supercanonic notation containing a full qualified number including country, city, main and extension number: +49815136856177
For operations affecting multiple calls be sure to check that all calls affected have the corresponding feature set. To merge two calls both calls have to have the feature eCFEATUREMERGECALLS set.

Example: Monitoring lines

Get the lines the client has access to with asnCtiEnumPhoneLines. If you wish to get events if the line list changes afterwards, set the parameter "attachChangeNotify" to 1.
Use the lines URI to start monitoring for initial data and events on it. asnCtiLineMonitorStart will result in a monitor cross reference id to distinguish between events for different line monitors easier.
This is useful, if the client has the requirement to monitor the same line multiple times for different use cases.
With the line URI you can call functions e.g. asnCtiMakeCall, asnCtiAnswerCall a.s.o. With the line monitoring on, you will get the according changes on the line and its calls as events back.
To stop monitoring a line, call asnCtiLineMonitorStop with the corresponding monitor cross reference id.

Example: Call data transfer

Phone number formats

The whole system tries to use supercanonic numbers (+country city main and extension number / +49815136856177) whereever possible.
As long as the number is used in supercanonic notation all components can format the number as required (for dialing, for display, etc.)
You likely wonÂ´t need to format numbers as the system always provides supercanonic numbers.

Operations:

Name	Description
asnCtiEnumPhoneLines	Retrieve line information from the server.
asnCtiSnapshotPhoneLine	Call this function to get the current status of a line.
asnCtiLineMonitorStart	Gets the current state of a line and attach for call and change notifies on this line.
asnCtiLineMonitorStop	Stops the call and state change events on a line.
asnCtiLineSetDoNotDisturb	Set or remove "Do not Disturb" feature on the a line.
asnCtiLineSetRemoteOffice	Changes the state of the "Remote Office" feature on a line.
asnCtiMakeCall	Initiates a new call on a line.
asnCtiDropCall	Drop a call identified by its connection identifier.
asnCtiLineDropCall	Drop the cative call on a line.
asnCtiAnswerCall	Accept a call on a line.
asnCtiRedirectCall	Redirect an incoming call to another line.
asnCtiPickupCall	Pickup a ringing call from another line on an own line.
asnCtiStartCallRecording	Start recording of a call.
asnCtiStopCallRecording	Stop recording of a call.
asnCtiSetCallData	Add some data to the call which will be transferred to other clients.
asnCtiMergeCalls	Merge two calls on a line together.
asnCtiSwapHold	Swap puts the active call on hold and retrieves the hold call
asnCtiHold	Set the call on hold, so another another call in the same line will be possible to make.
asnCtiSetForward	Set simple call forwards.
asnCtiRemoveForward	Remove a forward from a line.
asnCtiDialDigits	Dial DTMF tones on an active call.
asnCtiCompleteCall	Set a automatic call back if the call was not accepted or busy.
asnCtiConference	Initiate a conference call with two already existing calls of a line.

Events:

Name	Description
asnCtiNotifyLineInfoChanged	Event from the server if a line changed its status or has been added or removed. In order to get these events the line must be monitored with asnCtiLineMonitorStart
asnCtiNotifyLineDoNotDisturbChanged	Event from the server if a line changed its DnD status. In order to get these events the line must be monitored with asnCtiLineMonitorStart
asnCtiNotifyLineRemoteOfficeChanged	Event from the server if a line changed its remote office state. In order to get these events the line must be monitored with asnCtiLineMonitorStart
asnCtiNotifyMonitorStopped	Event from the server that a monitoring point was closed due to a configuration change In order to get these events the line must be monitored with asnCtiLineMonitorStart This event is send to the client if a monitor was closed due to a configuation change on the server The client shall remove the monitor point with u8sMonitorCrossRefID on the client side.
asnCtiNotifyLineSortOrderChanged	Event from the server that a monitoring point has changed position from the configurative view In order to get these events the line must be monitored with asnCtiLineMonitorStart This event is send to the client if the sort order of the lines has changed (line added, config lines have swapped positions, (no event is dispatched if a line was removed)) This event is only dispatched for the userOwnLines (see AsnCtiEnumPhoneLinesArgument)
asnCtiNotifyLineForwardingChanged	Event from the server if a line changed its forwardings. In order to get these events the line must be monitored with asnCtiLineMonitorStart
asnCtiNotifyLineCallInformationChanged	Event from the server if a call changed its state. In order to get this event the line must be monitored with asnCtiLineMonitorStart
asnCtiNotifyLineAddRemove	Event from the server if asnCtiEnumPhoneLines was called to monitor the lines of the user. In order to get this event the line must be monitored via asnCtiEnumPhoneLines
asnCtiNotifyMakeCallResult	Event from the server with the result of an asynchronous make call operation on the server. In order to get this event the client must have called asnCtiMakeCall first.
asnCtiNotifyConferenceCreated	Event from the server if there is a conference established on a line. In order to get these events the line must be monitored via asnCtiLineMonitorStart
asnCtiNotifyConferenceDestroyed	Event from the server if a conference is closed/destroyed. In order to get these events the line must be monitored via asnCtiLineMonitorStart
asnCtiNotifyConferencePartyAdded	Event from the server when a new participant was added to a conference. In order to get these events the line must be monitored via asnCtiLineMonitorStart
asnCtiNotifyConferencePartyRemoved	Event from the server when a conference participant was removed. In order to get these events the line must be monitored via asnCtiLineMonitorStart
asnCtiNotifyLineCallFeaturesChanged	Event from the server when call features have changed. In order to get these events the line must be monitored via asnCtiLineMonitorStart
asnCtiNotifyLineProjectSettingsChanged	Event from the server when the project settings or the location of a line has changed. In order to get these events the line must be monitored via asnCtiLineMonitorStart

Types:

Name	Description
AsnCtiNotifyLineAddRemoveArgumentEnum	Line was added (0) or removed (1).
AsnCtiEnumPhoneLinesArgumentEnum	Which lines shall be listed for the user (own, additional lines, all).
AsnCtiLineOpenStatus	Line Open State (identical to ECTILineStatusEnum)
EnumCallFeatures	Bitfield of features/functions which can be executed on a call.
EnumLineFeatures	Bitfield describing which features/function can be executed on a line
EnumForwardModes	Different forward modes the API supports
EnumForwardController	Different forward controllers the API supports
AsnCtiEnumPhoneLinesErrorEnum	Error codes in case AsnRequestError is returned.
AsnCtiSnapshotPhoneLineErrorEnum	Error codes in case AsnRequestError is returned by asnCtiSnapshotPhoneLine
AsnCtiLineMonitorStartErrorEnum	Error codes in case AsnRequestError is returned by asnCtiLineMonitorStart
AsnCtiLineMonitorStopErrorEnum	Error codes in case AsnRequestError is returned by asnCtiLineMonitorStop
AsnCtiLineSetDoNotDisturbErrorEnum	Error codes in case AsnRequestError is returned by asnCtiLineSetDoNotDisturb
AsnCtiLineSetRemoteOfficeErrorEnum	Error codes in case AsnRequestError is returned by asnCtiLineSetRemoteOffice
AsnCtiCallInfoChangedReason	Possible reasons for a call information changed event.
AsnCtiMakeCallErrorEnum	Error codes in case AsnRequestError is returned by asnCtiMakeCall
EnumCtiDigitMode	Line dial digit modes for asnCtiDialDigits
AsnCtiCallData	Data structure (key value pair) to associate additional information with call objects.
AsnCtiLineInfo	Description of a line with its state, phone number etc.
AsnLineForward	Line forward information object
AsnRemoteOfficeState	Remove office information object
AsnCtiEnumPhoneLinesError	Generic error sequence. See the documentation of the operations specific descriptions.
AsnCtiSnapshotPhoneLineArgument	Argument for asnCtiSnapshotPhoneLine
AsnCtiSnapshotPhoneLineError	Generic error sequence. See the documentation of the operations specific descriptions.
AsnCtiLineMonitorStartArgument	Arguments for asnCtiLineMonitorStart
AsnCtiLineMonitorStartError	Generic error sequence. See the documentation of the operations specific descriptions.
AsnCtiLineMonitorStopArgument	Arguments for asnCtiLineMonitorStop
AsnCtiLineMonitorStopResult	Result of asnCtiLineMonitorStop
AsnCtiLineMonitorStopError	Generic error sequence. See the documentation of the operations specific descriptions.
AsnCtiLineSetDoNotDisturbArgument
AsnCtiLineSetDoNotDisturbResult	Result of asnCtiLineSetDoNotDisturb
AsnCtiLineSetDoNotDisturbError	Generic error sequence. See the documentation of the operations specific descriptions.
AsnCtiLineSetRemoteOfficeResult	Result of asnCtiLineSetRemoteOffice If the client receives the Result, the operation was successful.
AsnCtiLineSetRemoteOfficeError	Generic error sequence. See the documentation of the operations specific descriptions.
AsnCtiNotifyLineDoNotDisturbChangedArgument	Event arguments of asnCtiNotifyLineDoNotDisturbChanged
AsnCtiNotifyMonitorStoppedArgument	Event arguments of asnCtiNotifyMonitorStopped
AsnCtiNotifyLineSortOrderChangedArgument	Event arguments of asnCtiNotifyLineSortOrderChanged
AsnCtiNotifyMakeCallResultArgument	Event arguments of asnCtiNotifyMakeCallResult
AsnCtiCallFeature	Helper to combine ConnectionID and call features of a call. See asnCtiNotifyLineCallFeaturesChanged
AsnCtiNotifyLineProjectSettingsChangedArgument	Event arguments for asnCtiNotifyLineProjectSettingsChanged
AsnCtiMakeCallArgument	Arguments for asnCtiMakeCall
AsnCtiMakeCallResult	Result of asnCtiMakeCall
AsnCtiMakeCallError	Generic error sequence. See the documentation of the operations specific descriptions.
AsnCtiDropCallArgument	Arguments for asnCtiDropCall
AsnCtiDropCallResult	Result of asnCtiDropCall If an error occured, AsnRequestError will be set.
AsnCtiLineDropCallArgument	Arguments for asnCtiLineDropCall
AsnCtiLineDropCallResult	Result of asnCtiLineDropCall If an error occured, AsnRequestError will be set.
AsnCtiAnswerCallArgument	Arguments for asnCtiAnswerCall
AsnCtiAnswerCallResult	Result of asnCtiAnswerCall If an error occured, AsnRequestError will be set.
AsnCtiRedirectCallArgument	Arguments for asnCtiRedirectCall
AsnCtiRedirectCallResult	Result of asnCtiRedirectCall If an error occured, AsnRequestError will be set.
AsnCtiPickupCallArgument	Arguments for asnCtiPickupCall
AsnCtiPickupCallResult	Result of asnCtiPickupCall If an error occured, AsnRequestError will be set.
AsnCtiStartCallRecordingArgument	Arguments for asnCtiStartCallRecording
AsnCtiStartCallRecordingResult	Result of asnCtiStartCallRecording If an error occured, AsnRequestError will be set.
AsnCtiStopCallRecordingArgument	Arguments for asnCtiStopCallRecording
AsnCtiStopCallRecordingResult	Result of asnCtiStopCallRecording If there was no error executing this operation, the result will be returned; otherwise AsnRequestError is set.
AsnCtiSetCallDataResult	Ergebnis fÃ¼r asnCtiSetCallData
AsnCtiMergeCallsArgument	Arguments for asnCtiMergeCalls
AsnCtiMergeCallsResult	Result of asnCtiMergeCalls If an error occured, AsnRequestError will be set.
AsnCtiSwapHoldArgument	Arguments for asnCtiSwapHold
AsnCtiSwapHoldResult	Result of asnCtiSwapHold If an error occured, AsnRequestError will be set.
AsnCtiHoldArgument	Arguments for asnCtiHold
AsnCtiHoldResult	Result of asnCtiHold If an error occured, AsnRequestError will be set.
AsnCtiSetForwardArgument	Arguments for asnCtiSetForward
AsnCtiSetForwardResult	Result of asnCtiSetForward If an error occured, AsnRequestError will be set.
AsnCtiRemoveForwardArgument	Arguments for asnCtiRemoveForward
AsnCtiRemoveForwardResult	Result of asnCtiRemoveForward If an error occured, AsnRequestError will be set.
AsnCtiDialDigitsArgument	Arguments for asnCtiDialDigits
AsnCtiDialDigitsResult	Result of asnCtiDialDigits If an error occured, AsnRequestError will be set.
AsnCtiCompleteCallArgument	Arguments for asnCtiCompleteCall
AsnCtiCompleteCallResult	Result of asnCtiCompleteCall If an error occured, AsnRequestError will be set.
AsnCtiConferenceArgument	Arguments for asnCtiConference
AsnCtiConferenceResult	Result of asnCtiConference If an error occured, AsnRequestError will be set.
AsnCtiCallDataList	List of AsnCtiCallData objects
AsnCtiLineInfoList
AsnCtiCallInformation	In depth information about a call
AsnCtiCallInformationList
AsnLineForwards
AsnCtiEnumPhoneLinesArgument	Arguments for asnCtiEnumPhoneLines
AsnCtiEnumPhoneLinesResult
AsnCtiSnapshotPhoneLineResult	If asnCtiSnapshotPhoneLine is executed successful, AsnCtiSnapshotPhoneLineResult will be returned.
AsnCtiLineMonitorStartResult
AsnCtiLineSetRemoteOfficeArgument
AsnCtiNotifyLineInfoChangedArgument	Event arguments of asnCtiNotifyLineInfoChanged
AsnCtiNotifyLineRemoteOfficeChangedArgument	Event arguments of asnCtiNotifyLineRemoteOfficeChanged
AsnCtiNotifyLineForwardingChangedArgument	Event arguments of asnCtiNotifyLineForwardingChanged
AsnCtiNotifyLineCallInformationChangedArgument	Event arguments of asnCtiNotifyLineCallInformationChanged
AsnCtiNotifyLineAddRemoveArgument	Event arguments of asnCtiNotifyLineAddRemove
AsnCtiNotifyConferenceCreatedArgument	Event arguments of asnCtiNotifyConferenceCreated
AsnCtiNotifyConferenceDestroyedArgument	Event arguments of asnCtiNotifyConferenceDestroyed
AsnCtiNotifyConferencePartyAddedArgument	Event arguments of asnCtiNotifyConferencePartyAdded
AsnCtiNotifyConferencePartyRemovedArgument	Event arguments of asnCtiNotifyConferencePartyRemoved
AsnCtiCallFeaturesList	List of AsnCtiCallFeature objects.
AsnCtiNotifyLineCallFeaturesChangedArgument	Event arguments of asnCtiNotifyLineCallFeaturesChanged
AsnCtiSetCallDataArgument	Arguments for asnCtiSetCallData

Version 6.4