Korištenje usluge Call

Call API i webhookovi za programere: ključevi, opsezi, događaji

Praktični pregled REST API-ja Calla: API ključevi i opsezi, ograničenja zahtjeva, obrada pogrešaka, potpisani webhookovi i stranica Programeri za krajnje točke.

Urednički tim usluge Call · Objavljeno · Čitanje: 5 min

Prije ili kasnije telefonski sustav mora komunicirati s nečim drugim: CRM-om koji treba prikazati poziv čim završi, alatom za naplatu koji želi znati tko je zvao, skriptom koja upućuje poziv kad se pošalje obrazac. Call za to ima REST API i odlazne webhookove. Ovaj vodič objašnjava kako se dijelovi uklapaju, što zatražiti prije pisanja koda i pogreške zbog kojih programeri najčešće izgube poslijepodne.

Programer na prijenosnom računalu pokraj stolnog telefona pregledava integraciju
Ilustrativna slika

Ako vam je cilj samo skupno premjestiti kontakte, najprije pročitajte Uvoz kontakata u CRM telefonskog tima; uvoz je često jednostavniji od integracije.

Gdje početi: referentna dokumentacija i stranica Programeri

Treba poznavati dva mjesta. Referentna dokumentacija API-ja nalazi se pod Postavke, a i u izborniku Resursi na početnoj stranici. Može se čitati bez prijave, što je praktično kad za klijenta procjenjujete opseg posla. Stranica Programeri, također pod Postavke, namijenjena je vašem radnom prostoru: prikazuje identifikatore vaše organizacije i agenta, vaše krajnje točke za webhookove i popis vaših ključeva samo za čitanje.

Što vam daje svako mjesto

  • Počnite ovdjeOsnovni URL i konvencije, autentifikacija s tablicom opsega te pogreške sa statusnim kodovima.
  • Krajnje točkeKartica svake krajnje točke navodi njezin opseg, parametre, tijelo zahtjeva, odgovor i pogreške, s gotovim zahtjevima za kopiranje u curlu, JavaScriptu i Pythonu.
  • PretraživanjePritisnite / za skok na Pretraži krajnje točke i filtrirajte po metodi, putanji, opsegu ili sažetku.
  • OpenAPI JSONPreuzima cijelu specifikaciju kao jednu datoteku za vaše alate.
  • ID agenta / APIID i slug vaše organizacije, način rada API-ja (Sandbox ili Live) i ID AI agenta kojeg odaberete, svaki s gumbom Kopiraj.
  • WebhookoviVaše krajnje točke, događaji koje svaka prima, posljednji HTTP status i neuspjele isporuke.

Odjeljke o ograničenjima broja zahtjeva i odlaznim webhookovima pročitajte prije pokretanja, a ne poslije. Opisuju ponašanje koje je lako previdjeti u brzom testu.

API ključevi i opsezi

Svaki zahtjev nosi ključ u zaglavlju Authorization kao bearer token. Ključevi se ne izrađuju u aplikaciji: izdaje ih operater vašeg radnog prostora i govori vam koje opsege nose. Cijeli ključ prikazuje se jednom, u trenutku izdavanja, a nakon toga vide se samo njegovi prvi znakovi, pa ga odmah spremite u vlastito spremište tajni.

OpsegŠto dopušta
readČitanje kontakata, poziva, redova, članova tima, izvješća i popisa za zabranu poziva.
writeIzrada i ažuriranje kontakata, bilježenje ishoda poziva, dodavanje brojeva na popis za zabranu poziva.
callsUpućivanje i završavanje poziva.
adminUpravljanje webhookovima; može pozivati i sve ostale krajnje točke.

Zatražite najmanji skup koji obavlja posao. Skripti za izvješća treba read i ništa drugo; gumbu za poziv jednim klikom treba calls. Ako zahtjev vrati 403 s kodom insufficient_scope, ključu nedostaje opseg naveden na kartici te krajnje točke.

Sandbox i Live

Ključevi se mogu izdati za sandbox, koji koristi simulator i ne upućuje stvarne pozive, ili za stvarnu upotrebu. Prefiks ključa smatrajte samo oznakom: ključ označen kao testni radi na istim podacima i istoj telefonskoj vezi kao stvarni, pa se ne oslanjajte na prefiks da eksperimente drži podalje od stvarnih klijenata. Kako biste znali gdje ste, koristite način rada API-ja prikazan na stranici Programeri.

Upućivanje poziva putem API-ja

Javne krajnje točke pokrivaju osnove: provjeru stanja, popis poziva, čitanje jednog poziva, upućivanje poziva, prekidanje, upravljanje webhookovima i razgovor s AI agentom. Odlazni poziv upućen putem API-ja prolazi istu provjeru usklađenosti kao poziv upućen iz službe, pa se broj na popisu za zabranu poziva ili izvan dopuštenog vremena pozivanja odbija, točno kao što bi bio odbijen agentu. Napišite kod tako da to odbijanje obrađuje kao normalan ishod, a ne kao grešku.

To je važno za dizajn. Ne pišite petlju koja ponavlja odbijeni poziv dok ne uspije. Pročitajte razlog, zabilježite ga i nastavite. Za pravila iza tih odbijanja pogledajte Zaštita vremena pozivanja u Callu i Popis za zabranu poziva u Callu.

Ograničenja broja zahtjeva i pogreške

Svaki ključ ima vlastito ograničenje zahtjeva u minuti, postavljeno pri izdavanju ključa; zadana vrijednost je 120. Kad ključ potroši minutu, API odgovara s 429 i kodom rate_limited te u zaglavlju X-RateLimit-Reset navodi koliko trebate čekati. Pričekajte toliko, a zatim nastavite. Pristojan klijent sam uspori prije nego što udari u zid.

