Introduction
At the end of this article, you will be able to integrate API and Webhooks triggers of calls from our PBX system to your preferred system. Should you need any assistance, feel free to contact our support department.
Configuring API integrations
API integration is the connection between two or more applications via APIs, which allow the systems to exchange data. By using this feature, you will be able to integrate your phone system to CRMs, management software, and other systems. To configure the API integration, firstly, click on the "Integration/API" tab and select the API option from the left-hand menu. To locate and protect your account in our system, an API key is generated. Copy and paste this API key into the header of your API request. Further, as an extra security layer, add the public IP where the API request is coming from by clicking the button "add IP" to have it whitelisted. Please note, you must list the IP from which the API request comes, otherwise, 401 - Not authorised response will be sent.
As an example, the API key has been added to the header of the API request. The system will compare if the API key matches and responds to the request.
Currently, our system supports four main types of requests:
Get Method
- Get user calls
- Get queue calls
- Get ring group calls
POST method
- Call a number
The example below shows a "get user calls" request. Once your IP address is whitelisted and the API key is in the header of your API request, the next step is defining the parameters. To obtain the user call details, firstly, define the date, how the calls will be sorted and the user(s) you would like to receive the call information. The offset parameter shifts the position of the calls you would like to receive, and the limit parameter defines how many will be shown.
For example, if a user has placed 100 calls, select the range from the 50th call to the 80th by setting 50 in the offset field and 30 in the limit. Then, copy the full request URL and paste it into your API request. Further, click on the "test API request" button to view the form of response when sending a get user request.
The "get" response includes a unique call ID, type of call, caller ID, caller name, destination number, user name, user's extension number, date, and duration of the call in seconds.
Similar to the "get ring group" calls, the queue calls details can be sent via an API request as well. To get the queue call information, firstly, define the date, how the calls will be sorted and the queue(s) you would like to receive the call information. The offset parameter shifts the position of the calls you would like to receive, and the limit parameter defines how many will be shown.
For example, if a queue has received 100 calls, select the range from the 50th call to the 80th by setting 50 in the offset field and 30 in the limit. Then, copy the full request URL and paste it into your API request. Further, click on the "test API request" button to view the form of response when sending a get-user request.
The queue API response template is shown in the image below. Information such as caller ID, date, call duration, user, and status of the queue is sent when requesting get queue calls.
Lastly, the POST call to a number request will place a call from the selected user to the entered number. On this request, select a user from the dropdown list and type the destination number following the E.164 format, as shown in the image below. Fill in the missing fields to generate a code in JSON format to be sent in the request body.
Once the POST request has been sent, the user will receive a call showing the destination number as the caller ID. If answered, a call will be placed to the destination number. In the case the user has more than one SIP device, all devices will receive the call at the same time until it times-out or is answered by one of the SIP devices.
Configuring Webhooks
Global webhooks can be configured to trigger various event types across the entire PBX. To configure the Webhook integration, firstly click on the "Integration/API" tab and select the Webhooks option from the left-hand menu. Then, enter the URL of the server to receive the webhook events in the URL field, and a string in the Secret Token field. This will be sent with each request via the HTTP header X-Pbx-Token for your server to validate. Next, select the tick box next to each event you would like to trigger a webhook event for, see below for further information on the details of each event. Please note, every time you make a change in the webhook section, you must apply configuration in your call flow.
If you are unsure of how to apply configuration in your call flow, click on the PBX tab and press the red button "apply configuration" as shown in the following image.
Webhook triggers
A short description of each triggered event currently supported can be found below:
- User inbound call: Webhook event is triggered when a call reaches a User Object and starts ringing. If the User is chosen via a Queue or Ring Group, the details of the object that the user is configured on will also be passed in the event.
- User inbound call answered: Webhook event is triggered when a call is answered by a User.
- User inbound call completion: Webhook event is triggered when a call to a User is completed.
- Queue call summary: Webhook event is triggered when call delivered via a queue object has ended.
- Ring group call summary: Webhook event is triggered when call delivered via a ring group object has ended.
- Voicemail: Webhook event is triggered when Voicemail is left.
- Inbound call recording: Webhook event is triggered when an inbound call has completed recording.
- User outbound call: Webhook event is triggered when a User initiates an outbound call.
- User outbound call answered: Webhook event is triggered when an outbound call from a user is answered by the called party.
- User outbound call completion: Webhook event is triggered when an outbound call from a user has ended.
- Outbound call recording: Webhook event is triggered when an outbound call has completed recording.
On the Webhooks configuration screen, select the webhooks triggers you wish to receive the data in JSON format. Additionally, by clicking on the dropdown list and selecting one of the triggers, a webhook response will be presented including the data type and its response to the triggered event. The text below the code shows a brief description of the variables presented in the JSON code.
As an example, the request below has been triggered by a "user inbound call" request. In this request, it is possible to identify the origin of the request, host, x-PBX-token, and call details. Within the call details, the caller ID, type of call, user name, user's extension, destination number, date, and queue information is presented. This data can be used and manipulated according to your business's needs to enhance your telephony system.
Webhook component event
Lastly, you may wish to customise a Webhook by using a Webhook object in the call flow. To set this up, select the PBX tab, click on "advanced options" from the left menu, and drag and drop the Webhook object onto the main screen. See attached image below of a customised webhook event that has triggered a call time-out of the queue. Headers can be configured on the object as required. The object can be placed anywhere in the call flow to meet your specific requirements.
The following HTTP Headers are sent with the webhook event, along with any additional headers defined on the webhook object;
x-pbx-token - The value defined in the Secret Token field on the webhook object
The following JSON data is sent with the webhook event;
(string) type - webhook_component_event
(string) unique_call_id - unique identifier of the call
(string) user_name - CNAM of the caller
(string) user_number - CallerID of caller (CLI)
(string) dest_number - phone number call was received on
(string) call_start_at - date and time when the call arrived on the PBX, in the ISO 8601 format
(string) component_name - name configured on the Webhook object
