FAQ WhatsApp API

Zainstaluj SDK, pobierz klucz API i wywołaj endpoint wysyłki z wcześniej zatwierdzonym szablonem. Bird zapewnia zarządzane numery nadawców, więc nie ma etapu provisioningu numeru przed pierwszym wysłaniem.

Jeden endpoint wysyłki obsługujący szablony lub treści dowolne, wstępnie zatwierdzony katalog szablonów, zdarzenia dostarczenia i potwierdzenia odczytu przez API i webhooki, oś czasu zdarzeń dla każdej wiadomości, wiadomości przychodzące i multimedia, zagregowane metryki dostarczeń oraz numery nadawcze zarządzane przez Bird do pierwszej wysyłki. Te same klucze API i regionalne hosty co Bird Email i SMS.

Oznacza, że Bird przyjął Twoją wiadomość i dostarczy ją asynchronicznie. Odpowiedź 202 nie jest potwierdzeniem dostarczenia. Dostarczenie, potwierdzenia odczytu i błędy przychodzą później jako zdarzenia, które możesz odpytywać lub odbierać przez webhooki.

Jedno i drugie. Szablon dociera do każdego w dowolnym momencie, dlatego jest jedynym sposobem na rozpoczęcie konwersacji. Treść dowolna dociera do kontaktu w 24-godzinnym oknie obsługi klienta, które otwiera jego własna wiadomość, i tylko z numeru należącego do Twojego workspace'u. Bird nie śledzi tego okna za Ciebie, więc wysyłka dowolnej treści poza oknem zostanie przyjęta, a następnie zakończy się błędem service_window_expired.

Tak. Wiadomość od kontaktu trafia na webhook whatsapp.received, pojawia się w logu WhatsApp w panelu i jest uwzględniana w zakładce Inbound na stronie Metrics. Wiadomości przychodzące docierają wyłącznie na Twoje własne numery: numery zarządzane przez Bird są współdzielone między workspace'ami, więc wiadomość wysłana na taki numer nie zostanie zarejestrowana dla Twojego workspace'u.

Za wiadomość, w zależności od kategorii szablonu (uwierzytelnianie, użytkowy lub marketingowy) i kraju odbiorcy. Opłata naliczana jest w momencie przyjęcia wiadomości przez Bird, a nie gdy odbiorca ją przeczyta.

Wyższa stawka za wiadomość pobierana przez Meta, gdy Twoja firma znajduje się poza krajem odbiorcy i wysyłasz szablony uwierzytelniania. Kwalifikacja rozpoczyna się po wysłaniu ponad 750 000 wiadomości z szablonami uwierzytelniania do użytkowników w jednym kraju w ciągu ruchomego 30-dniowego okresu. Główna lokalizacja Twojej firmy, ustawiona w Meta Business Manager, określa, które wysyłki się kwalifikują.

Współdzieleni nadawcy zawsze płacą stawkę międzynarodową za szablony uwierzytelniające, niezależnie od progu wolumenu. Wszystkie numery WhatsApp są obecnie zarządzane przez Bird, więc ta stawka dotyczy wysyłek uwierzytelniających, gdy Twoja firma znajduje się poza krajem odbiorcy.

Strony Użycie i Wydatki w panelu pokazują Twoje koszty WhatsApp. Dziennik wiadomości pokazuje kategorię i koszt każdej pojedynczej wiadomości po jej wycenie.

Nie. Każda wiadomość WhatsApp to oddzielne wywołanie API do POST /v1/whatsapp/messages z jednym odbiorcą. Aby wysłać do wielu odbiorców, iteruj po endpoincie wysyłki.

Grupa rate whatsapp_send dotyczy endpointu wysyłki. Każda odpowiedź zawiera nagłówek IETF RateLimit z pozostałą pulą i czasem resetu, więc dostosuj tempo do niego zamiast do zakodowanej na stałe liczby. Płatne plany zwiększają bazowy limit.

Tak, jako treść dowolna. Endpoint wysyłki obsługuje obrazy, wideo, audio, naklejki, dokumenty i lokalizację obok tekstu. Jak każda wysyłka dowolnej treści, każda z nich wymaga otwartego 24-godzinnego okna obsługi klienta i numeru należącego do Twojego workspace'u. Parametry szablonów pozostają wyłącznie tekstowe.

