Monitor Events via WebSocket

To monitor the PBX events in real-time, the third-party application needs to establish a WebSocket connection and subscribe to the desired events. This topic introduces the request commands that are used to create a WebSocket connection and subscribe to events, thus implement instant PBX event monitoring.

Prerequisites

A valid access token is required for establishing a WebSocket connection.
Note: You can obtain a new access token using Get Access Token or Refresh Access Token.

Establish a WebSocket connection

First of all, you need to send a request URL to request for establishing a WebSocket connection.
Request URL
To establish a WebSocket connection, you need to use the special protocol wss in the request URL:
wss://{pbx_domain}/{api_path}/subscribe?access_token={access_token}
Example
Request

wss://yeastardocs.example.yeastarcloud.com/openapi/v1.0/subscribe?access_token=QJZDwxIAXBoVrUmeyLiHS3zQXrdynAmh

Subscribe to the desired events

Once the connection is established, you need to compose and send messages to subscribe to desired events. In this way, the PBX will automatically report the subscribed events to the third-party application.

Request message
Query the desired event ID in API Event Summary, and compose the event subscription message in the following format:
{"topic_list":[eventid1,eventid2,...]}
Example
Request
Subscribe to the events of Call Status Changed and New CDR.
{"topic_list":[30011,30012]}
Response
{
    "errcode": 0,
    "errmsg": "SUCCESS"
}
The PBX sends event reports to the third-party application when the call status changes or a call ends.

Keep WebSocket connection alive

For security purpose, if there is no interaction between the third-party application and PBX for 60 seconds, the WebSocket connection will be automatically disconnected.

If you want to maintain a persistent WebSocket connection, use the heartbeat request to keep the connection alive.
Request message
heartbeat
Example
Request
heartbeat
Response
heartbeat response