API i webhooki Call dla programistów: klucze, zakresy, zdarzenia
Praktyczny przegląd REST API Call: klucze API i zakresy, limity zapytań, obsługa błędów, podpisane webhooki i strona Dla programistów do zarządzania endpointami.
Prędzej czy później system telefoniczny musi porozumieć się z czymś innym: z CRM, który ma pokazać połączenie zaraz po jego zakończeniu, z narzędziem rozliczeniowym, które chce wiedzieć, kto dzwonił, ze skryptem, który wykonuje połączenie po wysłaniu formularza. Właśnie do tego Call ma REST API i wychodzące webhooki. Ten przewodnik wyjaśnia, jak te elementy do siebie pasują, o co poprosić przed napisaniem kodu i jakie błędy najczęściej kosztują programistę całe popołudnie.

Jeśli chcesz po prostu przenieść kontakty hurtowo, najpierw przeczytaj tekst o imporcie kontaktów do CRM zespołu telefonicznego; import jest często prostszy niż integracja.
Od czego zacząć: dokumentacja i strona Dla programistów
Warto znać dwa miejsca.Dokumentacja API znajduje się w sekcji Ustawienia, a także w menu Zasoby na stronie głównej. Można ją czytać bez logowania, co przydaje się przy wycenie prac dla klienta. Strona Dla programistów, również w Ustawieniach, dotyczy Twojej przestrzeni roboczej: pokazuje identyfikatory organizacji i agenta, Twoje endpointy webhooków oraz listę kluczy tylko do odczytu.
Co daje każde z tych miejsc
- Zacznij tutajBazowy URL i konwencje, uwierzytelnianie z tabelą zakresów oraz błędy z kodami statusu.
- EndpointyKarta każdego endpointu podaje jego zakres, parametry, treść żądania, odpowiedź i błędy, a także gotowe do skopiowania żądania w curl, JavaScript i Pythonie.
- WyszukiwanieNaciśnij /, aby przejść do wyszukiwania endpointów i filtrować po metodzie, ścieżce, zakresie lub opisie.
- OpenAPI JSONPobiera całą specyfikację jako jeden plik do Twoich narzędzi.
- ID agenta / APIID i slug organizacji, tryb API (Sandbox lub Live) oraz ID wybranego agenta AI, każde z przyciskiem Kopiuj.
- WebhookiTwoje endpointy, zdarzenia, które odbiera każdy z nich, ostatni status HTTP i nieudane dostarczenia.
Przeczytaj sekcje o limitach zapytań i wychodzących webhookach przed uruchomieniem na produkcji, a nie po nim. Opisują zachowanie, które łatwo przeoczyć w szybkim teście.
Klucze API i zakresy
Każde żądanie zawiera klucz w nagłówku Authorization jako token typu bearer. Kluczy nie tworzy się w aplikacji: wydaje je operator Twojej przestrzeni roboczej i informuje, jakie mają zakresy. Pełny klucz jest pokazywany raz, w chwili wydania, a potem widać tylko jego pierwsze znaki, więc od razu zapisz go w swoim magazynie sekretów.
| Zakres | Na co pozwala |
|---|---|
| read | Odczyt kontaktów, połączeń, kolejek, członków zespołu, raportów i listy zastrzeżonych numerów. |
| write | Tworzenie i aktualizacja kontaktów, zapisywanie wyników połączeń, dodawanie numerów do listy zastrzeżonych numerów. |
| calls | Wykonywanie i kończenie połączeń. |
| admin | Zarządzanie webhookami; może też wywoływać wszystkie pozostałe endpointy. |
Proś o najmniejszy zestaw, który wystarczy do zadania. Skrypt raportowy potrzebuje tylko read; przycisk „kliknij, aby zadzwonić” potrzebuje calls. Jeśli żądanie zwraca 403 z kodem insufficient_scope, kluczowi brakuje zakresu podanego na karcie danego endpointu.
Sandbox i produkcja
Klucze mogą być wydane dla sandboxa, który korzysta z symulatora i nie wykonuje prawdziwych połączeń, albo do użytku produkcyjnego. Prefiks klucza traktuj wyłącznie jako etykietę: klucz oznaczony jako testowy działa na tych samych danych i tym samym połączeniu telefonicznym co produkcyjny, więc nie polegaj na prefiksie, by trzymać eksperymenty z dala od prawdziwych klientów. Sprawdzaj tryb API widoczny na stronie Dla programistów, żeby wiedzieć, gdzie jesteś.
Wykonywanie połączeń przez API
Publiczne endpointy obejmują podstawy: sprawdzenie stanu, listę połączeń, odczyt jednego połączenia, wykonanie połączenia, rozłączenie, zarządzanie webhookami i czat z agentem AI. Połączenie wychodzące wykonane przez API przechodzi tę samą kontrolę zgodności co połączenie wykonane przez konsultanta, więc numer z listy zastrzeżonych numerów lub poza dozwolonymi godzinami dzwonienia zostanie odrzucony, dokładnie tak jak w przypadku konsultanta. Pisz kod tak, by traktował takie odrzucenie jako normalny wynik, a nie błąd.
Ma to znaczenie dla projektu. Nie pisz pętli, która ponawia odrzucone połączenie, aż się uda. Odczytaj przyczynę, zapisz ją w logu i przejdź dalej. Zasady stojące za tymi odrzuceniami opisują teksty o ochronie godzin dzwonienia w Call oraz liście zastrzeżonych numerów w Call.
Limity zapytań i błędy
Każdy klucz ma własny limit zapytań na minutę, ustalany przy jego wydaniu; domyślnie to 120. Gdy klucz wyczerpie limit w danej minucie, API odpowiada kodem 429 z kodem błędu rate_limited i w nagłówku X-RateLimit-Reset podaje, ile trzeba odczekać. Odczekaj tyle i kontynuuj. Kulturalny klient zwalnia, zanim uderzy w ścianę.
- 429 rate_limited: odczekaj czas podany w nagłówku resetu i rozłóż masowe operacje w czasie.
- 403 insufficient_scope: kluczowi brakuje zakresu z karty endpointu; poproś o klucz, który go ma.
- Inne błędy: reaguj na kod błędu, a nie na komunikat. Kody się nie zmieniają, sformułowania mogą.
Obsługa nieudanego żądania
- Odczytaj statusCzy to błąd klienta, który możesz naprawić, czy błąd serwera, który warto ponowić?
- Odczytaj kodRozgałęziaj logikę według kodu, nigdy według treści komunikatu.
- Wycofaj sięPrzy 429 poczekaj na czas z nagłówka resetu; przy błędach serwera ponów kilka razy z rosnącymi odstępami.
- Zapisz szczegółyZachowaj endpoint, kod i czas, żeby wsparcie mogło to prześledzić.
- Zatrzymaj się przy odrzuceniachOdrzucenie ze względów zgodności to decyzja, a nie usterka; nie zapętlaj się na nim.
Webhooki: odbieranie zdarzeń
Zamiast raz po raz pytać API, czy coś się wydarzyło, pozwól, by Call sam Ci o tym powiedział. Na stronie Dla programistów kliknij Dodaj endpoint, wpisz publiczny adres https i zaznacz zdarzenia, które chcesz otrzymywać; brak zaznaczenia oznacza wszystkie zdarzenia. Sekret podpisujący jest wyświetlany raz, przy dodaniu endpointu. Skopiuj go wtedy. Jeśli go zgubisz, usuń endpoint i dodaj go ponownie, aby dostać nowy.
Każde dostarczenie jest podpisane. Nagłówek podpisu zawiera HMAC-SHA256 ze znacznika czasu i treści połączonych kropką, obliczony z użyciem Twojego sekretu podpisującego, a osobny nagłówek przenosi znacznik czasu. Oblicz go ponownie po swojej stronie i porównaj, zanim zaufasz danym. Dokumentacja API zawiera przykładowy kod w Node.js i Pythonie, a odrzucanie starych znaczników czasu chroni przed powtórzonymi żądaniami.
Dobry i słaby odbiornik webhooków
| Dobry | Słaby | |
|---|---|---|
| Podpis | Weryfikowany przy każdym żądaniu | Przyjmowany bez sprawdzania |
| Odpowiedź | 2xx w ciągu kilku sekund, praca odłożona do kolejki | Powolne przetwarzanie przed odpowiedzią |
| Duplikaty | Bezpiecznie przyjmuje to samo zdarzenie dwa razy | Tworzy dwa rekordy |
| Awarie | Alarmuje, gdy dostarczenia się nie udają | Cisza, dopóki ktoś nie zauważy |
Twój endpoint musi odpowiedzieć statusem 2xx w ciągu 10 sekund. Nieudane dostarczenie jest ponawiane, łącznie do sześciu prób, a endpoint, który zawiedzie 50 razy z rzędu, zostaje wyłączony. Każdy wiersz na stronie Dla programistów pokazuje ostatni status HTTP i liczbę nieudanych dostarczeń, a przycisk Wyślij test wysyła jedno podpisane zdarzenie testowe, żebyś mógł zobaczyć, co odpowiada Twój serwer.
Lista kontrolna przed uruchomieniem
Zanim włączysz integrację
- Wiesz, jakie zakresy ma klucz, i nie ma on więcej, niż potrzeba
- Klucz jest przechowywany w magazynie sekretów, a nie w kodzie źródłowym
- Podpisy webhooków są weryfikowane, a stare znaczniki czasu odrzucane
- Odbiornik odpowiada szybko i radzi sobie z powtórzonymi zdarzeniami
- Odpowiedzi o limicie zapytań i odrzuceniach są obsługiwane bez ciasnych pętli ponowień
- Testy zostały wykonane w trybie sandbox, a na endpoincie kliknięto Wyślij test
- Wskazano osobę, która dostanie alert, jeśli dostarczenia zaczną się nie udawać
Jak to zrobić w Call
W Call otwórz Ustawienia, a potem Dokumentacja API, aby poznać endpointy, oraz Ustawienia, a potem Dla programistów, aby skopiować ID organizacji, sprawdzić klucze i dodać webhook. Właściciele, administratorzy i menedżerowie mogą dodawać, testować i usuwać endpointy; pozostali widzą listę. Jeśli korzystasz też z funkcji agenta AI, ID agenta na tej samej stronie służy do endpointu czatu. O głosowej stronie produktu przeczytasz w tekście o konfiguracji agenta AI w Call.
Najczęstsze pytania
Jak uzyskać klucz API?
Klucze wydaje operator Twojej przestrzeni roboczej; nie można ich utworzyć w aplikacji. Poproś o klucz i podaj, jakich zakresów potrzebuje. Pełny klucz jest pokazywany raz, w chwili wydania.
Co oznacza odpowiedź 429?
Klucz wyczerpał limit zapytań w bieżącej minucie. Odczekaj liczbę sekund podaną w nagłówku X-RateLimit-Reset, spróbuj ponownie i rozłóż masowe operacje na dłuższy czas.
Jak sprawdzić, czy webhook naprawdę pochodzi z Call?
Oblicz HMAC-SHA256 ze znacznika czasu i treści przy użyciu swojego sekretu podpisującego i porównaj go z nagłówkiem podpisu. Dokumentacja API zawiera przykłady w Node.js i Pythonie.
Czy mogę wysyłać webhooki na lokalny serwer deweloperski?
Nie bezpośrednio. Endpointy muszą być publicznymi adresami https, więc użyj narzędzia do tunelowania, które udostępni pod takim adresem Twój lokalny serwer.
Dlaczego moje żądanie API wykonania połączenia zostało odrzucone?
Połączenia wykonywane przez API przechodzą tę samą kontrolę zgodności co połączenia od konsultantów. Numer z listy zastrzeżonych numerów lub połączenie poza godzinami dzwonienia zostanie odrzucone.
Kto może przeglądać i zmieniać webhooki?
Listę może czytać każdy, ale tylko właściciele, administratorzy i menedżerowie mogą dodawać, testować i usuwać endpointy.