Používanie Call

API a webhooky Call pre vývojárov: kľúče, rozsahy, udalosti

Praktická prehliadka REST API Call: kľúče API a rozsahy, limity požiadaviek, spracovanie chýb, podpísané webhooky a stránka Vývojári na správu koncových bodov.

Redakcia Call · Zverejnené · Čítanie na 5 min

Skôr či neskôr musí telefónny systém komunikovať s niečím iným: s CRM, ktoré má zobraziť hovor hneď po jeho skončení, s fakturačným nástrojom, ktorý chce vedieť, kto volal, so skriptom, ktorý pri odoslaní formulára uskutoční hovor. Presne na to má Call REST API a odchádzajúce webhooky. Tento sprievodca vysvetľuje, ako do seba jednotlivé časti zapadajú, čo si vyžiadať skôr, než začnete písať kód, a chyby, ktoré vývojára najčastejšie stoja celé popoludnie.

Vývojár kontroluje integráciu na notebooku vedľa stolného telefónu
Ilustračný obrázok

Ak chcete len hromadne preniesť kontakty, najprv si prečítajte článok Import kontaktov do CRM telefonického tímu; import je často jednoduchší než integrácia.

Kde začať: referenčná príručka a stránka Vývojári

Treba poznať dve miesta. Referenčná príručka API je v časti Nastavenia a tiež v menu Zdroje na domovskej stránke. Dá sa čítať bez prihlásenia, čo sa hodí, keď pripravujete rozsah práce pre klienta. Stránka Vývojári, tiež v časti Nastavenia, slúži pre váš vlastný pracovný priestor: zobrazuje identifikátory vašej organizácie a agenta, vaše koncové body webhookov a zoznam vašich kľúčov len na čítanie.

Čo vám ktoré miesto poskytne

  • Začnite tuZákladná URL a konvencie, overovanie s tabuľkou rozsahov a chyby so stavovými kódmi.
  • Koncové bodyKarta každého koncového bodu uvádza jeho rozsah, parametre, telo požiadavky, odpoveď a chyby a k tomu pripravené požiadavky na skopírovanie v curl, JavaScripte a Pythone.
  • HľadaťStlačením / prejdete do vyhľadávania koncových bodov a môžete filtrovať podľa metódy, cesty, rozsahu alebo popisu.
  • OpenAPI JSONStiahne celú špecifikáciu ako jeden súbor pre vaše vlastné nástroje.
  • ID agenta / APIID a slug vašej organizácie, režim API (Sandbox alebo Naživo) a ID AI agenta, ktorého vyberiete, každé s tlačidlom Kopírovať.
  • WebhookyVaše koncové body, udalosti, ktoré každý prijíma, posledný stav HTTP a prípadné neúspešné doručenia.

Časti o limitoch požiadaviek a odchádzajúcich webhookoch si prečítajte pred spustením, nie po ňom. Opisujú správanie, ktoré sa pri rýchlom teste ľahko prehliadne.

Kľúče API a rozsahy

Každá požiadavka nesie kľúč v hlavičke Authorization ako bearer token. Kľúče sa nevytvárajú v aplikácii: vydáva ich prevádzkovateľ vášho pracovného priestoru a oznámi vám, aké rozsahy majú. Celý kľúč sa zobrazí raz, v okamihu vydania, a potom sa zobrazujú len jeho prvé znaky, preto ho hneď uložte do vlastného úložiska tajomstiev.

RozsahČo umožňuje
readČítať kontakty, hovory, fronty, členov tímu, reporty a zoznam nevolať.
writeVytvárať a aktualizovať kontakty, zaznamenávať výsledky hovorov, pridávať čísla do zoznamu nevolať.
callsUskutočňovať a ukončovať hovory.
adminSpravovať webhooky; môže volať aj všetky ostatné koncové body.

