API Events

This topic introduces the API events which are sent from Yeastar K2 VoIP PBX to the application server. We introduce two types of API events and the relevant communication protocols, communication ports, and interaction flow between the PBX and the application server.

API reports (events) settings

Yeastar K2 VoIP PBX supports to send HTTP events and TCP events.. You can go to API Settings on PBX, and select the report method.

HTTP events

Communication protocol: PBX sends HTTP events by short-lived TCP flows.; A new TCP connection will be established every time PBX sends an event. The application server should disconnect the TCP connection after receiving an event.

Communication port: When the application server sends the request of Get API token, the port parameter should be specified in the API request. port defines the monitoring port to receive events.. PBX will send events to the application server through this port.

Event format: JSON.

Requirements: The application server must send the request of Get API token to log in PBX. Token validity must be ensured, or the application server can not receive the events.

Interaction flow: The following figure shows the HTTP events flow between the application server and the PBX.

TCP events

Communication protocol: PBX sends TCP events by keep-alive TCP flows.
PBX will send events continuously till the TCP connection disconnects. When the network error occurs or the application server disconnects the TCP connection, the application server needs to establish a new TCP connection with the PBX.

Communication port: On the PBX API web interface, set the TCP port. PBX will send TCP events to the application server through this port.

Event format: JSON.

Requirements

The application server should establish a TCP connection with PBX, and send a login data to log in PBX. Only the login request is authorized will PBX send events.

Format of TCP login data is as follows:

Action: login
Username: {username}
Secret: {password}
Version: {version}

{username}: Username on PBX API web interface (Settings > General > API > Username).
{password}: Clear-text password on PBX API web interface (Settings > General > API > Password).
{version}: API version. In this documentation, the API version is 2.0.0.

Interaction flow: The application server acts as a TCP client, and the PBX acts as a TCP server.; The following figure shows the TCP events flow between the PBX and the application server.; Note: Login data in the following figure is for reference. You should send a TCP login packet using the username and password set on the PBX API web interface.