Wysyłanie wiadomości WhatsApp

Ten przewodnik opisuje endpoint wysyłki, POST /v1/whatsapp/messages. Budujesz jeden payload JSON z odbiorcą i dokładnie jednym typem treści: zatwierdzonym szablonem lub wiadomością serwisową zawierającą tekst, obraz, wideo, audio, naklejkę, dokument, lokalizację, wizytówki lub element do dotknięcia. Bird zwraca 202 Accepted z identyfikatorem wiadomości i dostarcza asynchronicznie. To, którą z dwóch opcji możesz wysłać, zależy od okna obsługi klienta. Każde żądanie wysyła jedną wiadomość do jednego odbiorcy i nie ma endpointu zbiorczego.

Minimalna wysyłka

Najmniejszy prawidłowy payload to odbiorca to i template z jego slug. Dodaj language, jeśli chcesz konkretny język; pominięcie wysyła domyślny język szablonu. Zmienne zadeklarowane w szablonie wypełnij przez components.

Wywołanie curl wskazuje hosta US; jeśli Twój klucz zaczyna się od bk_eu1_, wywołaj zamiast tego https://eu1.platform.bird.com. SDK-i odczytują region z klucza, więc nie ustawiają hosta.

const msg = await bird.whatsapp.send({
  to: "+15551234567",
  template: {
    slug: "bird_otp",
    components: [{ type: "body", parameters: [{ type: "text", text: "123456" }] }],
  },
});
console.log(msg.id, msg.status);

msg = client.whatsapp.send(
    to="+31612345678",
    template="bird_otp",
    language="en",
    components=[{"type": "body", "parameters": [{"type": "text", "text": "123456"}]}],
)
print(msg.id, msg.status)

code := "123456"
msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
	To:       "+15551234567",
	Template: "bird_otp",
	Language: "en",
	Components: []bird.WhatsAppMessageTemplateComponent{{
		Type:       "body",
		Parameters: &[]bird.WhatsAppMessageTemplateComponentParameter{{Type: "text", Text: &code}},
	}},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)

$message = $bird->whatsapp->send(
    to: '+15551234567',
    template: 'bird_otp',
    language: 'en',
    components: [
        (new WhatsAppMessageTemplateComponent())
            ->setType('body')
            ->setParameters([
                (new WhatsAppMessageTemplateComponentParameter())->setType('text')->setText('123456'),
            ]),
    ],
);
echo $message->getId(), ' ', $message->getStatus();

bird whatsapp send \
  --components '[{"parameters":[{"text":"1234","type":"text"}],"type":"body"},{"parameters":[{"text":"1234","type":"text"}],"type":"button"}]' \
  --language en \
  --template bird_otp \
  --to +31612345678

curl -X POST "https://{region}.platform.bird.com/v1/whatsapp/messages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+31612345678",
    "template": {
      "slug": "bird_otp",
      "language": "en",
      "components": [
        {
          "type": "body",
          "parameters": [
            {
              "type": "text",
              "text": "1234"
            }
          ]
        },
        {
          "type": "button",
          "parameters": [
            {
              "type": "text",
              "text": "1234"
            }
          ]
        }
      ]
    }
  }'

Okno obsługi klienta

To, którą z dwóch opcji możesz wysłać, zależy od jednego stanu: czy okno obsługi klienta jest otwarte.

Kontakt otwiera okno, wysyłając wiadomość lub dzwoniąc na Twój numer biznesowy. Okno pozostaje otwarte przez 24 godziny i resetuje się za każdym razem, gdy kontakt ponownie do Ciebie napisze. Dopóki jest otwarte, możesz wysłać wiadomość serwisową, czyli dowolną treść: tekst, obraz, wideo, audio, naklejkę, dokument, lokalizację lub interaktywną. Gdy wygaśnie, dotrze do odbiorcy tylko zatwierdzony szablon, a jego odpowiedź na niego ponownie otworzy okno.

