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.

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.

asnCtiLineSetNewPassword

- PRIVATE - Set a password for a line.

asnCtiQueryPBXLine

- PRIVATE - Find lines in the server for a supercanonic number.

asnCtiMakeCall

Initiates a new call on a line.

asnCtiLineSetForwardState

- PRIVATE - not implemented

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.

asnCtiSetupConference

- PRIVATE - Operation to initiate a conference with "american conference model.

asnCtiSetActiveLineAddress

- PRIVATE - Allows to set the active address on a phone line

asnMobileRegisterDevice

- PRIVATE - (Re-)register a new line to the virtual line subsystem of the server.

Version 6.1