Project

General

Profile

API - Prezentare generala

While1 Voice API se acceseaza la URL:

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

Datele se transmit prin POST sau GET si trebuie sa fie de forma (exemplu pentru API - OriginateCall):

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

sau cu api_hash (daca parametrul api_key este completat in Settings - Parameters)

Array
(
    [data] => Array
        (
        ...
        )
    [api_hash] => 0f25e797e72d0dbba96d2c571a7bd6ba
)

Headere HTTP:

Pentru POSTFIELDS

Content-Type: application/x-www-form-urlencoded
Authorization: Bearer <token>

Pentru JSON

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. Daca este completat, parametrul api_hash devine obligatoriu
  • api_limit - optional, numarul maxim de request-uri pe zi, cumulat pentru toate API-urile. Peste 75% din limita raspunsul contine warnings, iar la depasire se intoarce eroarea API usage limit exceeded (cheia usage_limit in messages)

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 (se accepta si application/json; charset=utf-8)

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

api_hash se calculeaza pe toti parametrii trimisi (fara api_hash), concatenati cu api_key. Se accepta oricare din variantele de mai jos, indiferent de formatul trimis. Pentru varianta JSON, hash-ul se compara cu rezultatul json_encode din PHP (slash-urile escapate ca \/, caracterele non-ASCII ca \uXXXX); din alte limbaje este mai simplu de reprodus varianta http_build_query.

Exemplu calculare api_hash folosind api_key + http_build_query (optional):

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

Exemplu calculare api_hash folosind api_key + json_encode (optional):

$params['api_hash'] = md5(json_encode($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')) {
        throw new \Exception("PHP Warning: CURL is not installed");
    }

    // 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 {
        throw new \Exception("Bad CURL header ({$headers['http_code']}) on URL: {$url}, error code: {$error_code}");
    }
}

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
  • warnings: Array - avertizari (ex: limita de utilizare aproape atinsa), doar daca exista
  • pagination: Array - doar la API-urile care intorc liste: numarul de rezultate (row_count), marimea paginii (page_size, 100), pagina curenta si ultima pagina (max_page). O pagina mai mare decat max_page intoarce tot ultima pagina, deci paginarea se opreste la max_page
  • 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,
        "first_displayed_page": 1,
        "last_displayed_page": 1
    },
    "results": [
        {
            "id": "12",
            "name": "John Doe" 
        }
    ]

}

Sau in caz de eroare:

{

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

}

Continutul results depinde de API, vezi paginile fiecarui API.

Erori de autentificare posibile:

  • API Token not set in Parameters - parametrul api_token nu este setat in centrala
  • API Token is required - lipseste header-ul Authorization: Bearer <token>
  • API Hash is required - api_key este setat, dar nu s-a trimis api_hash
  • Token does not match - token invalid
  • Hash is invalid - api_hash calculat gresit
  • API usage limit exceeded (N) - limita zilnica api_limit a fost depasita

Dupa mai multe incercari esuate (token sau hash gresit), accesul este blocat temporar.

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

Acestea vor functiona ca deprecated si 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