Bird śledzi okno za Ciebie, więc wiadomość serwisowa wysłana do zamkniętego okna jest odrzucana, zanim cokolwiek zostanie utworzone lub obciążone: żądanie zwraca 422 E15044 WhatsAppServiceWindowClosed. Sprawdzenie działa na zasadzie best effort i przepuszcza w razie wątpliwości, więc 202 nie jest dowodem, że okno było faktycznie otwarte w momencie wysyłki; okno, które wygaśnie między akceptacją a wysyłką, kończy się błędem asynchronicznym, z service_window_expired w polu last_error wiadomości.

Zobacz okno obsługi klienta, aby poznać pełny cykl życia: co je otwiera, co je resetuje i jak wpływa na cenę.

Budowanie payloadu

Odbiorca

to wskazuje jednego odbiorcę podanego jako numer telefonu, identyfikator użytkownika w zakresie firmy (business-scoped user ID) lub identyfikator grupy. Numer telefonu jest w formacie E.164: wiodący +, kod kraju i numer abonenta, np. +14155550100. Numer jest walidowany, więc wartość niebędąca prawdziwym, wybieralnym numerem (nieprawidłowa długość, nieprzypisany prefiks) zostaje odrzucona z 422 WhatsAppInvalidRecipient zanim cokolwiek zostanie naliczone. Nie ma tablicy odbiorców ani wysyłki zbiorczej, więc dotarcie do wielu osób niebędących w jednej grupie wymaga osobnego wywołania na odbiorcę.

Identyfikator użytkownika w zakresie firmy, np. US.13491208655302741918, adresuje kontakt, którego numeru telefonu nie masz. W ten sposób odpowiadasz kontaktowi, który skontaktował się z Tobą bez numeru. Dwie rzeczy się zmieniają: numer wysyłający musi należeć do tego samego portfolio biznesowego, do którego jest przypisany identyfikator, a szablon jednorazowego kodu weryfikacyjnego wymaga numeru telefonu. Szablon zarządzany przez Bird jest odrzucany przy akceptacji z 422 WhatsAppRecipientNotSupportedForTemplate; szablon uwierzytelniający utworzony w Twoim obszarze roboczym jest akceptowany, a następnie kończy się błędem, ponieważ Meta wymaga dla niego numeru telefonu.

to przyjmuje jeszcze jedną postać: identyfikator grupy WhatsApp, np. wag_01krdgeqcxet5s7t44vh8rt9mg, który wysyła wiadomość do każdego uczestnika tego czatu grupowego. Wysyłka grupowa pomija from i raportuje dostarczenie w skali grupy, a nie wobec pojedynczego odbiorcy, dlatego Wysyłanie do grupy WhatsApp jest opisane na osobnej stronie.

Szablon

template wskazuje wstępnie zatwierdzony szablon do wysłania:

• slug (wymagane): slug szablonu, np. bird_order_confirmation. Musi odpowiadać szablonowi w Twoim katalogu (małe litery, cyfry i podkreślenia).
• language: tag języka szablonu, np. en lub pt-BR. Pomiń, aby wysłać szablon w domyślnym języku; podanie języka, którego szablon nie posiada, zwraca 422 z listą dostępnych języków. Zaakceptowana wiadomość zawiera rozwiązany język.
• components: wartości wypełniające zmienne szablonu (zobacz Komponenty i parametry). Pomiń dla szablonu bez zmiennych.

Przeglądaj swoje szablony, ich języki i wyrenderowany podgląd każdego z nich na stronie Szablony.

Komponenty i parametry

