Utilizarea Call

API-ul și webhook-urile Call: chei, scopes și evenimente

Un tur practic al API-ului REST Call: chei API și scopes, limite de rată, gestionarea erorilor, webhook-uri semnate și pagina Developers pentru endpoint-uri.

Echipa editorială Call · Publicat · 6 min de citit

Mai devreme sau mai târziu, un sistem telefonic trebuie să comunice cu altceva: un CRM care trebuie să afișeze un apel imediat ce se încheie, un instrument de facturare care vrea să știe cine a sunat, un script care inițiază un apel la trimiterea unui formular. Call are un API REST și webhook-uri outbound exact pentru asta. Acest ghid explică cum se potrivesc piesele, ce să cereți înainte de a scrie cod și greșelile care costă cel mai des o după-amiază unui dezvoltator.

Un dezvoltator verifică o integrare pe laptop, lângă un telefon de birou
Imagine ilustrativă

Dacă scopul este doar să mutați contacte în masă, citiți mai întâi Importul contactelor într-un CRM pentru echipe telefonice; un import este adesea mai simplu decât o integrare.

De unde începeți: referința și pagina Developers

Există două locuri de cunoscut. Referința API se află în Settings și, de asemenea, în meniul Resources de pe pagina principală. Poate fi citită fără autentificare, ceea ce este util când estimați lucrul pentru un client. Pagina Developers, tot din Settings, este pentru propriul spațiu de lucru: arată identificatorii organizației și ai agenților, endpoint-urile webhook și o listă doar pentru citire a cheilor.

Ce vă oferă fiecare loc

  • Start hereURL-ul de bază și convențiile, autentificarea cu un tabel de scopes și erorile cu codurile de status.
  • Endpoint-uriFiecare card de endpoint arată scope-ul, parametrii, corpul cererii, răspunsul și erorile, cu cereri gata de copiat în curl, JavaScript și Python.
  • CăutareApăsați / pentru a sări la Search endpoints și filtrați după metodă, cale, scope sau rezumat.
  • OpenAPI JSONDescarcă întreaga specificație ca un singur fișier pentru propriile instrumente.
  • Agent ID / APIID-ul și slug-ul organizației, modul API (Sandbox sau Live) și ID-ul agentului AI ales, fiecare cu un buton Copy.
  • WebhooksEndpoint-urile, evenimentele primite de fiecare, ultimul status HTTP și eventualele livrări eșuate.

Citiți secțiunile despre limitele de rată și webhook-urile outbound înainte de lansare, nu după. Descriu comportamente ușor de ratat într-un test rapid.

Chei API și scopes

Fiecare cerere conține o cheie într-un header Authorization, ca bearer token. Cheile nu se creează în aplicație: operatorul spațiului de lucru le emite și vă spune ce scopes au. Cheia completă este afișată o singură dată, în momentul emiterii, iar după aceea apar doar primele caractere, așa că păstrați-o imediat în propriul depozit de secrete.

ScopeCe permite
readCitirea contactelor, apelurilor, cozilor, membrilor echipei, rapoartelor și a listei „nu sunați”.
writeCrearea și actualizarea contactelor, înregistrarea rezultatelor apelurilor, adăugarea de numere în lista „nu sunați”.
callsInițierea și încheierea apelurilor.
adminGestionarea webhook-urilor; poate apela și toate celelalte endpoint-uri.

Cereți cel mai mic set care face treaba. Un script de raportare are nevoie doar de read; un buton click-to-call are nevoie de calls. Dacă o cerere returnează 403 cu codul insufficient_scope, cheiei îi lipsește scope-ul afișat pe cardul acelui endpoint.

Sandbox și live

Cheile pot fi emise pentru un sandbox, care folosește un simulator și nu inițiază apeluri reale, sau pentru utilizare live. Tratați prefixul unei chei doar ca pe o etichetă: o cheie etichetată pentru test lucrează pe aceleași date și pe aceeași conexiune telefonică precum una live, așa că nu vă bazați pe prefix pentru a ține experimentele departe de clienții reali. Folosiți modul API afișat pe pagina Developers ca să știți unde vă aflați.

Inițierea apelurilor prin API

Endpoint-urile publice acoperă elementele de bază: o verificare a stării, listarea apelurilor, citirea unui apel, inițierea unui apel, închiderea, gestionarea webhook-urilor și conversația cu un agent AI. Un apel outbound inițiat prin API trece prin aceeași verificare de conformitate ca un apel inițiat de la birou, așa că un număr din lista „nu sunați” sau din afara orelor de apelare permise este refuzat, exact ca în cazul unui agent. Construiți codul astfel încât să trateze acest refuz ca pe un rezultat normal, nu ca pe o eroare.

Acest lucru contează pentru arhitectură. Nu scrieți o buclă care reîncearcă un apel refuzat până reușește. Citiți motivul, înregistrați-l și mergeți mai departe. Pentru regulile din spatele acestor refuzuri, consultați Protecția orelor de apelare în Call și Lista „nu sunați” în Call.

Limite de rată și erori

Fiecare cheie are propria limită de cereri pe minut, stabilită la emitere; valoarea implicită este 120. Când o cheie își epuizează minutul, API-ul răspunde cu 429 și codul rate_limited și vă spune cât să așteptați în headerul X-RateLimit-Reset. Așteptați atât, apoi continuați. Un client politicos încetinește singur înainte de a da de zid.

