API - General information¶

While1 Voice API is accessed at URL:¶

https://[YOUR-PBX-URL]/api/endpoint_name

Data is sent via POST or GET and must be of the form::¶

Array
(
    [data] => Array
        (
            [project_id] => 1
            [caller_id] => 0123456789
            [caller_id_name] => John Doe
            [type] => queue
            [destination] => test-queue
            [external_id] => asdf1234
            [async] => 1
            [outbound_number] => +40212345678
            [outbound_trunk] => default-trunk
            [vars] => Array
                (
                    [SKIP_WELCOME] => 1
                    [SKIP_WE_ARE_RECORDING] => 1
                    [SKIP_ENTER_QUEUE] => 0
                    [BACKEND_LINK] => https://[YOUR-EXTERNAL-CRM-URL]/?change_this_url=1234
                )

        )

    [api_hash] => 0f25e797e72d0dbba96d2c571a7bd6ba
)

HTTP Headers:¶

Content-Type: text/xml
Authorization: Bearer <token>

or

Content-Type: application/json
Authorization: Bearer <token>

Required parameters:¶

• api_token - It will be sent in the Authorization: Bearer <token> header
• api_key - Optional key used in the hash to validate the integrity of the data sent

The parameters are set from the PBX GUI, Settings :: Parameters section:

Supported formats:¶

• POSTFIELDS (form-data) via GET or POST
• JSON via POST, where the required header is Content-Type: application/json

While1 Voice API responds in JSON format¶

Example of parameters generation:

$params = array(
    'data' => array(
        'project_id' => 1,
        'caller_id' => '0123456789',
        'caller_id_name' => 'John Doe',
        'type' => 'queue', // user, queue, context
        'destination' => 'test-queue',
        'external_id' => 'asdf1234',
        'async' => 1,
        'outbound_number' => '+40212345678',
        'outbound_trunk' => 'default-trunk',
        'vars' => array(
            'SKIP_WELCOME' => 1,
            'SKIP_WE_ARE_RECORDING' => 1,
            'SKIP_ENTER_QUEUE' => 0,
            'BACKEND_LINK' => 'https://[YOUR-EXTERNAL-CRM-URL]/?change_this_url=1234', // for pop-up
        )
    )
);

Example of hash generation using api_key

$params['api_hash'] = md5(http_build_query($params) . 'your_api_key'); // make hash

Example of sending GET data (not recommended due to the ~2000 character limit of the URL):

$url = 'https://[YOUR-PBX-URL]/api/endpoint_name';
$token = 'your_api_token';
$context = stream_context_create(
    array(
        'http'=> array(
            'header' => "Authorization: Bearer {$token}\r\n" 
        )
    )
);

echo file_get_contents($url . '?' . http_build_query($params) , false, $context);

Example for sending POSTFIELDS data:

$url = 'https://[YOUR-PBX-URL]/api/endpoint_name';
$token = 'your_api_token';
echo curlPost($url, http_build_query($params), array("Authorization: Bearer {$token}"));

Example for sending JSON data:

$url = 'https://[YOUR-PBX-URL]/api/endpoint_name';
$token = 'your_api_token';
echo curlPost($url, json_encode($params), array("Authorization: Bearer {$token}", "Content-Type: application/json"));

curlPost function:

/**
 * @param string $url
 * @param array $postdata
 * @param array $extra_headers
 * @return bool|mixed
 */
function curlPost($url, $postdata, $extra_headers = array()) {
    if (!function_exists('curl_init')) {
        //error_log("PHP Warning: CURL is not installed. curlPost function will now exit");
        return false;
    }

    // init CURL
    $ch = curl_init();

    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_HEADER, false);
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
    curl_setopt($ch, CURLOPT_SSLVERSION, 1);
    curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 60);
    curl_setopt($ch, CURLOPT_TIMEOUT, 60);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $postdata);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_USERAGENT, 'Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1)');
    curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
    curl_setopt($ch, CURLOPT_MAXREDIRS, 5);

    if (!empty($extra_headers)) {
        curl_setopt($ch, CURLOPT_HTTPHEADER, $extra_headers);
    }

    // get response
    $output = curl_exec($ch);

    if ($output === false) {
        $error_code = curl_error($ch);
    }
    else {
        $error_code = 'N/A';
    }

    // get headers
    $headers = curl_getinfo($ch);

    // close connection
    curl_close($ch);

    // if request is OK, return contents
    if ($headers['http_code'] == 200 || $headers['http_code'] == 226) {
        return $output;
    }
    // return an error
    else {
        //error_log("PHP Warning: Bad CURL header ({$headers['http_code']}) on URL: {$url}, error code: {$error_code}");
        return false;
    }
}

Types of answers¶

The service will respond JSON with the following parameters:

• has_error: Boolean - true sau false
• messages: Array - the list of error messages, optionally with the error code in the key
• pagination: Array - details about the number of pages, the current page, etc.
• results: Array - list of results returned by the service

If successful:

{

    "has_error": false,
    "messages": [ ],
    "pagination": {
        "row_count": 1,
        "page_size": 100,
        "current_page": 1,
        "max_page": 1
    },
    "results": [
    ]

}

Or in case of error:

{

    "has_error": true,
    "messages": [
        "Token does not match" 
    ],
    "pagination": [ ],
    "results": [ ]

}

Atention: api_username and api_password have been replaced by the Authorization: Bearer <token> header¶

They will work until July 2024 but will issue a warning:

{

    "has_error": false,
    "messages": [ ],
    "warnings": [
        "API Username and Password are deprecated. Please use 'Authorization: Bearer $token' header" 
    ],
    "results": [
    ]

}

---

Available in other languages:: RO