Szablony zawierają zmienne, nazwane ({{ref}}, {{amount}}) lub numerowane ({{1}}, {{2}}). Ich wartości podajesz przez components. Każdy komponent określa type (body lub button) i tablicę parameters. Każdy parametr określa własny type (text, image, video, gif, document lub location) i zawiera odpowiednie pole: text to zwykły ciąg znaków, image/video/gif/document to publiczny https url, a location to punkt na mapie. Szablon z nazwanymi parametrami wymaga name przy każdym parametrze, dokładnie odpowiadającego nazwom zadeklarowanym w szablonie (zobacz Referencja pól). Szablon pozycyjny pomija name i przyjmuje wartości w kolejności {{n}}, więc pierwszy parametr wypełnia {{1}}. W obu przypadkach parametry niezgodne z deklaracją szablonu zwracają 422 WhatsAppTemplateParameterMismatch. Na poziomie protokołu istnieje też typ komponentu header: w szablonie zarządzanym przez Bird jest pomijany, ponieważ żaden szablon zarządzany przez Bird nie deklaruje zmiennej nagłówkowej, ale w szablonie autorstwa Twojego obszaru roboczego jest przekazywany dalej, dzięki czemu szablon narzędziowy lub marketingowy z nagłówkiem medialnym otrzymuje swój obraz.

Na przykład szablon jednorazowego kodu weryfikacyjnego, którego treść brzmi {{1}} is your verification code, a którego przycisk kopiuje kod, przyjmuje kod zarówno jako parametr body, jak i parametr button, pozycyjnie (bez name):

{
  "components": [
    { "type": "body", "parameters": [{ "type": "text", "text": "481920" }] },
    { "type": "button", "parameters": [{ "type": "text", "text": "481920" }] }
  ]
}

Kategoria i nadawca

Kategoria szablonu (authentication, utility lub marketing) określa, jak WhatsApp traktuje wiadomość, a wraz z krajem docelowym, ile kosztuje.

To, kto jest właścicielem nadawcy, decyduje, czy go podajesz:

• Szablon zarządzany przez Bird (jego slug zaczyna się od bird_) wysyła z numeru, który Bird utrzymuje dla danej kategorii, więc pomiń from. Ustawienie go zwraca 422 WhatsAppSenderNotAllowed.
• Wszystko inne podaje własnego nadawcę w from: wiadomość serwisową dowolnego typu i każdy szablon autorstwa Twojego obszaru roboczego. Numer musi należeć do Twojego obszaru roboczego. Pominięcie go zwraca 422 WhatsAppSenderRequired, a numer, z którego obszar roboczy nie może wysyłać, zwraca 422 WhatsAppSenderNotFound. Szablon autorski musi też należeć do tego samego konta WhatsApp Business Account co numer, w przeciwnym razie wysyłka zwraca 422 WhatsAppSenderWABAMismatch.

Konfiguracja numeru telefonu opisuje oba typy numerów i sposób podłączenia własnego numeru.

Wiadomości serwisowe

Zamiast template przekaż dokładnie jedno z: text, image, video, audio, sticker, document, location, contact_cards lub interactive. Wszystkie dziewięć to wiadomości serwisowe, więc wymagają otwartego okna obsługi klienta. Każde z nich wymaga też from, numeru należącego do Twojego obszaru roboczego; zarządzane numery Bird nie mogą go obsługiwać.

• text: { "body": "..." }, do 4096 znaków. Dodaj "preview_url": true, aby wyrenderować podgląd linku dla pierwszego URL-a w body.
• image, video, audio, sticker, document: każde przyjmuje publiczny URL https, który WhatsApp pobiera w momencie wysyłki (url), więc podpisany URL musi być ważny dłużej niż trwa wysyłka. URL http jest odrzucany natychmiast. WhatsApp pobiera sam plik, więc URL, do którego nie może dotrzeć, serwujący nieobsługiwany typ lub plik przekraczający limit rozmiaru dla danego typu, zostaje zaakceptowany, a następnie kończy się błędem, z media_rejected na last_error wiadomości i własnym powodem WhatsApp w description. image, video i document przyjmują też opcjonalny caption; document przyjmuje też opcjonalny filename; audio przyjmuje opcjonalną flagę voice do renderowania notatki głosowej.
• location: { "latitude": ..., "longitude": ... } (oba wymagane, stopnie dziesiętne) plus opcjonalnie name i address.
• contact_cards: tablica do pięciu kontaktów udostępnianych w jednej wiadomości. name każdej karty wymaga formatted_name plus co najmniej jednej innej części (first_name, last_name, middle_name, prefix lub suffix); phone_numbers, emails, urls i addresses przyjmują do dziesięciu wpisów, a org i birthday (jako YYYY-MM-DD) są opcjonalne. phone_number w formacie E.164 daje karcie przycisk otwierający z nią czat.
• interactive: tekst treści plus element do dotknięcia, w jednym z sześciu typów: przyciski odpowiedzi, menu listy, przycisk z linkiem, karuzela mediów albo pojedynczy przycisk proszący odbiorcę o lokalizację lub numer telefonu. Wiadomości interaktywne opisują strukturę każdego typu, odpowiedzi generowane przez dotknięcie oraz limity.

