API - Prezentare generala¶

While1 Voice API se acceseaza la URL:¶

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

Datele se trasmit prin POST sau GET si trebuie sa fie de forma:¶

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
)

Headere HTTP:¶

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

sau

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

Parametri necesari:¶

• api_token - Se va trimite in header-ul Authorization: Bearer <token>
• api_key - Key optional folosit in hash-ul pentru validarea integritatii datelor trimise

Parametrii se seteaza din interfata de administrare a centralei, sectiunea Settings :: Parameters:

Formate acceptate:¶

• POSTFIELDS (form-data) prin GET sau POST
• JSON prin POST, unde este necesar header-ul Content-Type: application/json

While1 Voice API raspunde in format JSON¶

Exemplu generare parametri:

$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
        )
    )
);

Exemplu generare hash folosind api_key:

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

Exemplu trimitere date GET (nerecomandat din cauza limitei de ~2000 caractere a URL-ului):

$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);

Exemplu trimitere date POSTFIELDS:

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

Exemplu trimitere date JSON:

$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"));

Functie curlPost:

/**
 * @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;
    }
}

Tipuri de raspuns¶

Serviciul va raspunde JSON cu urmatorii parametri:

• has_error: Boolean - true sau false
• messages: Array - lista mesajelor de eroare, optional avand in cheie codul de eroare
• pagination: Array - detalii despre numarul de pagini, pagina curenta etc
• results: Array – lista rezultatelor returnate de serviciu

In caz de succes:

{

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

}

Sau in caz de eroare:

{

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

}

Atentie: api_username si api_password au fost inlocuite de header-ul Authorization: Bearer <token>¶

Acestea for functiona pana in Iulie 2024 dar vor emite o avertizare:

{

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

}

---

Disponibil si in alte limbi: EN