Wstępnie zatwierdzona struktura wiadomości zarejestrowana w WhatsApp za pośrednictwem Meta. Każdy szablon ma nazwę, jeden lub więcej języków, kategorię (uwierzytelnianie, użytkowy lub marketingowy) oraz zmienne zastępcze, które wypełniasz w momencie wysyłki. Bird dostarcza zarządzany katalog, który możesz od razu wysyłać, a po podłączeniu WhatsApp Business Account możesz tworzyć własne szablony.

Meta weryfikuje i zatwierdza każdy szablon, niezależnie od tego, czy został przesłany przez Bird, czy przez Ciebie. Szablon może być aktywny ogólnie, ale poszczególne wersje językowe mogą mieć status odrzucony lub wstrzymany — sprawdź status dla danego języka przed wysyłką w tym języku.

Uwierzytelnianie (jednorazowe kody dostępu i procesy logowania), użytkowe (aktualizacje zamówień, powiadomienia o koncie) i marketingowe (promocje i oferty). Kategoria określa, który numer nadawcy Bird wybiera i jak wiadomość jest wyceniana.

Podczas wysyłki przekaż tablicę components z parametrami body i button. Parametry mogą być nazwane (dopasowane po kluczu, np. 'name') lub pozycyjne (dopasowane po indeksie). Parametry nazwane są bezpieczniejsze, gdy kolejność zmiennych w szablonie może się zmienić.

Tak, na stronie Templates w panelu, po podłączeniu własnego WhatsApp Business Account do workspace'u. Kreator obsługuje obecnie tekst główny w jednym języku. Tworzenie szablonów przez publiczne API nie jest dostępne, ale endpoint wysyłki przyjmuje każdy szablon, który Twój workspace może wysłać — zarządzany lub własny.

Nie. Bird zapewnia zarządzane numery nadawców. Szablony uwierzytelniania wysyłane są z dedykowanego numeru, a szablony użytkowe i marketingowe współdzielą numer powiadomień. Strona Numery w dashboardzie wyświetla numery dostępne dla Twojego workspace'u.

Tak, a podłączenie własnego numeru odblokowuje wysyłkę jako Twoja marka: własne szablony, treści dowolne w otwartym oknie obsługi klienta i wiadomości przychodzące. Numery zarządzane przez Bird są współdzielone między workspace'ami i obsługują wyłącznie zarządzane szablony, dlatego traktuj je jako ścieżkę szybkiego startu do pierwszej wysyłki, a nie rozwiązanie docelowe.

W przypadku szablonu zarządzanego — według jego kategorii: uwierzytelnianie korzysta z dedykowanego numeru nadawczego, a użytkowy i marketingowy współdzielą numer powiadomień. Wszystko inne wskazuje własnego nadawcę w polu from, który musi być numerem należącym do Twojego workspace'u, a szablon, który sam utworzyłeś, musi znajdować się na tym samym WhatsApp Business Account co ten numer.

Wyślij POST na /v1/whatsapp/messages z numerem telefonu odbiorcy w formacie E.164, slugiem szablonu i wartościami zmiennych szablonu. Bird waliduje żądanie, zwraca 202 z identyfikatorem wiadomości i dostarcza ją asynchronicznie.

Dodaj nagłówek Idempotency-Key, a ponowione żądanie zwróci oryginalny wynik zamiast wysyłać wiadomość ponownie. Bez niego ponowna próba jest traktowana jako nowa wiadomość, a odbiorca otrzymuje duplikat.

Tak. Tagi to maksymalnie 20 ustrukturyzowanych etykiet, według których możesz filtrować i grupować dane w dzienniku wiadomości i metrykach. Metadane to dowolny JSON (do 2 KB) zwracany wraz z wiadomością i jej zdarzeniami, przydatny do korelowania wysyłek z Twoimi własnymi systemami.

Każda zmiana stanu generuje zdarzenie webhook: accepted, sent, delivered, read, failed lub rejected. Możesz też odpytywać oś czasu zdarzeń wiadomości przez API. Status delivered oznacza, że WhatsApp potwierdził odebranie wiadomości przez urządzenie odbiorcy.

