API Change Logs
When sending an API request, the request address must include the API version. All request samples in this guide use {api version} to represent the API version.
API Overview
Yeastar S-Series VoIP PBX provides API interfaces for you to integrate a 3rd party application server. After the integration, you can achieve variable call features on the 3rd party application server and the PBX will automatically send API reports to the 3rd party application server.
This section is applicable for users who are new to the Yeastar S-Series VoIP PBX API. In this section, we introduces the pre-configurations before using the API, API communication methods and protocols, API request structure, and response result.
Enable API Access on PBX
Before you start, enable API access on the PBX first.
Enable CORS for a REST API Resource
Cross-region Resource Sharing (CORS) is a browser security feature that restricts cross-region HTTP requests that are initiated from scripts running in the browser. If you can not access API and receive an error message indicating the cross-region request was blocked, you need to enable CORS. This topic describes how to enable CORS for a simple request.
Delete Blocked API IP
If an IP exceeds the allowed failed API login attempts, PBX will block the IP and tag the blocked IP as API-IP. You can delete the blocked API IP if the IP is trusted.
Communication Methods
Yeastar S-Series VoIP PBX communicates with the 3rd-party application server by two methods.
Request Structure
This topic introduces the structure of API requests, including request method, request URL, and communication protocol.
Response Results
Yeastar S-Series VoIP PBX returns the API responses in JSON format.
API Reports
After the 3rd-party application server is connected to the Yeastar S-Series VoIP PBX via API interface, PBX will automatically sends API reports to the 3rd-party application server.
API Demo
Yeastar provides an API demo and sample configurations for you to test the API functions with Yeastar S-Series VoIP PBX.
Login
Enable API access on the Yeastar S-Series VoIP PBX, then access the PBX by the API username and the encrypted MD5 API password.
Heartbeat Packet
With heartbeat packet, Yeastar S-Series VoIP PBX can update IP, Port, and URL of the connected 3rd party application server if there are any changes.
Query PBX Information
Query PBX information, such as firmware version, system time, etc.
Send SMS Messages
Send SMS messages through a GSM/3G/4G trunk.
Download Recording Files
Get a random string of the recording file, then combine the random string with other parameters to form a download link.
Download CDR Files
Get a random string of the CDR file, then combine the random string with other parameters to form a download link.
Hotel Check Out
Through this interface, you can perform checkout for the hotel customers.
'Changed Extension Status' Report
The PBX will send a report to the application server when the extension status changes.
'Ring Back' Report
The PBX will send a report to the application server when the called party (extension/inbound call) rings back the calling party.
'Answer a Call' Report
The PBX will send a report to the application server when an extension answers a call. Answering call (the called party) and call answered (the calling party) coexist. In the report, the calling party's number will appear first.
'Call Answered' Report
The PBX will send a report to the application server when the calling party's call is answered. Answering call (the called party) and call answered (the calling party) coexist. In the report, the calling party's number will appear first.
'Call Released' Report
The PBX will send two "BYE" reports to the 3rd-party application server when a call is released. In the first "BYE" report, the user who releases the call will appear first.
'Call Transfer' Report
When there is a call transferred inside the PBX, the PBX will send a report to the application server.
'Call Failure' Report
Generally, call failure event will appear in the response message of the API request. In certain circumstances, the PBX will send the report. Call failure is defined as calls that are failed to connect. Failure of calls initiated manually and by the API will both be reported.
'Keypress' Report
This event is used report key pressed (DTMF information) during a call.
CDR Report
CDR is raw data of all call activities. Records of all calls from the beginning to the end will be kept. When a call is released, the PBX will send a report to the application server in real time.
'Inbound Call Request' Report
If the trunk's API has Control Inbound Call Answering enabled, then whenever there's a call to this trunk, the PBX will send an INVITE event to the application server.
'Inbound Call' Report
If the trunk's API has Control Inbound Call Destination enabled, then when the trunk answers the call, the PBX will send an Incoming event to the application server.
'Prompt Play End' Report
Report the event when the prompt played to the extension and the external number ends.
'Customer Satisfaction Survey Result' Report
Once the DTMF pressed is collected from callers, API will send the customer satisfaction survey result to the client automatically.
Hotel APIs
Connect Hotel Property Management System and Yeastar S-Series VoIP PBX via API to achieve automate hotel operations, such as extension management, wake-up service, statistics for call and mini-bar consumption, change of room's clean status, check-out and so on.
Dispatching System APIs
Connect Dispatching System and Yeastar S-Series VoIP PBX via API to dispatch tasks by one-way paging, one-way multicast paging, or two-way intercom via phone terminals.
Call Center APIs
Connect Call Center System and Yeastar S-Series VoIP PBX via API to achieve multiple operations, such as automatic call distribution, agent management, daily communication, and satisfaction survey.
IVR Alarm System APIs
Connect Alarm System and Yeastar S-Series VoIP PBX via API to provide alarm service via IVR prompts.
Voice Interactive Service APIs
Connect Yeastar S-Series VoIP PBX and Application System to offer customers voice interactive service.
Error Code
References of API error codes.