API notificări apel

Acest API permite notificarea unui sistem extern asupra apelurilor în derulare. Notificările sunt cereri HTTP sau HTTPS pe care Accolades le inițializează către un server web, atunci când unul dintre evenimentele urmărite are loc.

Se pot transmite notificări pentru următoarele evenimente:

Activare și configurare

Acest API trebuie activat, la nivel de utilizator (telefon), individual.

Interfața pentru managementul serviciului este disponibilă în fișa utilizatorului (pentru care se activează), tabul API.

Pentru a rula corect sunt necesare următoarele informații:

Configurarea incorectă va determina închiderea apelurilor, în momentul în care acestea se proceseaza de Accolades (de exemplu, dacă fișierul către care se transmite notificarea nu există).

Structură notificare

O notificare se transmite sub forma unei cereri HTTP sau HTTPS către serverul indicat în interfața de configurare.

Informațiile despre apel se transmit sub forma unor parametrii POST:

apiName
("callNotification") Denumirea api-ului care a generat notificarea (se poate utiliza pentru a putea diferenția mesajele transmise de diversele sisteme API Accolades, în cazul în care acestea se procesează se același script de pe serverul unui client).
event
("answer", "confirmHangup" sau "hangup") Tipul de eveniment care a generat notificarea. Poate avea valorea "answer" (s-a raspuns la un apel) "confirmHangup" (durata limită pentru apel a expirat, serverul întreabă clientul dacă apelul se închide sau se prelungește cu o nouă durată) sau "hangup" (s-a inchis un apel).
callId
(text de forma numeric.numeric) Identificatorul unic pe care îl are apelul în sistemul Accolades. Valoarea se poate utiliza pentru a se corela notificările multiple care apartin unui singur apel (ex: evenimentul "answer" cu evenimentul "hangup").
userId
(numeric) Identificatorul unic pe care îl are entitatea (telefonul) care a generat evenimentul în sistemul Accolades.
userType
("user") Tipul de entitate care a generat evenimentul (momentan acest câmp are doar valoarea "user" - adică evenimentul a fost generat de un telefon).
callDirection
("inbound" sau "outbound") Direcția apelului, relativă la utilizatorul care a generat evenimentul. Poate avea valorile "inbound" (apel de intrare, un utilizator Accolades a primit un apel) sau "outbound" (apel de ieșire, un utilizator Accolades a inițializat un apel).
callerId
(text) Numărul de telefon de la care a fost inițializat apelul. Atenție, valoarea poate fi și Anonymus, pentru apelurile pentru care nu se furnizează identitatea.
partnerNumber
(text) Numărul de telefon cu care vorbește utilizatorul Accolades (numărul de telefon la care s-a sunat, în cazul apelurilor de ieșire sau numărul de telefon de la care s-a sunat, în cazul apelurilor de intrare).
answered
("yes" sau "no") Statusul apelului în momentul emiterii notificării. Valoarea "yes" indică un apel la care s-a raspuns, valoarea "no" indică un apel la care nu s-a raspuns. Evenimentele de tip "answer" vor avea întotdeauna valoarea "yes" deoarece sunt generate imediat după ce se răspunde la apel. Evenimentele de tip "hangup" pot avea atât valoarea "yes" (s-a închis un apel la care în prealabil s-a răspuns) cât și "no" (s-a închis un apel în timp de telefonul persoanei apelate încă sună).
startTime
(Unix Time) Timpul inițierii apelului (pentru apelurile de ieșire se furnizează momentul în care centrala începe formarea numărului, către persoana care se apelează, pentru apelurile de intrare se furnizează momentul în care centrala trimite apelul către telefonul utilizatorului Accolades). Acest parametru are întotdeauna o valoare în orice notificare.
answerTime
(Unix Time sau 0) Momentul în care s-a raspuns la apel. Dacă notificarea este pentru un apel la care nu s-a răspuns, acest parametru va avea valoarea 0.
hangupTime
(Unix Time sau 0) Momentul în care apelul a fost închis. Dacă notificarea este pentru un apel în curs (care nu este încă închis) atunci parametrul va avea valoarea 0.
hangupCode
(numeric) Motivul pentru care a fost închis apelul. O listă cu codurile și descrierea acestora se poate verifica în documentația Asterisk. De exemplu, codul 16 indică o terminare normală a apelului.
hangupDescription
(text) Descrierea motivului pentru care a fost închis apelul. O listă cu codurile și descrierea acestora se poate verifica în documentația Asterisk.
error
(text) Parametrul este un text gol, în cazul în care nu au apărut erori în procesul de notificare. În cazul unei erori, parametrul conține o descriere a erorii.
errorCode
(400, 500 sau gol) Codul de eroare corespunzător textului de eroare. Dacă nu există erori, atunci parametrul este gol. Altfel, acesta poate avea valoarea 500 (eroare generată de serverul Accolades) sau 400 (eroare generată de modul în care serverul extern a răspuns la cererea Accolades).