Žiadajte najmenšiu sadu, ktorá na úlohu stačí. Skript na reporty potrebuje read a nič viac; tlačidlo click-to-call potrebuje calls. Ak požiadavka vráti 403 s kódom insufficient_scope, kľúču chýba rozsah uvedený na karte daného koncového bodu.

Sandbox a ostrá prevádzka

Kľúče možno vydať pre sandbox, ktorý používa simulátor a neuskutočňuje skutočné hovory, alebo na ostré použitie. Predponu kľúča berte len ako označenie: kľúč označený ako testovací pracuje s rovnakými údajmi a rovnakým telefónnym pripojením ako ostrý, preto sa nespoliehajte na predponu, že udrží experimenty ďalej od skutočných zákazníkov. Kde sa nachádzate, zistíte z režimu API zobrazeného na stránke Vývojári.

Uskutočňovanie hovorov cez API

Verejné koncové body pokrývajú základy: kontrolu stavu, zoznam hovorov, načítanie jedného hovoru, uskutočnenie hovoru, zavesenie, správu webhookov a chat s AI agentom. Odchádzajúci hovor uskutočnený cez API prechádza rovnakou kontrolou súladu ako hovor z pracoviska, takže číslo zo zoznamu nevolať alebo hovor mimo povolených hodín sa odmietne presne tak ako u operátora. Kód navrhnite tak, aby toto odmietnutie spracoval ako bežný výsledok, nie ako chybu.

Pre návrh je to dôležité. Nepíšte cyklus, ktorý odmietnutý hovor opakuje, kým neprejde. Prečítajte dôvod, zaznamenajte ho a pokračujte. Pravidlá za týmito odmietnutiami opisujú články Strážca hodín volania v Call a Zoznam nevolať v Call.

Limity požiadaviek a chyby

Každý kľúč má vlastný limit požiadaviek za minútu, nastavený pri vydaní kľúča; predvolená hodnota je 120. Keď kľúč minútu vyčerpá, API odpovie 429 s kódom rate_limited a v hlavičke X-RateLimit-Reset uvedie, ako dlho čakať. Počkajte tak dlho a potom pokračujte. Slušný klient spomalí skôr, než narazí na stenu.

Spracovanie neúspešnej požiadavky

  1. Prečítajte stavIde o chybu klienta, ktorú môžete opraviť, alebo o chybu servera, pri ktorej sa oplatí skúsiť to znova?
  2. Prečítajte kódVetvite podľa kódu, nikdy podľa textu správy.
  3. UstúptePri 429 počkajte podľa hlavičky reset; pri chybách servera to skúste niekoľkokrát s rastúcim odstupom.
  4. Zaznamenajte podrobnostiUchovajte koncový bod, kód a čas, aby to podpora mohla dohľadať.
  5. Pri odmietnutiach zastavteOdmietnutie z dôvodu súladu je rozhodnutie, nie porucha; necyklite na ňom.

Webhooky: prijímanie udalostí

Namiesto toho, aby ste sa API stále dookola pýtali, či sa niečo stalo, nechajte Call, nech vám to povie. Na stránke Vývojári stlačte Pridať koncový bod, zadajte verejnú adresu https a zaškrtnite požadované udalosti; ak nezaškrtnete žiadnu, znamená to všetky udalosti. Podpisové tajomstvo sa zobrazí raz, pri pridaní koncového bodu. Vtedy ho skopírujte. Ak sa stratí, koncový bod odstráňte a pridajte znova, čím získate nové.

Každé doručenie je podpísané. Hlavička podpisu obsahuje HMAC-SHA256 časovej pečiatky a tela spojených bodkou, vypočítaný s vaším podpisovým tajomstvom, a samostatná hlavička nesie časovú pečiatku. Na svojej strane ho prepočítajte a porovnajte skôr, než obsahu uveríte. Referenčná príručka API obsahuje ukážkový kód v Node.js a Pythone a odmietanie starých časových pečiatok vás chráni pred opakovane prehranými požiadavkami.

Dobrý a slabý prijímač webhookov

