Skip to Content

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 open a WebSocket connection, you need to use the special protocol ws or wss in the request URL according to the web access settings on your PBX.

  • If the web access protocol of PBX is HTTP, use the following request URL:

    ws://{pbx_ip}:{http_port}/{api_path}/subscribe?access_token={access_token}

  • If the web access protocol of PBX is HTTPS, use the following request URL:

    wss://{pbx_ip}:{https_port}/{api_path}/subscribe?access_token={access_token}

  • If you use the FQDN for remote API access, use the following request URL:

    wss://{pbx_fqdn_domain}

    Note: To remotely access API via Cloud One FQDN, you need to configure API remote access. For more information, see Configure Network for Remote API Access by a Cloud One FQDN.

Example

Request

wss://192.168.5.150:8088/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

Related information