{
  "to": "+16505551234",
  "from": "+13124495648",
  "text": { "body": "Your order shipped: https://example.com/track/A1B2C3", "preview_url": true }
}

Żądanie bez treści lub z więcej niż jednym typem jest odrzucane z 422.

Cytowanie wiadomości

Ustaw in_reply_to_message_id na identyfikator wiadomości WhatsApp, aby wysłać swoją wiadomość jako odpowiedź na nią, tak jak dotknięcie odpowiedzi w aplikacji WhatsApp cytuje wiadomość. Odbiorca widzi Twoją wiadomość z cytowaną nad nią, a pole to jest zwracane przy każdym odczycie wiadomości.

Działa to też w drugą stronę: przychodząca wiadomość, którą WhatsApp oznacza jako odpowiedź, zawiera identyfikator cytowanej wiadomości w tym samym polu, dzięki czemu rozpoznajesz, na którą z Twoich wiadomości jest odpowiedź. Przychodząca wiadomość, której WhatsApp nie oznacza, nie zawiera identyfikatora, a rozwiązanie może też nie nastąpić. Aby uzyskać niezawodną korelację, używaj jawnych identyfikatorów odpowiedzi interaktywnych wraz ze stanem konwersacji lub zadania przechowywanym w Twojej aplikacji. Wychodzący metadata pozostaje na rekordzie wychodzącym i nie jest automatycznie kopiowany na odpowiedź.

Cytat jest rozwiązywany przed zaakceptowaniem wysyłki, więc cytat niemożliwy do wyrenderowania powoduje błąd samego żądania i nic nie zostaje utworzone ani naliczone. Identyfikator, który nie wskazuje żadnej wiadomości w tym obszarze roboczym, lub wskazuje wiadomość starszą niż 15 dni, przez które wiadomość można cytować, zwraca 404 E15071 WhatsAppReferencedMessageNotFound. Identyfikator wskazujący wiadomość, która nigdy nie dotarła do WhatsApp, lub wiadomość z innej konwersacji niż to i from tej wysyłki, zwraca 422 E15072 WhatsAppMessageNotQuotable. Jeśli Bird nie może połączyć się z magazynem danych, który to sprawdza, wysyłka zwraca 503 E15073 WhatsAppMessageLookupUnavailable i warto wtedy spróbować ponownie. Cytowanie działa zarówno przy wysyłce szablonu, jak i przy wysyłce dowolnej treści.

{
  "to": "+16505551234",
  "from": "+13124495648",
  "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
  "text": { "body": "Yes, that slot is still free." }
}

Tagi i metadane

Dwa opcjonalne pola dołączają do wiadomości Twój własny kontekst; oba wracają przy odczytach API i są dołączane do każdego zdarzenia webhooka dotyczącego tej wiadomości:

• tags: do 20 strukturalnych etykiet { "name": ..., "value": ... } dla wymiarów o niskiej kardynalności, po których filtrujesz i raportujesz (kampania, wariant eksperymentu). Nazwy i wartości przyjmują litery ASCII, cyfry, podkreślenie i myślnik; nazwy mają limit 32 znaków i są unikalne w obrębie wysyłki, wartości 64. Filtruj listę wiadomości po tagu (?tag=campaign lub ?tag=campaign:launch-week), a strona Metryki rozbija dostarczenia według tagów.
• metadata: jeden dowolny obiekt JSON, do 2 KB po serializacji, na kontekst specyficzny dla wysyłki, którego nie potrzebujesz jako wymiaru filtrowania (wewnętrzny identyfikator zamówienia, referencja sesji).