DobrýSlabý
PodpisOverený pri každej požiadavkeDôveruje sa mu bez kontroly
Odpoveď2xx do niekoľkých sekúnd, práca zaradená na neskôrPomalé spracovanie pred odpoveďou
DuplikátyBezpečne zvládne rovnakú udalosť dvakrátVytvorí dva záznamy
ZlyhaniaUpozorní, keď doručenia zlyhávajúTicho, kým si to niekto nevšimne

Váš koncový bod musí odpovedať stavom 2xx do 10 sekúnd. Neúspešné doručenie sa skúša znova, celkovo najviac šesťkrát, a koncový bod, ktorý zlyhá 50-krát po sebe, sa vypne. Každý riadok na stránke Vývojári zobrazuje posledný stav HTTP a počet neúspešných doručení a Odoslať test pošle jednu podpísanú testovaciu udalosť, aby ste videli, čo váš server odpovie.

Kontrolný zoznam pred spustením

Skôr než integráciu zapnete

  • Viete, aké rozsahy má kľúč, a nemá ich viac, než je potrebné
  • Kľúč je uložený v úložisku tajomstiev, nie v zdrojovom kóde
  • Podpisy webhookov sa overujú a staré časové pečiatky sa odmietajú
  • Prijímač odpovedá rýchlo a zvláda duplicitné udalosti
  • Odpovede o limite požiadaviek a odmietnutí sa spracúvajú bez tesných cyklov opakovania
  • Testovali ste v režime sandbox a na koncovom bode ste stlačili Odoslať test
  • Je určený človek, ktorý dostane upozornenie, ak doručenia začnú zlyhávať

Ako na to v Call

V Call otvorte Nastavenia, potom Referenčná príručka API a preštudujte si koncové body, a Nastavenia, potom Vývojári, kde skopírujete ID organizácie, skontrolujete kľúče a pridáte webhook. Koncové body môžu pridávať, testovať a odstraňovať vlastníci, administrátori a manažéri; ostatní vidia zoznam. Ak používate aj funkcie AI agenta, ID agenta na tej istej stránke slúži pre koncový bod chatu. Hlasovej stránke produktu sa venuje článok Nastavenie AI agenta v Call.

Často kladené otázky

Ako získam kľúč API?

Kľúče vydáva prevádzkovateľ vášho pracovného priestoru; v aplikácii sa vytvoriť nedajú. Požiadajte oň a uveďte, aké rozsahy potrebuje. Celý kľúč sa zobrazí raz pri vydaní.

Čo znamená odpoveď 429?

Kľúč vyčerpal svoje požiadavky na aktuálnu minútu. Počkajte počet sekúnd uvedený v hlavičke X-RateLimit-Reset, potom to skúste znova a hromadnú prácu rozložte na dlhšie obdobie.

Ako overím, že webhook naozaj prišiel z Call?

Vypočítajte HMAC-SHA256 časovej pečiatky a tela s vaším podpisovým tajomstvom a porovnajte ho s hlavičkou podpisu. Referenčná príručka API uvádza príklady v Node.js a Pythone.

Môžem posielať webhooky na lokálny vývojový server?

Nie priamo. Koncové body musia byť verejné adresy https, preto použite tunelovací nástroj, ktorý váš lokálny server na takej adrese sprístupní.

Prečo bolo moje volanie API na uskutočnenie hovoru odmietnuté?

Hovory uskutočnené cez API prechádzajú rovnakou kontrolou súladu ako hovory z pracoviska. Číslo zo zoznamu nevolať alebo hovor mimo povolených hodín sa odmietne.

Kto môže vidieť a meniť webhooky?

Zoznam si môže prečítať každý, no koncové body môžu pridávať, testovať alebo odstraňovať len vlastníci, administrátori a manažéri.

Otvorte referenčnú príručku API Call a pridajte koncový bod webhooku

V demo konzole si môžete vyskúšať prichádzajúce hovory v simulácii.

Súvisiace príručky