Project

General

Profile

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