'subscr' capability for WebSocket User API
Overview
The module is used to subscribe to system events. Events occurring in the system are divided into classes, packed into objects with event data, and sent to subscribers using filters.
Events are sent only within an existing subscription. If the same event matches several subscriptions, a separate notification is sent for each of them. Each peer can make an arbitrary reasonable number of subscriptions.
Via User API the user can subscribe only to modelevents.data_changed events.
Events of other classes are available to external systems via Token API (requests and responses are similar to those described here) and via HTTP webhooks.
An overview of notification channels, the differences between general events and data model events, and the approach to consistent data loading are in the article Notification channels from the system.
Requests and responses
To subscribe, send a subscribe request specifying the event class and accompanying identification information.
A subscription has a lifetime. Long cycles require regular subscription renewal. The recommended mode is a subscription with a unique identifier for a period of up to 3600 seconds, and then, in advance before the previous subscription expires, sending a request with the same identifier and the same period. Other fields may be omitted. For subscriptions with a 300-second period, the optimal resubscription time is after 240 seconds. For 3600-second subscriptions — after 3000 seconds.
A subscription may contain filters. Depending on the event class, filters may be set and applied differently.
If a request is sent with the identifier of an existing subscription, it is treated as renewal (with a non-zero 'expires' value) or unsubscription (with zero 'expires'). A subscription is deleted by sending a "subscribe" request with the identifier of the subscription of interest in the 'id' field and the value 'expires': 0. No access rights check is performed on deletion.
If a renewal request contains values of other fields ('events', 'objects', 'classpath', 'exargs') different from the original request, the subscription is changed according to the new data. This method of modification is not recommended because it can cause transaction collisions when processing dense event streams.
[
"subscribe",
{
"qid": "16066361-dfc0-49f6-b734-9b3dda09db22",
"objects": ...,
"events": ...,
"expires": ...,
"id": ...
"exargs": ...
...
}
]
-
events- list of events for filtering event types. A list of strings is specified, each representing a separate event type, for example "callevents.dlg_start". For some classes "callevents.*" may be specified. -
objects- list of objects for filtering events. The value "any" or a list of values may be specified, for example '["sipuser1","sipuser2"]'. -
expires- subscription lifetime in seconds. If necessary, the subscriber must renew the subscription by resending the request with a non-zero 'expires' value. -
id- subscription identifier. If not set in the request, it is generated automatically and is always returned in the response so that subscription management (renewal and deletion) is possible. -
exargs- object with specific subscription settings. When subscribing to "modelevents.data_changed", a filter, index, mask, operations list, and content mode can be set, see the article. -
classpath- for 'modelevents' class events, can be specified instead of 'objects' and contain the full class path (endpoint), for example "/rest/v1/model/my/Records" or "/rest/v1/uc/calls". -
timeout- optional. Wait time in milliseconds during which the server retries if the subscription service is unavailable (restart, switch to another server). Default 30000, maximum 120000. Value 0 — one attempt without retries.
Subscription to several events of one class and to several objects at once is allowed.
If the subscription service is temporarily unavailable, subscription, renewal, or deletion are not confirmed in advance: the server retries during the timeout time and responds as soon as the subscription service executes the request. If the wait time expires, a response with "success": false and "errormsg": "No response from wssubscr role" is returned; the request should be repeated later.
[
"subscribe_result",
{
"qid": "16066361-dfc0-49f6-b734-9b3dda09db22",
"success": true,
"id": ...,
"msg": "subscribed",
"domain": ...
}
]
-
success- subscription success flag. -
id- subscription identifier used to manage the subscription: renewal and deletion. It is also indicated in the corresponding notifications sent for this subscription. -
msg- subscription result. -
domain- domain in which the subscription was made.
Notifications
Notifications are sent to subscribers taking into account the specified objects, filters, and masks. They contain a 'data' field with content corresponding to the event type specification.
[
"notify",
{
"class": string,
"eventts": integer,
"sid": string,
"type": string,
"data": object
}
]
-
class- event class. -
type- event type. -
eventts- event timestamp. -
sid- subscription identifier (required for 'modelevents' class notifications, may be absent in others). -
data- event content according to the specification in the Events section.
[
"notify",
{
"class": "modelevents",
"type": "data_changed",
"eventts": 1692042096897,
"sid": "81edebaa-0189-f5cd-80e2-7cd30a921f58",
"data": {
"classname": "sipusers",
"classpath":"/rest/v1/uc/sipusers",
"eid": "57278625-5fa4-eb0c-fb53-f6fa26881f25",
"operation": "update",
"entity": {
"id":"57278625-5fa4-eb0c-fb53-f6fa26881f25","iduser":"e7adf0aa-05b7-8163-948c-3392a9660db9","lic":{"devices":123456789},
"login": "sip1",
"name": "SIP1Sip-{D}",
"phonenumber": "11",
"reg": 1,
"opts":{
"calltimesec": 37,
"dlgtimesec": 300,
"title": ""
}
},
"modifier_type": "user",
"modifier_id": "e7adf0aa-05b7-8163-948c-3392a9660db9"
}
}
]
Event classes
The following event categories are distinguished:
-
Data model change events - both static and dynamic (modelevents).
-
Telephony events (callevents) — Token API and webhooks only.
-
IVR script events (ivrevents) — Token API and webhooks only.
Notifications for project events generated in scripts are also possible.
modelevents class events
Events of this type are generated immediately when changes are made in the data model - both static (dc) and dynamic (dms). The class has a single event "data_changed". Detailed description of the class events is here.
When processing a "subscribe" request, authorization for the operation of reading collection elements is performed. Accordingly, the user must be assigned a role with permission for the route to the collection element endpoint with the 'GET' method.
The "notify" event delivers data about the performed operation, as well as the current value of the changed entity adjusted for the mask ('exargs.mask'). When creating a subscription with a filter ('exargs.filter'), events can be filtered. The filter and mask are specified in a form similar to the parameters of a REST GET collection request (more).
Delivered events for a specific entity are always reduced to "create", "update", and "delete" based on comparing the previous value and the new value with the filter. Thus, if the previous value did not match the filter and after the change it does, the event is delivered and has the "create" operation despite the fact that the actual operation was "update" or "replace".
Operation types:
-
create- the entity was created and matches the filter, or was changed so that it now matches the subscription filter. -
update- the entity was changed, and both values - previous and current - match the subscription filter. -
delete- the entity was deleted, or changed so that it no longer matches the subscription filter. -
reload- the request processing queue for the class was reloaded. To ensure integrity, a repeated REST request to select elements from the collection with the filter is required. -
clear- the collection was cleared. -
corrupt- a storage problem occurred while processing the entity request; the current entity state may be inconsistent and the entity must be updated via REST request.
A correct subscription request must contain exactly one object (class name or class path in the REST API) and exactly one event type — "modelevents.data_changed".
To specify a specific collection, the 'classpath' field is mainly used; in this case the 'objects' field is ignored.
With large event streams, using masks and filters can significantly reduce system load.
A large number of simultaneous subscriptions with different filters to the same collection can significantly increase system load.
The following approaches for working with class events may be used: * subscribing to a collection with a mask leaving only one or two fields, and a request to read the object when an event arrives. * subscribing without a mask and using the object directly from the event body. * subscribing for a short time while work with data is in progress. For example, subscribing to changes of a request object with a filter by identifier and state, creating a request object with this identifier, tracking the event of the request object moving to the state of interest, deleting the subscription. * caching objects: subscribing to a collection followed by reading data into the cache; then modifying cached data when events arrive; periodic full reading of data into the cache at a large interval.
[
"subscribe",
{
"qid": 0.15994723,
"id": "abcdabcd-abcd-abcd-abcd-abcdabcdabcd",
"events": ["modelevents.data_changed"],
"classpath": "/rest/v1/model/my/Records",
"expires": 300,
"exargs": {
"filter": ["==",["property","code"],"aaa"],
"mask": ["id","name"]
}
}
]
callevents class events
Telephony events. Available only in Token API and webhooks. Detailed description of the class events is here.
In the 'events' field, the callevents class events of interest may be listed, or the full mask "callevents.*" specified.
A filter by subscriber parties of the dialog mentioned in the event can be set in the 'objects' field.
[
"subscribe",
{
"qid": 0.105938272,
"id": "bcdebcde-bcde-bcde-bcde-bcdebcdebcde",
"events": ["callevents.*"],
"objects": ["11"],
"expires": 300
}
]
ivrevents class events
IVR script events. Available only in Token API and webhooks. Detailed description of the class events is here.
In the 'events' field, the ivrevents class events of interest may be listed, or the full mask "ivrevents.*" specified.
Practical benefit can be gained from the ivrevents.api_start and ivrevents.api_stop events, which notify readiness to transfer control by the script to an external module.
[
"subscribe",
{
"qid": 0.105938272,
"id": "cdefcdef-cdef-cdef-cdef-cdefcdefcdef",
"events": ["ivrevents.api_start", "ivrevents.api_stop"],
"objects": "any",
"expires": 300
}
]