Korzystanie z Call

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.

Redakcja Call · Opublikowano · Czas czytania: 5 min

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.

Programista sprawdza integrację na laptopie obok telefonu biurkowego
Obraz poglądowy

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.

ZakresNa co pozwala
readOdczyt kontaktów, połączeń, kolejek, członków zespołu, raportów i listy zastrzeżonych numerów.
writeTworzenie i aktualizacja kontaktów, zapisywanie wyników połączeń, dodawanie numerów do listy zastrzeżonych numerów.
callsWykonywanie i kończenie połączeń.
adminZarzą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ę.

Obsługa nieudanego żądania

  1. Odczytaj statusCzy to błąd klienta, który możesz naprawić, czy błąd serwera, który warto ponowić?
  2. Odczytaj kodRozgałęziaj logikę według kodu, nigdy według treści komunikatu.
  3. Wycofaj sięPrzy 429 poczekaj na czas z nagłówka resetu; przy błędach serwera ponów kilka razy z rosnącymi odstępami.
  4. Zapisz szczegółyZachowaj endpoint, kod i czas, żeby wsparcie mogło to prześledzić.
  5. 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

DobrySłaby
PodpisWeryfikowany przy każdym żądaniuPrzyjmowany bez sprawdzania
Odpowiedź2xx w ciągu kilku sekund, praca odłożona do kolejkiPowolne przetwarzanie przed odpowiedzią
DuplikatyBezpiecznie przyjmuje to samo zdarzenie dwa razyTworzy dwa rekordy
AwarieAlarmuje, 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.

Otwórz dokumentację API Call i dodaj endpoint webhooka

W konsoli demo możesz wypróbować połączenia przychodzące w symulacji.

Powiązane poradniki