Wprowadzenie

Bird API to ujednolicone REST API do wszystkiego, co platforma oferuje. Ta dokumentacja referencyjna opisuje każdy publiczny endpoint i jest generowana z tej samej specyfikacji OpenAPI, która napędza oficjalne SDK, więc kształty żądań i odpowiedzi tutaj są dokładnie tym, co przechodzi przez sieć.

Pasek boczny dokumentacji grupuje najczęściej używane zasoby według produktu: Email, SMS, Voice, Realtime, Verify oraz narzędzia deweloperskie (Webhooks i Documentation, API wyszukiwania w dokumentacji). Pozostałe publiczne endpointy, w tym domeny wysyłkowe, poczta przychodząca, kontakty i grupy odbiorców oraz WhatsApp, są dostępne przez wyszukiwanie i bezpośrednie linki w przewodnikach. Sekcja Voice obejmuje połączenia, logi odcinków, trunki, numery, identyfikatory dzwoniącego, miejsca docelowe i dane uwierzytelniające sesji SIP. Statystyki Voice są nadal dostępne przez dashboard i CLI. Ustawienia obszaru roboczego, klucze API i dedykowane adresy IP są zarządzane w dashboardzie, a nie w publicznym API.

Strony zasobów są linkowane bezpośrednio z przewodników: gdy przewodnik wspomina endpoint, link prowadzi do jego wpisu w dokumentacji referencyjnej.

Konwencje

Każdy endpoint stosuje te same konwencje. Są opisane tutaj raz, zamiast powtarzać je na każdej stronie.

Ścieżka bazowa: wszystkie endpointy znajdują się pod /v1 na regionalnym hoście, np. https://us1.platform.bird.com. Zobacz Bazowe URL-e i regiony.
Uwierzytelnianie: żądania przekazują klucz API jako bearer token: Authorization: Bearer bk_us1_.... Zobacz Uwierzytelnianie.
JSON, snake_case: ciała żądań i odpowiedzi są w formacie JSON z nazwami pól w konwencji snake_case (created_at, workspace_id), a żądania muszą ustawiać Content-Type: application/json.
Znaczniki czasu: wszystkie znaczniki czasu to ciągi RFC 3339 w UTC, w polach z sufiksem _at (created_at, delivered_at). Znaczniki czasu zasobów, takie jak created_at, są przypisywane przez serwer i tylko do odczytu; kilka pól żądania, np. scheduled_at, to znaczniki czasu podawane przez ciebie.
Typowane ID zasobów: każde ID zawiera prefiks typu: em_ dla wiadomości e-mail, dom_ dla domen wysyłkowych, whk_ dla endpointów webhook, sup_ dla suppressions itd. Prefiks sprawia, że ID jest samoopisujące się w logach i zapobiega przekazaniu ID jednego zasobu tam, gdzie oczekiwane jest ID innego.
Częściowe aktualizacje używają PATCH: żądanie PATCH zmienia tylko pola, które uwzględnisz; pominięte pola pozostają bez zmian. Kilka podzasobów adresowanych po nazwie w URL-u zapisuje się za pomocą PUT, co zastępuje dany podzasób w całości.
Parametry zapytania są ścisłe: żądanie zawierające parametr zapytania, którego endpoint nie dokumentuje, jest odrzucane z kodem 422 (E01029), a nie ignorowane. Sprawdź pisownię względem listy parametrów endpointu.
Błędy: każda odpowiedź z błędem ma tę samą strukturę, zawierającą type do ogólnego rozgałęziania, stabilny code, czytelny dla człowieka message oraz request_id do podania przy kontakcie ze wsparciem. Zobacz Odpowiedzi z błędem.
Paginacja: endpointy listowe używają paginacji opartej na kursorach ze współdzielonym zestawem parametrów. Zobacz Paginacja.
Idempotentność: endpointy modyfikujące przyjmują nagłówek Idempotency-Key, dzięki czemu ponowne próby są bezpieczne. Zobacz Nagłówek Idempotency-Key.
Wycofywanie: zmienione pole nadal działa pod starą nazwą, a odpowiedź sygnalizuje to nagłówkiem Deprecation. Zobacz Wycofywanie.

Zalecani klienci

Możesz wywoływać API dowolnym klientem HTTP, ale oficjalni klienci obsługują uwierzytelnianie, wybór regionu, ponowne próby i paginację za ciebie:

Oficjalne SDK dla TypeScript, Go i Python: typowane metody na kurowanej powierzchni publicznej
Bird CLI: API z twojego terminala, odpowiedni również do skryptów i agentów

Uruchom w Postmanie

Całe API jest też kolekcją Postman, skonwertowaną z tej samej specyfikacji, z przykładowym żądaniem i odpowiedzią dla każdego endpointu. Zaimportuj środowisko dla swojego regionu, ustaw apiKey na klucz API obszaru roboczego i wyślij dowolne żądanie.

Możesz też pobrać kolekcję oraz środowisko dla us1 lub eu1 bezpośrednio.

Czytaj dalej

Uwierzytelnianie: jak żądania uwierzytelniają się na poziomie sieci
Bazowe URL-e i regiony: hosty regionalne i model regionów
Paginacja: kursory, rozmiary stron i sortowanie
Nagłówek Idempotency-Key: bezpieczne ponowne próby dla żądań modyfikujących
Odpowiedzi z błędem: odpowiedź z błędem i pełny katalog błędów
Wycofywanie: co zastąpiona nazwa pola nadal robi i jak z niej zmigrować

Powiązane zasoby

Kontynuuj z dokumentacją, przewodnikami i przykładami dotyczącymi tego tematu. Zasoby są w języku angielskim.

Zrozum koncepcjęShould I use a Bird SDK or call the API directly?Podążaj ścieżką naukiBuild your first integration Przewodnik wdrożeniowySend your first email

Uzyskaj brief wdrożeniowy