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 pasować do szablonu w Twoim katalogu (małe litery, cyfry i podkreślenia).
• language: tag języka szablonu, np. en lub pt-BR. Pomiń, aby wysłać domyślny język szablonu; podanie języka, którego szablon nie ma, zwraca 422 z listą dostępnych. Zaakceptowana wiadomość zwraca 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 swojego nadawcę w from: wiadomość serwisowa dowolnego typu i każdy szablon utworzony w Twoim obszarze roboczym. Numer musi być numerem należącym do Twojego obszaru roboczego. Pominięcie zwraca 422 WhatsAppSenderRequired, a numer, z którego obszar roboczy nie może wysyłać, zwraca 422 WhatsAppSenderNotFound. Utworzony szablon musi też być na tym samym koncie 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 w body.
• image, video, audio, sticker, document: każdy 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, którego nie może osiągnąć, serwujący nieobsługiwany typ lub plik przekraczający limit rozmiaru dla danego typu, jest akceptowany, a następnie kończy się błędem, z media_rejected w polu last_error wiadomości i przyczyną WhatsApp w description. image, video i document przyjmują też opcjonalny caption; document przyjmuje też opcjonalny filename; audio przyjmuje opcjonalną flagę voice dla renderowania notatki głosowej.
• location: { "latitude": ..., "longitude": ... } (oba wymagane, stopnie dziesiętne) plus opcjonalne name i address.
• contact_cards: tablica do pięciu kontaktów udostępnionych w jednej wiadomości. name każdej wizytówki 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 dodaje do wizytówki przycisk otwierający z nią czat.
• interactive: tekst body plus element do dotknięcia, w jednym z sześciu typów: przyciski odpowiedzi, menu listowe, przycisk z linkiem, karuzela medialna lub pojedynczy przycisk proszący odbiorcę o lokalizację lub numer telefonu. Wiadomości interaktywne opisują kształt protokołu każdego typu, odpowiedzi generowane przez dotknięcie i 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 strukturyzowanych 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 muszą być unikalne w ramach 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 tagu.
• metadata: jeden dowolny obiekt JSON, do 2 KB po serializacji, na kontekst per wysyłka, 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

Koszty i rozliczenia

• 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żytkowników w zakresie firmy: adresowanie kontaktu, który skontaktował się z Tobą bez numeru telefonu
• Szablony: przeglądaj katalog i odczytuj zmienne szablonu
• Idempotencja: bezpieczne ponawianie z nagłówkiem Idempotency-Key