Gestionarea unei cereri eșuate

  1. Citiți statusulEste o eroare a clientului pe care o puteți corecta sau o eroare de server care merită reîncercată?
  2. Citiți codulRamificați logica după cod, niciodată după textul mesajului.
  3. Reduceți ritmulPentru 429, așteptați headerul de resetare; pentru erorile de server, reîncercați de câteva ori, cu pauze tot mai lungi.
  4. Înregistrați detaliilePăstrați endpoint-ul, codul și ora, ca suportul să poată urmări problema.
  5. Opriți-vă la refuzuriUn refuz de conformitate este o decizie, nu o defecțiune; nu intrați în buclă.

Webhook-uri: primirea evenimentelor

În loc să întrebați API-ul iar și iar dacă s-a întâmplat ceva, lăsați Call să vă anunțe. Pe pagina Developers, apăsați Add endpoint, introduceți o adresă https publică și bifați evenimentele dorite; dacă nu bifați niciunul, le primiți pe toate. Secretul de semnare este afișat o singură dată, când se adaugă endpoint-ul. Copiați-l atunci. Dacă se pierde, ștergeți endpoint-ul și adăugați-l din nou pentru a obține unul nou.

Fiecare livrare este semnată. Headerul de semnătură conține un HMAC-SHA256 al timestamp-ului și al corpului, unite printr-un punct, calculat cu secretul de semnare, iar un header separat conține timestamp-ul. Recalculați-l pe partea dumneavoastră și comparați înainte de a avea încredere în conținut. Referința API include cod de exemplu pentru asta în Node.js și Python, iar respingerea timestamp-urilor vechi vă protejează împotriva cererilor reluate.

Un receptor de webhook bun și unul slab

BunSlab
SemnăturăVerificată la fiecare cerereAcceptată fără verificare
Răspuns2xx în câteva secunde, munca pusă în coadă pentru mai târziuProcesare lentă înainte de răspuns
DuplicatePrimirea aceluiași eveniment de două ori nu creează problemeCreează două înregistrări
EșecuriAlertează când livrările eșueazăTăcere până observă cineva

Endpoint-ul trebuie să răspundă cu un status 2xx în 10 secunde. O livrare eșuată este reîncercată, până la șase încercări în total, iar un endpoint care eșuează de 50 de ori la rând este dezactivat. Fiecare rând de pe pagina Developers arată ultimul status HTTP și câte livrări au eșuat, iar Send test trimite un eveniment de test semnat, ca să vedeți ce răspunde serverul.

O listă de verificare pentru lansare

Înainte de a activa o integrare

  • Știți ce scopes are cheia și nu are mai multe decât este necesar
  • Cheia este păstrată într-un depozit de secrete, nu în codul sursă
  • Semnăturile webhook sunt verificate, iar timestamp-urile vechi sunt respinse
  • Receptorul răspunde rapid și gestionează evenimentele duplicate
  • Răspunsurile de limită de rată și de refuz sunt gestionate fără bucle strânse de reîncercare
  • Ați testat în modul sandbox și ați apăsat Send test pe endpoint
  • Este desemnată o persoană care primește o alertă dacă livrările încep să eșueze

Cum o faceți în Call

În Call, deschideți Settings, apoi API reference, pentru a studia endpoint-urile, și Settings, apoi Developers, pentru a copia ID-ul organizației, a verifica cheile și a adăuga un webhook. Proprietarii, administratorii și managerii pot adăuga, testa și șterge endpoint-uri; toți ceilalți văd lista. Dacă folosiți și funcțiile agentului AI, ID-ul agentului de pe aceeași pagină alimentează endpoint-ul de chat. Pentru partea de voce a produsului, consultați Configurarea unui agent AI în Call.

Întrebări frecvente

Cum obțin o cheie API?

Cheile sunt emise de operatorul spațiului de lucru; nu pot fi create în aplicație. Cereți una și spuneți ce scopes are nevoie. Cheia completă este afișată o singură dată, la emitere.

Ce înseamnă un răspuns 429?

Cheia și-a epuizat cererile pentru minutul curent. Așteptați numărul de secunde din headerul X-RateLimit-Reset, apoi încercați din nou și distribuiți lucrul în masă pe o perioadă mai lungă.

Cum verific că un webhook a venit cu adevărat de la Call?

Calculați un HMAC-SHA256 al timestamp-ului și al corpului cu secretul de semnare și comparați-l cu headerul de semnătură. Referința API arată exemple în Node.js și Python.

Pot trimite webhook-uri către un server local de dezvoltare?

Nu direct. Endpoint-urile trebuie să fie adrese https publice, așa că folosiți un instrument de tunelare care vă expune serverul local pe o astfel de adresă.

De ce mi-a fost refuzat apelul API de inițiere a unui apel?

Apelurile inițiate prin API trec prin aceeași verificare de conformitate ca apelurile de la birou. Un număr din lista „nu sunați” sau din afara orelor de apelare este refuzat.

Cine poate vedea și modifica webhook-urile?

Toată lumea poate citi lista, dar doar proprietarii, administratorii și managerii pot adăuga, testa sau șterge endpoint-uri.

Deschideți referința API Call și adăugați un endpoint webhook

În consola demo puteți încerca apeluri primite într-o simulare.

Ghiduri conexe