Wysyłanie wiadomości WhatsApp

Minimalna wysyłka

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

Budowanie payloadu

Odbiorca

Szablon

• 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.

Komponenty i parametry

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

Kategoria i nadawca

• 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.

Wiadomości serwisowe

• 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 }
}

Cytowanie wiadomości

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

Tagi i metadane

• 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

Model asynchroniczny: co oznacza 202

Bezpieczne ponawianie

Odbieranie odpowiedzi

Koszt i rozliczenia

Note: a service message carries no Meta share until September 30th 2026, and neither does a utility template delivered inside an open customer service window. From October 1st 2026 Meta charges for both, except inside a 72-hour free entry point window, and with 1,000 free service messages per business phone number per month: October 2026 pricing changes.

• 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.

Następne kroki

• Wiadomości serwisowe: dziewięć typów treści dowolnej i co każdy z nich przyjmuje
• Odbieranie wiadomości WhatsApp: wiadomości przychodzące, media i webhook whatsapp.received
• Identyfikatory użytkownika w zakresie firmy: adresowanie kontaktu, który skontaktował się z Tobą bez numeru telefonu
• Szablony: przeglądaj katalog i sprawdzaj zmienne szablonu
• Wysyłanie do grupy WhatsApp: adresowanie grupy i odczyt potwierdzeń per uczestnik
• Idempotentność: bezpieczne ponawianie z nagłówkiem Idempotency-Key