Sześć zdarzeń cyklu życia: whatsapp.accepted (Bird umieścił w kolejce), whatsapp.sent (przesłano do WhatsApp), whatsapp.delivered (urządzenie odbiorcy ją otrzymało), whatsapp.read (odbiorca ją otworzył), whatsapp.failed (WhatsApp odrzucił po przesłaniu) oraz whatsapp.rejected (Bird odrzucił przed przesłaniem, bez opłaty).

Nie. Zdarzenie odczytu oznacza, że odbiorca otworzył wiadomość, ale status wiadomości pozostaje jako dostarczona. Odczyt jest raportowany osobno jako znacznik czasu i zdarzenie whatsapp.read, a nie jako zmiana statusu.

Rejected oznacza, że Bird odrzucił wiadomość przed przesłaniem jej do WhatsApp, więc nie ponosisz opłaty. Failed oznacza, że Bird przesłał wiadomość, ale WhatsApp odmówił dostarczenia. Oba zawierają obiekt błędu z kodem, opisem i kodem błędu Meta, jeśli dotyczy.

Na dwa sposoby: pobierz oś czasu dla konkretnej wiadomości za pomocą GET /v1/whatsapp/messages/{id}/events lub zarejestruj endpoint webhook na typy zdarzeń whatsapp.* i odbieraj je na bieżąco. Strona Wiadomości w dashboardzie również wyświetla oś czasu zdarzeń dla każdej wiadomości.

Na stronie Metryki w aplikacji dashboardu WhatsApp. Pokazuje wskaźnik dostarczalności, wskaźnik błędów, zaakceptowany wolumen oraz opóźnienie dostarczania (przetwarzanie i end-to-end) dla wszystkiego, co wysyła Twój workspace.

Według numeru nadawcy, według szablonu, według kategorii szablonu i według tagu. Wskaźnik błędów, który ogólnie wygląda dobrze, często okazuje się wynikać z jednego szablonu lub jednego tagu generującego większość błędów.

Dwa rodzaje: opóźnienie przetwarzania (po stronie Bird, od przyjęcia do przesłania) i całkowite opóźnienie (end-to-end, od przyjęcia do potwierdzenia dostarczenia). Oba są raportowane na poziomach p50, p95 i p99.

Jeszcze nie dla zagregowanych statystyk. Możesz budować własne agregacje na podstawie zdarzeń webhook lub API listy wiadomości, które zawiera status i oś czasu zdarzeń dla każdej wiadomości.

WhatsApp zapewnia szyfrowanie end-to-end wiadomości między nadawcą a urządzeniem odbiorcy. Twoje wywołanie API do Bird odbywa się przez HTTPS, a zdarzenia webhook wysyłane przez Bird są podpisywane HMAC.

Każde zdarzenie jest podpisane HMAC. Zweryfikuj podpis za pomocą klucza tajnego Twojego endpointu przed przetworzeniem danych i rotuj ten klucz z poziomu panelu, gdy zajdzie taka potrzeba.

W regionie, w którym hostowana jest Twoja organizacja — us1 lub eu1. Twój klucz API zawiera tę informację w prefiksie (bk_us1_, bk_eu1_), dzięki czemu SDK i CLI automatycznie wybierają właściwy endpoint bez konieczności konfiguracji.

Tylko to, do czego go upoważnisz. Klucz zawiera listę zakresów uprawnień (scopes), każdy z poziomem odczytu lub zapisu, więc klucz wysyłający wiadomości WhatsApp nie może zarządzać Twoimi numerami ani odczytywać danych innego kanału. Klucze obsługują również listy dozwolonych adresów IP i bezpieczną rotację z konfigurowalnym okresem karencji.

Certyfikaty i dokumentacja bezpieczeństwa są dostępne na trust.bird.com. Umowa o przetwarzaniu danych, polityka prywatności i polityka dopuszczalnego użytkowania znajdują się na bird.com/legal. W sprawie kwestionariusza dla dostawców — zajmuje się tym Twój opiekun konta w Bird.