API request object

Introduction

At the end of this article, you will be able to integrate and configure the API object within your PBX system. Should you need any assistance, feel free to contact our support department.

Configuring API request object

The API request object allows you to alter the route of a call or add string caller ID prefixes based on a plain text document. By using this feature, you will be able to change a plain text document to redirect calls without making changes to your call flow.

To configure the API request object, click on the "PBX" tab and select the API request object from the left-hand side menu under advanced options. Next, drag and drop the object onto the main screen and click on the settings icon.

Then, enter a descriptive name for the object and insert the URL to which the plain text document is hosted. Please note, some hosting systems add characters to the text document, impacting the functionality of the feature. Further to this, invalid SSL certificates also affect the API request object. Following this, you can add a secret token to avoid public access to the hosted document, therefore, the API request will utilise this secret token to access the file. Once the URL details are configured, select the mode in which the API should behave, number, or name.

Number mode: In this mode, all calls that reach the API request object will be sent to the internal or external number included in the plain text file. This allows you to divert calls to mobile or internal extensions only by editing the text file instead of changing the call flow. Please note, it's only possible to set one number or extension per time, if you add more than one number, the calls will be sent to the "failed" path.
Name mode: In this mode, the system will add the caller ID to the call with the text received from the plain text file. Please note, the maximum length is 14 symbols (including whitespace digits).

Lastly, double-check the information entered, save it, and click the Apply Configuration button as shown in the image below.

API request object usages

The following call flow represents the usage of the API request feature in number mode. For this, a PHP file was hosted in a web server with the "API USER" internal number, 1050. This means all calls should be routed to user 1050, and if the PHP file is removed from the entered URL, all calls will follow the "Failed" path.

The image below shows the PHP file which contains a simple text file with "1050" without any whitespace or characters. Please note, text documents on Google Drive, Dropbox, and GitHub will not work.

In summary, we can observe that the incoming calls were routed to user 1050, despite there being no connection between the user and the call flow. This feature is handy in diverting calls to external numbers or queues in a hasty manner.

Now, switching to the name mode, the text file's added to the caller ID. To apply the name mode changes, select name, save, and click the Apply Configuration button as shown in the image below.

Head back to the PHP file, which now contains "Support" on the text file. The "Support" text will be displayed on the agents' device as a caller ID. The feature is particularly useful for agents who answer calls from different departments, such as sales, support, accounts, etc, making the calls recognisable. Please note, the maximum length is 14 symbols, including whitespace characters.