CTI integration events (ctievents)

Description

An abstraction layer over telephony events for external CTI systems (Computer Telephony Integration) in terms of devices and calls: delivery, answer, hold, transfer, completion. Events are built by the cti plugin from callevents events of all site domains and sent to master domain subscribers. An example consumer is the SmartLogger (CRT) conversation recording system adapter connected via gRPC (the cti_servers mware role option). Besides call events, the adapter passes to its client the composition of domain operators and devices and its changes (by $system events).

Table 1. System characteristics

Class

ctievents

Domain type

master

Destination types

wssubscr (master domain subscriptions), kafka (master domain)

Source logical role

mware (site master domain cti plugin)

Handler logical role

Subscription and delivery

  • Subscription in the master domain: "events": ["ctievents.*"] or the ctievents.<type> list, "objects": "any"; via Token API (websocket) or webhooks (not recommended: events of all site calls). To Kafka — when kafka_mustache is configured in the master domain and only while events are generated (see below): Kafka is not considered a subscriber and does not enable generation.

  • Each site generates events of its own calls: a subscriber receives events of the sites where it is subscribed (the SmartLogger adapter — only its own site).

  • Call events are generated while the cti_servers option is set for any mware instance on the site — then from mware startup, including already ongoing calls, regardless of consumer connection. Without it — while the class has subscribers receiving events of this site: processing is enabled within a minute after the first subscriber appears (calls started earlier arrive from the middle) and disabled 10 minutes after the last one leaves. $system events and external events are always generated.

  • Disabling: the value "cti" in the events list of the master domain disabled_plugins setting.

Notification format:

["notify", {"sid": "...", "class": "ctievents", "type": "call_delivered", "eventts": 1792170171426, "data": {...}}]

Events

Type When

call_delivered

Call delivered to the device

call_established

Conversation established

call_held

Conversation put on hold

call_retrieved

Conversation taken off hold

call_transfer

Call transferred

call_cleared

Call or conversation completed

$system

Domain users or SIP users changed

External events

Sent by an external system via the cti_event method

External events (cti_event)

An event of the class can be generated by an external system (product layer) of a working domain with the cti_event Token API ccs request:

["cti_event", {"qid": 1, "type": "agent", "params": {"agent_id": "operator1@pbx.incoplax.com", "agent_name": "Operator 1", "agent_state": "ready", "device_id": "13@pbx.incoplax.com"}}]
  • type — event type, params — the data object; domain — the integration channel domain — is added to data.

  • There is no response to the request.

  • The type and composition of params are not validated; the consumer understands its own types. The SmartLogger adapter, besides the events above, accepts device, agent, group, agentgroup, call_conference, call_queued, call_dequeued.

Example notification
["notify", {"sid": "my_subscr", "class": "ctievents", "type": "agent", "eventts": 1792170212400,
  "data": {"agent_id": "operator1@pbx.incoplax.com", "agent_name": "Operator 1", "agent_state": "ready",
           "device_id": "13@pbx.incoplax.com", "domain": "pbx.incoplax.com"}}]