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