{
  "tags": [{ "name": "campaign", "value": "order-confirmations" }],
  "metadata": { "order_id": "ord_8271" }
}

Referencja pól

* language jest opcjonalne; pominięcie wysyła szablon w domyślnym języku. † name jest wymagane przy każdym parametrze szablonu z nazwanymi parametrami. Pomiń dla szablonu pozycyjnego. Zobacz Komponenty i parametry. ** Przekaż dokładnie jedno z: template lub pole treści wiadomości serwisowej (text, image, video, audio, sticker, document, location, interactive); zobacz Wiadomości serwisowe.

Model asynchroniczny: co oznacza 202

Pomyślne wysłanie zwraca 202 Accepted z identyfikatorem wiadomości i status: accepted. 202 jest zwracany dopiero po trwałym zaakceptowaniu wysyłki; nigdy nie zostanie zaakceptowany, a potem po cichu odrzucony. Twarde błędy, które możesz naprawić, kończą się natychmiast kodem 422: nieprawidłowy odbiorca, nieznany slug lub język szablonu, niezgodność parametrów albo wiadomość serwisowa wysłana przy zamkniętym oknie obsługi klienta (WhatsAppServiceWindowClosed). Brak środków w portfelu nie należy do nich: wysyłka zostaje zaakceptowana, a wiadomość kończy się statusem rejected z kodem insufficient_balance, gdy Bird spróbuje ją rozliczyć. Właściwe dostarczenie odbywa się asynchronicznie: wiadomość przechodzi do sent, gdy przekażemy ją do WhatsApp, a następnie do statusu końcowego (delivered lub failed) po nadejściu potwierdzenia, raportowanego przez zdarzenia, webhooki i endpointy odczytu. Potwierdzenie odczytu jest udostępniane osobno jako znacznik czasu read_at i zdarzenie whatsapp.read, a nie jako status.

Uwaga dotycząca prywatności: dla szablonów kategorii authentication API nigdy nie zwraca wypełnionych wartości. Echo 202 i każdy późniejszy odczyt zawierają pustą tablicę components dla tych wiadomości, więc kod weryfikacyjny nigdy się nie pojawia ponownie.

Bezpieczne ponawianie

Wyślij nagłówek Idempotency-Key z unikalną wartością dla każdej logicznej wysyłki, a ponowne próby staną się bezpieczne. Jeśli Twoje pierwsze żądanie się powiodło, ale nie otrzymałeś odpowiedzi (przekroczony limit czasu, zerwane połączenie), powtórzenie go z tym samym kluczem zwraca oryginalny wynik zamiast wysłać duplikat wiadomości i naliczyć za niego opłatę. Powtórzona odpowiedź zawiera nagłówek Idempotency-Replay. Zobacz idempotentność, aby poznać format klucza i czas przechowywania.

Odbieranie odpowiedzi

Wiadomości przychodzące trafiają na ten sam zasób co wychodzące i każda z nich resetuje okno serwisowe. Odbieranie wiadomości WhatsApp opisuje ich odczyt przez API, pobieranie mediów wysłanych przez kontakt oraz webhook whatsapp.received.

Koszt i rozliczenia

WhatsApp jest wyceniany za wiadomość, na podstawie kategorii szablonu i kraju odbiorcy; zobacz cennik WhatsApp. Wiadomość jest naliczana w dwóch krokach, w dwóch różnych momentach, a obiekt cost na wiadomości raportuje oba:

Obie kwoty to ciągi dziesiętne, netto (bez podatku).

Uwaga: do 30 września 2026 r. wiadomość serwisowa nie zawiera udziału Meta, podobnie jak szablon narzędziowy dostarczony w otwartym oknie obsługi klienta. Od 1 października 2026 r. Meta pobiera opłaty za oba typy, z wyjątkiem 72-godzinnego bezpłatnego okna punktu wejścia, przy czym każdy firmowy numer telefonu ma 1000 bezpłatnych wiadomości serwisowych miesięcznie: zmiany cen od października 2026 r..

