Click-to-call

Pornește un apel din aplicația ta: centrala sună telefonul colegului, iar când răspunde, formează numărul cerut.

Cazul obișnuit este un buton „Sună” lângă numărul unui client, în CRM-ul sau în aplicația internă a firmei tale. Apelul se face de pe interiorul colegului, de pe telefonul lui fix, cu aceleași reguli ca un apel format de mână: numărul afișat, înregistrarea, accesul pe destinații și limitele contului. În istoric și în evenimente apare ca un apel efectuat de acel interior.

Cum funcționează

1. Aplicația ta trimite cererea, cu interiorul colegului în adresă și numărul de format în corp.
2. Centrala sună telefoanele înregistrate pe interior: telefonul fix și, dacă există, aplicația de mobil. Softphone-ul din browser nu sună. Pe ecranul telefonului apare numărul care urmează să fie format și, dacă l-ai trimis, numele contactului.
3. Când colegul ridică, centrala formează numărul. Colegul aude tonul de apel, apoi vorbește ca într-un apel obișnuit.
4. Răspunsul la cerere vine după ce colegul a ridicat sau după ce telefonul a sunat fără răspuns. Cererea durează cât sună telefonul, cel mult 15 secunde.

Permisiunea

Ruta cere o cheie cu permisiunea calls:dial. Permisiunea se bifează la crearea cheii, în CrioX, la Integrări → API, cu opțiunea „Poate porni apeluri (click-to-call)”. Cheile create fără ea au doar calls:read și primesc 403 insufficient_scope; permisiunea nu se poate adăuga ulterior, deci creează o cheie nouă pentru aplicația care pornește apeluri. Verifici permisiunile unei chei cu GET /v1/account, în câmpul scopes.

Ține această cheie cu aceeași grijă ca pe celelalte: cine o are poate face să sune telefoanele colegilor tăi, cu orice număr pe ecran. Apelul se formează totuși doar după ce un coleg ridică.

Pornirea unui apel

extension este interiorul colegului de pe care se face apelul, de exemplu 101. Corpul cererii este JSON, cu antetul Content-Type: application/json:

Exemplu

curl -X POST https://api.criox.ro/v1/extensions/101/dial \
  -H "Authorization: Bearer cxk_…" \
  -H "Content-Type: application/json" \
  -d '{ "number": "+40743755549", "name": "Ion Popescu" }'

Răspuns, după ce colegul a ridicat:

{
  "extension": "101",
  "number": "+40743755549",
  "devices": 1
}

Răspunsul 200 înseamnă că colegul a ridicat și centrala formează numărul. Ce se întâmplă mai departe (răspuns, ocupat, fără răspuns) nu este cunoscut în acel moment; vezi Apelul după pornire.

Din Node.js, cu un timp de așteptare potrivit pentru o cerere care durează cât sună telefonul:

const res = await fetch("https://api.criox.ro/v1/extensions/101/dial", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CRIOX_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ number: "+40743755549", name: "Ion Popescu" }),
  signal: AbortSignal.timeout(30_000),
});
const body = await res.json();
if (res.ok) {
  console.log(`Colegul a ridicat; centrala formează ${body.number}.`);
} else if (body.error === "phone_no_answer") {
  console.log("Colegul nu a răspuns la telefon.");
} else {
  console.log(`Apelul nu a pornit: ${body.error} (${body.message})`);
}

Erori

Pe lângă erorile comune, descrise în Prezentare, ruta are coduri proprii. Codurile 409 descriu starea telefonului colegului și nu dispar la reîncercare imediată; spune-i utilizatorului ce s-a întâmplat.

Apelul după pornire

După răspunsul 200, apelul continuă pe centrală ca orice apel efectuat de colegul tău. Rezultatul lui ajunge în aplicația ta pe două căi:

• prin evenimente: la încheiere primești call.completed, cu direction: "outbound", agent_extension egal cu interiorul din cerere și contact_number egal cu numărul format;
• prin GET /v1/calls, cu direction=outbound și agent egal cu interiorul, după încheierea apelului.

Răspunsul la cerere nu conține id-ul apelului, pentru că apelul se creează pe centrală abia după ce colegul a ridicat. Pentru a lega apelul de cererea ta, folosește interiorul, numărul și momentul: started_at al apelului este la câteva secunde după răspunsul 200.

Un apel pornit prin API care nu a fost preluat de celălalt capăt apare în istoric cu result no_answer, busy sau failed, ca orice apel efectuat.

Întrebări frecvente

Pot suna un coleg, nu un număr extern?

Da. Trimite interiorul colegului ca number, de exemplu "number": "102". Apelul este intern și nu apare în GET /v1/calls, nici în evenimente.

Colegul lucrează doar din browser. Cum îl ajut să sune?

Prin API, apelul se face de pe un telefon fix sau de pe aplicația de mobil înregistrată pe interior. Când colegul are deschis doar softphone-ul din browser, cererea primește 409 phone_offline, iar message spune că softphone-ul este deschis. În acest caz, colegul sună din CrioX, unde numerele sunt deja legături de apel.

De ce nu răspunde telefonul singur, ca să nu mai fie nevoie de ridicare?

Pentru că apelul ar pleca atunci fără nicio persoană la telefon. O cheie compromisă ar putea forma orice număr, în afara programului, pe factura ta. Ridicarea receptorului este singura confirmare care nu depinde de nicio setare.

Cât durează cererea?

Cât sună telefonul colegului: de la o secundă, dacă ridică imediat, până la aproximativ 15 secunde, dacă nu răspunde. Setează un timp de așteptare de cel puțin 30 de secunde pentru această cerere, mai mare decât cel folosit pentru citiri.

Pot trimite două cereri una după alta pentru același coleg?

Cât timp telefonul sună pentru prima cerere, a doua primește 409 phone_ringing. După ce colegul a ridicat, o cerere nouă este acceptată: telefonul decide dacă o arată ca apel în așteptare sau o respinge ca ocupat.

CrioX · suport@criox.ro · live.criox.ro