Skip to Content

API Events Overview

Cloud One Business Communication Suite API events provide comprehensive event-logging and change-tracking to help you monitor the PBX resources. You can choose either WebSocket or Webhook as the event monitoring method and subscribe to desired PBX events as needed, then the Cloud One Business Communication Suite would proactively send event reports to the third-party application once the related event occurs.

WebSocket monitoring

WebSocket is a computer communication protocol that provides a persistent, full-duplex communication between a server and a client over a single TCP connection.

After the third-party application establishes WebSocket connection with Cloud One Business Communication Suite and subscribes to desired events, it will receive event-driven responses without having to poll the PBX for a reply, thus achieving real-time monitoring. For more information, see Monitor Events via WebSocket.

Restriction

  • The WebSocket connection expires after 60 seconds.
  • If there is no interaction between the third-party application and PBX for 60 seconds, the WebSocket connection will be automatically disconnected.
  • Note: You can use a heartbeat request to keep the WebSocket connection alive.

  • The WebSocket connection establishment requires a valid access token, which will expire after 30 minutes.

    You will need to get a new access token or refresh the access token to maintain the WebSocket connection.

WebSocket workflow

Data interaction between client (third-party application) and server (Cloud One Business Communication Suite) via WebSocket is shown below:

For the initial handshake, the third-party application sends a request through HTTP to request an upgrade to WebSocket. PBX responds an HTTP status code 101, indicating that the protocol will be switched from HTTP to WebSocket. After a successful upgrade, the communication occurring through this active TCP connection follows the WebSocket Protocol.

During the connection, both the PBX and the application can send each other messages whenever they wish for the whole duration of the WebSocket connection. If either side closes the connection, the WebSocket connection will be terminated.

Webhook monitoring

Webhook is an HTTP-based callback mechanism, which allows the PBX to actively push notifications to a predefined URL in real-time when specific events occur. For more information, see Monitor Events via Webhook.

Webhook workflow

After configuring the Webhook URL and specifying the subscribed events on the PBX web portal, the PBX will automatically send event details to the third-party application when specified events occur. Every time the PBX sends a event notification, the third-party application should return a successful HTTP response (2xx) to acknowledge successful receipt of the message.

Supported events

Cloud One Business Communication Suite offers a comprehensive set of events to which developers can subscribe. Such events include but is not limited to the following:

  • Status and configuration change of features, including extension, trunk, organization, etc.
  • Call status of extensions
  • Inbound call notifications
  • Call activity details
  • Call records
  • Satisfaction survey results

You can check the whole set of events in API Event Summary.

Related information