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

 

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.

 

 

mceclip0.png

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.

 

mceclip0.png

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.

 

mceclip0.png


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.


mceclip0.png


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.


mceclip1.png


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

mceclip2.png

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

mceclip3.png

 

[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)

mceclip4.png

 

 

[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)

mceclip1.png

 

[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


mceclip0.png

 

[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

mceclip1.png

 

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