Obrada neuspjelog zahtjeva

  1. Pročitajte statusJe li riječ o pogrešci klijenta koju možete ispraviti ili o pogrešci poslužitelja koju vrijedi ponoviti?
  2. Pročitajte kodGrananje temeljite na kodu, nikad na tekstu poruke.
  3. Povucite seZa 429 pričekajte zaglavlje za ponovno postavljanje; kod pogrešaka poslužitelja pokušajte nekoliko puta s rastućim razmacima.
  4. Zabilježite pojedinostiSačuvajte krajnju točku, kod i vrijeme kako bi podrška mogla pratiti problem.
  5. Zaustavite se kod odbijanjaOdbijanje zbog usklađenosti je odluka, a ne kvar; ne vrtite ga u petlji.

Webhookovi: primanje događaja

Umjesto da API iznova pitate je li se nešto dogodilo, neka vam Call to javi. Na stranici Programeri pritisnite Dodaj krajnju točku, upišite javnu https adresu i označite događaje koje želite; ako ne označite nijedan, primate sve događaje. Tajna za potpisivanje prikazuje se jednom, kad se krajnja točka doda. Tada je kopirajte. Ako se izgubi, izbrišite krajnju točku i ponovno je dodajte kako biste dobili novu.

Svaka isporuka je potpisana. Zaglavlje potpisa sadrži HMAC-SHA256 vremenske oznake i tijela spojenih točkom, izračunat vašom tajnom za potpisivanje, a zasebno zaglavlje nosi vremensku oznaku. Izračunajte ga ponovno na svojoj strani i usporedite prije nego što povjerujete sadržaju. Referentna dokumentacija API-ja uključuje primjer koda za to u Node.js-u i Pythonu, a odbijanje starih vremenskih oznaka štiti vas od ponovno poslanih zahtjeva.

Dobar i loš prijamnik webhookova

DobarLoš
PotpisProvjerava se pri svakom zahtjevuPrihvaća se bez provjere
Odgovor2xx unutar nekoliko sekundi, posao u redu za kasnijeSporo procesiranje prije odgovora
DuplikatiIsti se događaj sigurno može primiti dvaputStvara dva zapisa
NeuspjesiUpozorava kad isporuke ne uspijuTiho dok netko ne primijeti

Vaša krajnja točka mora odgovoriti statusom 2xx unutar 10 sekundi. Neuspjela isporuka ponovno se pokušava, ukupno do šest pokušaja, a krajnja točka koja 50 puta zaredom ne uspije isključuje se. Svaki redak na stranici Programeri prikazuje posljednji HTTP status i broj neuspjelih isporuka, a Pošalji test šalje jedan potpisani testni događaj kako biste vidjeli što vaš poslužitelj odgovara.

Kontrolni popis za pokretanje

Prije uključivanja integracije

  • Znate koje opsege ključ ima i nema ih više nego što je potrebno
  • Ključ je pohranjen u spremištu tajni, a ne u izvornom kodu
  • Potpisi webhookova se provjeravaju, a stare vremenske oznake odbijaju
  • Prijamnik brzo odgovara i obrađuje duplicirane događaje
  • Odgovori o ograničenju broja zahtjeva i odbijanju obrađuju se bez uskih petlji ponavljanja
  • Testirali ste u načinu rada sandbox i pritisnuli Pošalji test na krajnjoj točki
  • Imenovana je osoba koja prima upozorenje ako isporuke počnu propadati

Kako to učiniti u Callu

U Callu otvorite Postavke, zatim Referentna dokumentacija API-ja kako biste proučili krajnje točke, te Postavke, zatim Programeri kako biste kopirali ID organizacije, provjerili ključeve i dodali webhook. Vlasnici, administratori i voditelji mogu dodavati, testirati i brisati krajnje točke; svi ostali vide popis. Ako koristite i značajke AI agenta, ID agenta na istoj stranici koristi se za krajnju točku za razgovor. Za glasovni dio proizvoda pogledajte Postavljanje AI agenta u Callu.

Često postavljana pitanja

Kako mogu dobiti API ključ?

Ključeve izdaje operater vašeg radnog prostora; ne mogu se izraditi u aplikaciji. Zatražite ključ i navedite koje opsege treba. Cijeli ključ prikazuje se jednom, pri izdavanju.

Što znači odgovor 429?

Ključ je potrošio zahtjeve za tekuću minutu. Pričekajte broj sekundi naveden u zaglavlju X-RateLimit-Reset, zatim pokušajte ponovno i rasporedite skupni posao na dulje razdoblje.

Kako provjeriti je li webhook doista došao od Calla?

Izračunajte HMAC-SHA256 vremenske oznake i tijela svojom tajnom za potpisivanje i usporedite ga sa zaglavljem potpisa. Referentna dokumentacija API-ja prikazuje primjere u Node.js-u i Pythonu.

Mogu li webhookove slati na lokalni razvojni poslužitelj?

Ne izravno. Krajnje točke moraju biti javne https adrese, pa koristite alat za tuneliranje koji vaš lokalni poslužitelj izlaže na takvoj adresi.

Zašto je moj API zahtjev za upućivanje poziva odbijen?

Pozivi upućeni putem API-ja prolaze istu provjeru usklađenosti kao pozivi iz službe. Broj na popisu za zabranu poziva ili izvan vremena pozivanja se odbija.

Tko može vidjeti i mijenjati webhookove?

Popis mogu čitati svi, ali krajnje točke mogu dodavati, testirati ili brisati samo vlasnici, administratori i voditelji.

Otvorite referentnu dokumentaciju Call API-ja i dodajte krajnju točku za webhook

U demo konzoli možete isprobati dolazne pozive u simulaciji.

Povezani vodiči