Oba składniki są wyceniane na podstawie różnych danych wejściowych. Opłata Bird bazuje na kategorii wysłanego szablonu i kraju odbiorcy, który wynika z kodu kraju numeru telefonu lub, w przypadku wysyłki na identyfikator użytkownika w zakresie firmy, z dwuliterowego prefiksu tego identyfikatora. Udział Meta bazuje na kategorii, którą Meta raportuje na odpowiednim potwierdzeniu, co może się różnić od kategorii szablonu: Meta może zgłosić authentication-international, gdy mają zastosowanie jej reguły dotyczące miejsca docelowego, lokalizacji firmy i kwalifikowalności. Zobacz stawki WhatsApp authentication-international.

Odczyt cost zależy od tego, jak daleko dotarła wiadomość:

• W momencie 202 cost jest null. Nic nie zostało wycenione.
• Po przetworzeniu transaction_amount jest ustawione i amount jest mu równe. passthrough_amount pozostaje null.
• Po odpowiednim potwierdzeniu delivered lub read pomyślnie zarejestrowana opłata Meta wypełnia passthrough_amount, a amount odzwierciedla zarejestrowane składniki.

Składnik o wartości null oznacza, że w tej projekcji nie zarejestrowano kwoty; nie jest to dowód, że wiadomość była darmowa. Składnik jawnie wyceniony na zero odczytuje się jako "0.00000".

Oba naliczenia obsługują błędy inaczej. Opłata Bird działa w trybie fail-closed: gdy nie może przejść po 202, ponieważ portfel nie pokrywa wysyłki lub trasa nie ma skonfigurowanej ceny, wiadomość kończy się statusem rejected z kodem błędu insufficient_balance lub price_not_found i nic nie jest naliczane. Wiadomość rejected nigdy nie dotarła do WhatsApp, co odróżnia ją od failed. Udział Meta działa w trybie fail-open: jeśli portfel nie ma wystarczających środków lub brakuje stawki, gdy nadchodzi potwierdzenie, naliczenie jest pomijane bez cofania obserwowanego stanu wiadomości. Dostarczenie nigdy nie jest wstrzymywane przez drugie naliczenie.

Wiadomość naliczona przez Bird zachowuje tę opłatę wychodzącą, nawet jeśli dostarczenie później się nie powiedzie. Opłata Meta jest przetwarzana z odpowiedniego callbacku delivered lub read, gdy Meta raportuje regularne ceny z rozwiązywalną kategorią i miejscem docelowym. Obie ścieżki callbacku używają tej samej tożsamości opłaty i opierają się na deduplikacji usługi billingowej. Uzgadniaj powtórzone potwierdzenia z rekordami billingowymi zamiast traktować projekcję wiadomości jako trwałe potwierdzenie obciążenia. Ceny serwisowe lub bezpłatne mogą sprawić, że składnik Meta wyniesie zero; nierozwiązany składnik nie jest dowodem, że wiadomość była darmowa.

Do uzgodnień finansowych używaj księgi billingowej. Pola cost wiadomości to projekcje naliczeń i mogą być opóźnione lub niekompletne. Zobacz metryki WhatsApp, aby poznać różnicę między obserwacjami wiadomości a rekordami billingowymi.

Zdarzenia WhatsApp nie zawierają kosztu. Aby odczytać dowolny składnik, odczytaj wiadomość za pomocą GET /v1/whatsapp/messages/{id}.

Następne kroki

• Wiadomości serwisowe: wysyłaj tekst, multimedia i treści interaktywne w ramach okna obsługi klienta
• Szablony: wybierz szablon i podaj wartości jego zmiennych
• Odbieranie wiadomości WhatsApp: odczytuj odpowiedzi i pobieraj multimedia przychodzące
• Webhooki statusu wiadomości: otrzymuj powiadomienia o dostarczeniu i błędach
• Idempotentność: bezpiecznie spróbuj ponownie za pomocą nagłówka Idempotency-Key