Event Subscriptions
V2 Changes Overview
While not new to v2, event subscriptions received some improvements. V2's most notable improvement is the ability to make a subscription more resilient and support redundancy, with the subscription capable of moving between servers if needed for failures. In v2, you can also see the status of the subscriptions, counters of posts sent and errors, and set (or change) a preferred server for the events to be sent from.
Getting Started with Subscriptions
To begin receiving events, you must have a publicly accessible web address or a locally connectable one that our servers can access. Ideally, it should be open from any of the clustered servers to avoid connection issues in failover scenarios. We highly recommend securing the server using HTTPS, but HTTP can also be used if you connect locally or over a secure network. Both protocols support custom ports. This URL will be used as the endpoint for posting data and will be referred to as the "post-url."
Next, you should determine the data type you want to receive. These "models" are documented on the following page and will dictate the nature of the data and the timing of its delivery. It's important to note that some data streams may have high volumes, so ensure your system is prepared to handle the data before configuring the URL.
You must also specify the scope of the data you want and the associated resources (resellers, domains, and users). Access permissions should align with the desired scope; for example, setting the domain to "*" would typically require reseller or superuser permissions.
Consider whether you want to enable geo support. Opting for "yes," which is the new v2 default, is recommended unless you intend to subscribe to multiple servers and manage deduplication independently.
All data posts will be transmitted in JSON format, organized as an "array" of "objects." The structure of these objects will be specific to the chosen model.
Please feel free to ask if you require further assistance or clarification.
This create process is further documented via the API reference page at Create Event Subscription
Available Models
| Model | Description |
|---|---|
| agent | This model will send an event every time an agent entry changes. This will show the agent's availability changes and queue changes. Both the user- and device-based agents will be shown. |
| auditlog | This model will stream one entry per entry in the audit log after they are recorded. It should be used with super user scoped only. For domain filtering, the "target_domain" will be filtered. |
| auditlog_lite | This model is a streamlined version of the auditlog model, with a focus on creating and deleting just a few key objects often used for billing. The objects include domain, user, reseller, call queue, agent, conference, and phone number. Note: the phone number will only be sent on changes from API (v1 or v2) and not from admin UI changes. |
| call | This model will send all active call information for all the call events that match the domain and user of the filters. This means one event for every change to the call, including creation, updates, and removal. Look for "remove: yes" when the call object is being removed. |
| call_origid | This model is similar to "call," but it is only keyed off of changes to the orig_callid. This means that you will not get as much data, including things that happen on the term side of the call, like events for multiple users being rung and transfers. |
| cdr | This model will send you one event after the call. This is useful if you need to know when calls are complete to trigger follow-up work or review other needed information, such as transcriptions, call recordings, etc. |
| message | This model will send 1 event per message received for chat or SMS. It should be used in conjunction with the user and domain to limit it to a single user. |
| messagesession | This model will send 1 event per session being updated. This could include a new message event or a mark of the session being read. |
| subscriber | This model will update each time a subscriber is updated and will include most of the fields for a user. |
| presence | This model is similar to "subscriber," but a more limited dataset will be posted, focusing on user, name, status, and presence changes. |
| voicemail | This model will send 1 event per voicemail recorded for a user. There is some built-in delay, so the transcription should be available, but it is not guaranteed based on vendor latencies. If transcriptions are needed, your application should queue up an API call to read the voicemail again if needed. |
Redundancy
The new logic begins by synchronizing the status of all nsnode applications, which is used by the API to transmit data. This synchronization ensures that all servers are aware of which applications are running and stable, as well as identifies any servers that may be offline. To assume control of a subscription, a server must demonstrate stability for a continuous period of 60 seconds and have the fewest active subscriptions. In cases of tie-breakers, predefined random information is used, ensuring each server has a predictable next-fail option. Additionally, a new field has been introduced in the v2 dataset, allowing for the designation of a preferred server and the ability to view the current server.
Authenticating and Validating Posts
In certain scenarios, it may be necessary to safeguard your web application against undesirable data. The simplest approach is to restrict incoming traffic solely to the known IP addresses within the cluster. Moreover, starting with V2, a new header called X-Correlation-ID will be introduced, containing the subscription ID. By ensuring the confidentiality of this value, you can employ it to validate incoming posts. In cases where multiple subscriptions target the same URL, this header can also be used for matching purposes.