API - OriginateCall¶
API Originate Call se foloseste pentru a initia apeluri catre clienti via extensiile logate in centrala.
Procesul se face in trei pasi:¶
- Originate call: transmiterea in centrala a numarului destinatie (caller_id) si a userului / cozii / contextului (destination)
- Primul apel: centrala suna intai telefonul agentului sau clientul, in functie de type (vezi tabelul de mai jos)
- Al doilea apel: cand primul apel este preluat, centrala il conecteaza cu destinatia
Ordinea apelurilor in functie de type¶
| type | destination | suna intai | apoi |
|---|---|---|---|
| user | username-ul userului din While1 Voice | telefonul agentului | clientul (caller_id) |
| user_email | emailul userului din While1 Voice | telefonul agentului | clientul (caller_id) |
| queue | numele cozii | clientul (caller_id) | coada (primul agent liber) |
| extension | extensia din contextul internal | clientul (caller_id) | extensia |
| context | contextul din dialplan | clientul (caller_id) | contextul |
Click-to-call din CRM (suna intai agentul, apoi clientul): folositi type = user sau user_email.
API URL¶
https://[YOUR-PBX-URL]/api/originate-call
Datele se transmit 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
[external_info] => some test call
[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
)
Parametri:¶
- project_id: ID proiect in While1 Voice, obligatoriu
- caller_id: numarul de telefon destinatie conform regulilor de outbound din centrala, obligatoriu
- caller_id_name: nume destinatar, obligatoriu
- type: tipul actiunii - user, user_email, queue, extension, context, obligatoriu (vezi "Ordinea apelurilor in functie de type")
- destination: username-ul (type user), emailul userului (type user_email), coada (type queue), extensia (type extension) sau contextul (type context) din While1 Voice, obligatoriu
- external_id: ID-ul din aplicatia proprie partener (ex: ID ticket / client), salvat pe apel si folosit pentru interogari ulterioare prin API - Call Detail Records - CDR, recomandat
- external_info: text informativ pentru descrierea external_id
- async: daca operatiunea se executa asincron (1) sau nu (0), optional, implicit 0
- outbound_number: numarul care este afisat catre destinatar, optional
- outbound_trunk: providerul prin care se face apelul, optional
- vars: array cu diferite variabile pentru contextul din PBX, optional
Nota: daca optiunea async este 1, API va raspunde imediat. Pentru type user / user_email se verifica inainte ca telefonul userului sa fie online, iar pentru type queue ca coada sa aiba locuri libere (nu este garantat ca apelul a fost preluat). Pentru extension / context nu se face nicio verificare.
Daca optiunea async este 0, API va tine conexiunea deschisa pana cand primul apel (vezi tabelul) este preluat, respins sau expira, returnand eroare sau success.
Headere HTTP:¶
Content-Type: application/json Authorization: Bearer <token>
Exemplu generare parametri:
$params = array(
'data' => array(
'project_id' => 1,
'caller_id' => '0123456789',
'caller_id_name' => 'John Doe',
'type' => 'queue', // user, queue, context, extension, user_email
'destination' => 'test-queue',
'external_id' => 'asdf1234',
'external_info' => 'some test call',
'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:
$params['api_hash'] = md5(json_encode($params) . 'your_api_key'); // make hash
Exemplu trimitere date:
$url = 'https://[YOUR-PBX-URL]/api/originate-call';
$token = 'your_api_token';
echo curlPost($url, json_encode($params), array("Authorization: Bearer {$token}", "Content-Type: application/json"));
Date trimise JSON¶
{
"data": {
"project_id": 1,
"caller_id": "0123456789",
"caller_id_name": "John Doe",
"type": "queue",
"destination": "test-queue",
"external_id": "asdf1234",
"external_info": "some test call",
"async": 1,
"outbound_number": "+40212345678",
"outbound_trunk": "default-trunk",
"vars": {
"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": "a397d9c156faf7c90a18c12ad9a4beaf"
}
Raspuns¶
In caz de succes:
{
"has_error": false,
"messages": [ ],
"results": [
{
"originate_result": "Call successfully originated for queue: test-queue"
}
]
}
Sau in caz de eroare:
{
"has_error": true,
"messages": [
"Invalid Queue. Check if pbx queue exists"
],
"results": [ ]
}
Rezultatul apelului¶
API-ul nu returneaza ID-ul apelului (uniqueid). Pentru a afla rezultatul (uniqueid, call_status: ANSWERED / NO ANSWER / BUSY / FAILED, durata, inregistrarea etc.), trimiteti un external_id la originate-call si, dupa terminarea apelului, cititi detaliile prin API - Call Detail Records - CDR folosind filtrul external_id.
Disponibil si in alte limbi: EN