CTI

CTI Modul

Module description

This module contains the 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

  1. 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.
  2. 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.
  3. 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.
  4. 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.

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

AsnCtiQueryPBXLineErrorEnum

- PRIVATE - Error codes in case AsnRequestError is returned by asnCtiQueryPBXLine

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

AsnMobileRegisterDeviceErrorEnum

- PRIVATE - Errors of asnMobileRegisterDevice.

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

AsnCtiSnapshotPhoneLineArgument

Argument for asnCtiSnapshotPhoneLine

AsnCtiSnapshotPhoneLineError

AsnCtiLineMonitorStartArgument

Arguments for asnCtiLineMonitorStart

AsnCtiLineMonitorStartError

AsnCtiLineMonitorStopArgument

Arguments for asnCtiLineMonitorStop

AsnCtiLineMonitorStopResult

Result of asnCtiLineMonitorStop

AsnCtiLineMonitorStopError

AsnCtiLineSetDoNotDisturbArgument

AsnCtiLineSetDoNotDisturbResult

Result of asnCtiLineSetDoNotDisturb

AsnCtiLineSetDoNotDisturbError

AsnCtiLineSetRemoteOfficeResult

Result of asnCtiLineSetRemoteOffice

If the client receives the Result, the operation was successful.

AsnCtiLineSetRemoteOfficeError

AsnCtiLineSetNewPasswordArgument

- PRIVATE -

AsnCtiLineSetNewPasswordResult

- PRIVATE - Result of asnCtiLineSetNewPassword

If the client receives the Result, the operation was successful.

AsnCtiLineSetNewPasswordError

- PRIVATE -

AsnCtiQueryPBXLineArgument

- PRIVATE -

AsnCtiQueryPBXLineResult

- PRIVATE - Result of asnCtiQueryPBXLine

AsnCtiQueryPBXLineError

- PRIVATE -

AsnCtiNotifyLineDoNotDisturbChangedArgument

Event arguments of asnCtiNotifyLineDoNotDisturbChanged

AsnCtiNotifyLineInvalidPasswordChangedArgument

- PRIVATE - Event arguments of asnCtiNotifyLineInvalidPasswordChanged.

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

AsnCtiLineSetForwardStateResult

Result of asnCtiLineSetForwardState
If an error occured, AsnRequestError will be set.

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.

AsnCtiSetupConferenceArgument

- PRIVATE - Arguments for asnCtiSetupConference.

AsnCtiSetupConferenceResult

- PRIVATE - Result of asnCtiSetupConference.
If an error occured, AsnRequestError will be set.

AsnCtiSetActiveLineAddressArgument

- PRIVATE - Arguments for asnCtiSetActiveLineAddress.

AsnCtiSetActiveLineAddressResult

- PRIVATE - Result of asnCtiSetActiveLineAddress.
If an error occured, AsnRequestError will be set.

AsnCtiNotifyLineActiveAddressChangedArgument

- PRIVATE - Event arguments of asnCtiNotifyLineActiveAddressChanged

AsnMobileRegisterDeviceArgument

- PRIVATE - Arguments for asnMobileRegisterDevice.

AsnMobileRegisterDeviceResult

- PRIVATE - Result of asnMobileRegisterDevice.

AsnMobileRegisterDeviceError

- PRIVATE -

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.

AsnCtiLineSetForwardStateArgument

Arguments for asnCtiLineSetForwardState

AsnCtiSetCallDataArgument

Arguments for asnCtiSetCallData

Version 6.1