Valorile parametrilor startTime, answerTime și hangupTime sunt furnizate în format Unix Time (numărul de secunde de la 1 ianuarie 1970, ora 00:00:00).

Răspuns la cerere

Atunci când este emisă o notificare de tip "answer" sau "confirmHangup" serverul Accolades verifică răspunsul primit. În funcție de răspunsul primit există 3 cazuri:

Răspuns la un pachet "answer"

Răspunsul în format JSON poate conține următorii parametrii:

confirmHangup
Dacă parametrul este definit cu valoarea "yes" atunci Accolades, va emite un pachet de tip "confirmHangup" către client, după expirarea duratei maxime definită mai jos. Pentru orice altă valoare, apelul se va închide automat, după expirarea duratei maxime.
callMaxDuration
Durata (în secunde) după care se va solicita o nouă durată (dacă parametrul "confirmHangup" este "yes") sau apelul se va închide (parametrul "confirmHangup" nu este definit sau are o valoare diferită de "yes"). Valoarea maximă pe care o acceptă parametrul este 7200 (2 ore). Dacă se furnizează o valoare mai mare, atunci aceasta se va suprascrie cu 7200. Dacă nu se furnizează parametrul sau se furnizează cu valoarea 0 atunci apelul nu se limitează în niciun fel. Durata minimă acceptată este de 30 de secunde (dacă nu este zero). Valorile cuprinse între 1 și 30 de secunde se vor suprascrie automat cu 30.

Răspuns la un pachet "confirmHangup"

Răspunsul în format JSON poate conține următorii parametrii:

confirmHangup
Dacă parametrul este definit cu valoarea "yes" atunci Accolades, va emite un pachet de tip "confirmHangup" către client, după expirarea duratei maxime definită mai jos. Pentru orice alta valoare, apelul se va închide automat, după expirarea duratei maxime.
callMaxDuration
Durata (în secunde) după care se va solicita o nouă durată (dacă parametrul "confirmHangup" este "yes") sau apelul se va închide (parametrul "confirmHangup" nu este definit sau are o valoare diferită de "yes"). Valoarea maximă pe care o acceptă parametrul este 7200 (2 ore). Dacă se furnizează o valoare mai mare, atunci aceasta se va suprascrie cu 7200. Dacă nu se furnizează parametrul sau se furnizează cu valoarea 0 atunci apelul se va închide instantaneu. Durata minimă acceptata este de 30 de secunde (daca nu este zero). Valorile cuprinse între 1 și 30 de secunde se vor suprascrie automat cu 30.

Formatare JSON

Atenție! Obiectul JSON se va formata conform standarului. Nu sunt acceptate chei fără încadrare în ghilimele.

Formatare corectă: {"callMaxDuration":"120","confirmHangup":"yes"}.

Formatare incorectă: {callMaxDuration:"120",confirmHangup:"yes"}.