Introduction
At the end of this article, you will be able to configure API requests to the PBX. This feature is currently in Beta and only available to customers that have requested Beta features be activated on their account. Please note, API calls are limited to 100 queries per 15 minutes. Should you need any assistance, feel free to contact our support department.
Contents
- Obtain API Key for your account
- Whitelist IP address(es)
- [GET] /api/integration/v1/get-user-calls
- [GET] /api/integration/v1/get-queue-calls
- [GET] /api/integration/v1/get-ringgroup-calls
- [POST] /api/integration/v1/call-to-number
- [GET] /api/integration/v1/get-system-status
- Codes
Obtain API Key for your account
To make an API request, you will need the API key for your account. This can be found in the Billing tab in the customer portal in the customer details. Click the Edit details button and you will be able to copy the key to then paste into your API parameters.
Note: From 18/12/2020 we are moving the API key from a parameter to a HTTP Headers for additional security. The Header name is token and the value for this header should be the key copied above. Both methods the Header and Parameter method of authentication will work, giving you some time to update your API requests. The Parameter method will stop working in Jan 2021.
Whitelist IP address(es)
You will need to add the IP address(es) to the whitelist to allow access to make API requests to your PBX. If you attempt to send an API request from an IP, not in the Whitelist, you will get the following response.
To add an IP to the whitelist, from the PBX tab, click on Settings, then the Integrations tab, select API on the left menu and scroll down to the Whitelisted IPs section. Click the Add IP button.
Add the IP address(es) you require to have access to make API requests to your PBX. Each IP address should be added on its own line. Click the Add button once done.
Click Save on the Settings window, and then apply the configuration. You can now start to send API requests as detailed below.
[GET] /api/integration/v1/get-user-calls
This request will retrieve a list of calls for the user(s) specified. Calls will be sorted from newest to oldest.
Headers:
- Header Name: token - required Value should be your API Key.
Parameters:
- (string) api_key - required This method of authentication will be deprecated in JAN 2021
- (string) from_date - optional (default: '' - any time), in the format Y-m-d
- (string) to_date - optional (default: '' - any time), in the format Y-m-d
- (int) limit - optional (default: 100), the limit value should be in the range from 1 to 10000
- (int) offset - optional (default: 0), element number to get data from
- (string) users_names - optional (default: '' - all users), a comma-separated list of users names
Response Data:
- (string) from_number - number of caller
- (string) to_number - number the call was received on
- (string) user_name - name of User object who answered the call
- (int) is_inbound - is the call inbound or not
- (string) call_start_at - date and time when the call was started, in the format ISO 8601
- (int) call_duration - call duration is seconds
- (string|null) call_finished_at - null or date and time when the call was finished, in the format ISO 8601
- (int) conversation_duration - conversation duration is seconds
[GET] /api/integration/v1/get-queue-calls
This request will retrieve a list of calls to queues. Calls will be sorted from newest to oldest.
Headers:
- Header Name: token - required Value should be your API Key.
Parameters:
- (string) api_key - required This method of authentication will be deprecated in JAN 2021
- (string) from_date - optional (default: '' - any time), in the format Y-m-d
- (string) to_date - optional (default: '' - any time), in the format Y-m-d
- (int) limit - optional (default: 100), the limit value should be in the range from 1 to 10000
- (int) offset - optional (default: 0), element number to get data from
- (string) queues_names - optional (default: '' - all users), a comma-separated list of queue names
Response Data:
- (string) queue_name - name of Queue object
- (string) callerid - number of caller
- (string) inbound_number - number the call was received on
- (string) call_start_at - date and time when the call was started, in the format ISO 8601
- (string|null) call_answered_at - null or date and time when the call was finished, in the format ISO 8601
- (string) call_finished_at - date and time when the call was finished, in the format ISO 8601
- (string) answered_by_user_name - name of User object who answered the call if exists
- (string) status - status of the call (answered|abandoned|timedout)
[GET] /api/integration/v1/get-ringgroup-calls
This request will retrieve a list of calls to Ring-groups. Calls will be sorted from newest to oldest.
Headers:
- Header Name: token - required Value should be your API Key.
Parameters:
- (string) api_key - required This method of authentication will be deprecated in JAN 2021
- (string) from_date - optional (default: '' - any time), in the format Y-m-d
- (string) to_date - optional (default: '' - any time), in the format Y-m-d
- (int) limit - optional (default: 100), the limit value should be in the range from 1 to 10000
- (int) offset - optional (default: 0), element number to get data from
- (string) ringgroups_names - optional (default: '' - all users), a comma-separated list of ring group names
Response Data:
- (string) ring_group_name - name of Ring Group object
- (string) callerid - number of caller
- (string) inbound_number - number the call was received on
- (string) call_start_at - date and time when the call was started, in the format ISO 8601
- (string|null) call_answered_at - null or date and time when the call was finished, in the format ISO 8601
- (string) call_finished_at - date and time when the call was finished, in the format ISO 8601
- (string) answered_by_user_name - name of User object who answered the call if exists
- (string) status - status of the call (answered|abandoned|timedout)
[POST] /api/integration/v1/call-to-number
This request will launch a call to the user, which once answered will then call the number specified.
Headers:
- Header Name: token - required Value should be your API Key.
Parameters:
- (string) api_key - required This method of authentication will be deprecated in JAN 2021
- (string) user_number - required user number to call
- (string) number_to_call - required number to call from user
[GET] /api/integration/v1/get-system-status
This request will retrieve the current system status as reported by the VoIPcloud NOC.
Headers:
- Header Name: token - required Value should be your API Key.
Parameters:
- (string) api_key - required This method of authentication will be deprecated in JAN 2021
Codes
Code | Description |
---|---|
200 | Success |
400 | Parameters error |
401 | Authorization error |
404 | Tenant or required data not found |
429 | Too Many Requests |
0 | Unknown error |