API a webhooky Call pro vývojáře: klíče, rozsahy, události
Praktický průvodce REST API Call: API klíče a rozsahy, limity požadavků, zpracování chyb, podepsané webhooky a stránka Vývojáři, kde spravujete koncové body.
Dříve či později musí telefonní systém komunikovat s něčím dalším: s CRM, které má zobrazit hovor hned po jeho skončení, s fakturačním nástrojem, který chce vědět, kdo volal, se skriptem, který po odeslání formuláře uskuteční hovor. Call má přesně pro tyto účely REST API a odchozí webhooky. Tento průvodce vysvětluje, jak do sebe části zapadají, o co si říct, než začnete psát kód, a chyby, které vývojáře nejčastěji stojí celé odpoledne.

Pokud potřebujete jen hromadně přesunout kontakty, přečtěte si nejprve článek Import kontaktů do CRM telefonního týmu; import bývá jednodušší než integrace.
Kde začít: referenční příručka a stránka Vývojáři
Je třeba znát dvě místa. Referenční příručka API je v Nastavení a také v nabídce Zdroje na domovské stránce. Lze ji číst bez přihlášení, což se hodí, když odhadujete práci pro klienta. Stránka Vývojáři, rovněž v Nastavení, je určena pro váš vlastní pracovní prostor: ukazuje identifikátory vaší organizace a agentů, koncové body webhooků a seznam vašich klíčů jen pro čtení.
Co které místo nabízí
- Začněte zdeZákladní URL a konvence, ověřování s tabulkou rozsahů a chyby se stavovými kódy.
- Koncové bodyKarta každého koncového bodu uvádí jeho rozsah, parametry, tělo požadavku, odpověď a chyby, s požadavky připravenými ke zkopírování v curl, JavaScriptu a Pythonu.
- VyhledáváníStisknutím / přejdete na Hledat koncové body a filtrujete podle metody, cesty, rozsahu nebo popisu.
- OpenAPI JSONStáhne celou specifikaci jako jeden soubor pro vaše vlastní nástroje.
- ID agenta / APIID a zkrácený název vaší organizace, režim API (testovací prostředí nebo ostrý provoz) a ID zvoleného AI agenta, každé s tlačítkem Kopírovat.
- WebhookyVaše koncové body, události, které každý přijímá, poslední stav HTTP a případná neúspěšná doručení.
Části o limitech požadavků a odchozích webhoocích si přečtěte před spuštěním, ne až po něm. Popisují chování, které se při rychlém testu snadno přehlédne.
API klíče a rozsahy
Každý požadavek nese klíč v hlavičce Authorization jako bearer token. Klíče se v aplikaci nevytvářejí: vydává je provozovatel platformy vašeho pracovního prostoru a sdělí vám, jaké rozsahy nesou. Celý klíč se zobrazí jen jednou, v okamžiku vydání, a poté jsou vidět jen jeho první znaky, proto ho ihned uložte do vlastního úložiště tajemství.
| Rozsah | Co umožňuje |
|---|---|
| read | Čtení kontaktů, hovorů, front, členů týmu, reportů a seznamu nevolat. |
| write | Vytváření a úprava kontaktů, zaznamenávání výsledků hovorů, přidávání čísel na seznam nevolat. |
| calls | Uskutečňování a ukončování hovorů. |
| admin | Správa webhooků; může volat i všechny ostatní koncové body. |
Žádejte nejmenší sadu, která na úkol stačí. Skript pro reporty potřebuje read a nic dalšího; tlačítko pro volání jedním kliknutím potřebuje calls. Pokud požadavek vrátí 403 s kódem insufficient_scope, klíči chybí rozsah uvedený na kartě daného koncového bodu.
Testovací prostředí a ostrý provoz
Klíče lze vydat pro testovací prostředí, které používá simulátor a neuskutečňuje skutečné hovory, nebo pro ostrý provoz. Předponu klíče berte jen jako štítek: klíč označený jako testovací pracuje se stejnými daty a stejným telefonním připojením jako ostrý, proto se na předponu nespoléhejte, že udrží pokusy mimo skutečné zákazníky. Kde se nacházíte, zjistíte podle režimu API zobrazeného na stránce Vývojáři.
Uskutečňování hovorů přes API
Veřejné koncové body pokrývají základy: kontrolu stavu, výpis hovorů, čtení jednoho hovoru, uskutečnění hovoru, zavěšení, správu webhooků a chat s AI agentem. Odchozí hovor uskutečněný přes API prochází stejnou kontrolou souladu s pravidly jako hovor z pracoviště, takže číslo na seznamu nevolat nebo mimo povolené hodiny pro volání je odmítnuto stejně, jako by tomu bylo u operátora. Napište kód tak, aby toto odmítnutí zpracoval jako běžný výsledek, ne jako chybu.
Pro návrh to má význam. Nepište smyčku, která odmítnutý hovor opakuje, dokud neprojde. Přečtěte důvod, zalogujte ho a pokračujte. Pravidla, která za odmítnutím stojí, popisují články Hlídání hodin pro volání v Call a Seznam nevolat v Call.
Limity požadavků a chyby
Každý klíč má vlastní limit požadavků za minutu, nastavený při vydání; výchozí hodnota je 120. Když klíč minutový limit vyčerpá, API odpoví 429 s kódem rate_limited a v hlavičce X-RateLimit-Reset uvede, jak dlouho čekat. Počkejte tuto dobu a pak pokračujte. Ohleduplný klient zpomalí dřív, než narazí na zeď.
- 429 rate_limited: ustupte na dobu uvedenou v hlavičce reset a hromadnou práci rozložte v čase.
- 403 insufficient_scope: klíči chybí rozsah uvedený na kartě koncového bodu; požádejte o klíč, který ho má.
- Ostatní chyby: řiďte se kódem chyby, ne zprávou. Kódy se nemění; znění ano.
Zpracování neúspěšného požadavku
- Přečtěte stavJde o chybu klienta, kterou můžete opravit, nebo o chybu serveru, kterou má smysl zopakovat?
- Přečtěte kódVětvěte podle kódu, nikdy podle textu zprávy.
- UstupteU 429 počkejte podle hlavičky reset; u chyb serveru to několikrát zkuste znovu s rostoucími prodlevami.
- Zalogujte podrobnostiUchovejte koncový bod, kód a čas, aby je podpora mohla dohledat.
- U odmítnutí přestaňteOdmítnutí kvůli souladu s pravidly je rozhodnutí, ne závada; neopakujte ho ve smyčce.
Webhooky: příjem událostí
Místo toho, abyste se API stále dokola ptali, zda se něco stalo, nechte Call, ať vám to oznámí. Na stránce Vývojáři stiskněte Přidat koncový bod, zadejte veřejnou adresu https a zaškrtněte požadované události; nezaškrtnete-li žádnou, budete dostávat všechny. Podpisové tajemství se zobrazí jen jednou, při přidání koncového bodu. Tehdy si ho zkopírujte. Pokud se ztratí, koncový bod smažte a přidejte znovu, abyste získali nové.
Každé doručení je podepsané. Hlavička s podpisem obsahuje HMAC-SHA256 časového razítka a těla spojených tečkou, vypočtený vaším podpisovým tajemstvím, a samostatná hlavička nese časové razítko. Než datům uvěříte, přepočítejte podpis na své straně a porovnejte ho. Referenční příručka API pro to obsahuje ukázkový kód v Node.js a Pythonu a odmítání starých časových razítek vás chrání před opakovaně přehrávanými požadavky.
Dobrý a špatný příjemce webhooků
| Dobrý | Špatný | |
|---|---|---|
| Podpis | Ověřuje se u každého požadavku | Důvěřuje se bez kontroly |
| Odpověď | 2xx během několika sekund, práce zařazená na později | Pomalé zpracování před odpovědí |
| Duplicity | Bezpečně zvládne stejnou událost dvakrát | Vytvoří dva záznamy |
| Selhání | Upozorní, když doručení selhávají | Mlčí, dokud si toho někdo nevšimne |
Váš koncový bod musí odpovědět stavem 2xx do 10 sekund. Neúspěšné doručení se zkouší znovu, celkem až šestkrát, a koncový bod, který selže 50krát za sebou, se vypne. Každý řádek na stránce Vývojáři ukazuje poslední stav HTTP a počet neúspěšných doručení a tlačítko Odeslat test odešle jednu podepsanou testovací událost, abyste viděli, co váš server odpoví.
Kontrolní seznam před spuštěním
Než integraci zapnete
- Víte, jaké rozsahy klíč má, a nemá jich víc, než je třeba
- Klíč je uložen v úložišti tajemství, ne ve zdrojovém kódu
- Podpisy webhooků se ověřují a stará časová razítka se odmítají
- Příjemce odpovídá rychle a zvládá duplicitní události
- Odpovědi o limitu požadavků a odmítnutí se zpracovávají bez rychlých opakovacích smyček
- Testovali jste v testovacím prostředí a u koncového bodu stiskli Odeslat test
- Je určen člověk, který dostane upozornění, pokud doručení začnou selhávat
Jak na to v Call
V Call otevřete Nastavení a poté Referenční příručku API, kde si prostudujete koncové body, a Nastavení a poté Vývojáři, kde zkopírujete ID organizace, zkontrolujete své klíče a přidáte webhook. Koncové body mohou přidávat, testovat a mazat vlastníci, administrátoři a manažeři; ostatní vidí seznam. Pokud používáte i funkce AI agenta, ID agenta na stejné stránce slouží pro koncový bod chatu. Hlasovou stránku produktu popisuje článek Nastavení AI agenta v Call.
Často kladené otázky
Jak získám API klíč?
Klíče vydává provozovatel platformy vašeho pracovního prostoru; v aplikaci je vytvořit nelze. Požádejte o klíč a uveďte, jaké rozsahy potřebuje. Celý klíč se zobrazí jednou, při vydání.
Co znamená odpověď 429?
Klíč vyčerpal své požadavky pro aktuální minutu. Počkejte tolik sekund, kolik uvádí hlavička X-RateLimit-Reset, pak to zkuste znovu a hromadnou práci rozložte do delšího období.
Jak ověřím, že webhook skutečně přišel od Call?
Vypočtěte HMAC-SHA256 časového razítka a těla svým podpisovým tajemstvím a porovnejte ho s hlavičkou podpisu. Referenční příručka API ukazuje příklady v Node.js a Pythonu.
Mohu posílat webhooky na lokální vývojový server?
Přímo ne. Koncové body musí být veřejné adresy https, proto použijte tunelovací nástroj, který váš lokální server na takové adrese zpřístupní.
Proč bylo moje volání API pro uskutečnění hovoru odmítnuto?
Hovory uskutečněné přes API procházejí stejnou kontrolou souladu s pravidly jako hovory z pracoviště. Číslo na seznamu nevolat nebo mimo hodiny pro volání je odmítnuto.
Kdo může webhooky vidět a měnit?
Seznam může číst každý, ale přidávat, testovat a mazat koncové body mohou jen vlastníci, administrátoři a manažeři.