WhatsApp-Nachrichten senden

Ein minimaler Send

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"
            }
          ]
        }
      ]
    }
  }'

Das Kundenservice-Fenster

Das Payload aufbauen

Empfänger

Template

• slug (erforderlich): Der Slug des Templates, zum Beispiel bird_order_confirmation. Er muss einem Template in Ihrem Katalog entsprechen (Kleinbuchstaben, Ziffern und Unterstriche).
• language: Das Sprach-Tag des Templates, zum Beispiel en oder pt-BR. Lassen Sie es weg, um die Standardsprache des Templates zu senden; die Angabe einer Sprache, die das Template nicht hat, gibt einen 422 zurück, der die verfügbaren auflistet. Die angenommene Nachricht gibt die aufgelöste Sprache zurück.
• components: Die Werte, die die Variablen des Templates füllen (siehe Komponenten und Parameter). Lassen Sie es weg, wenn das Template keine Variablen hat.

Komponenten und Parameter

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

Kategorie und Absender

• Ein von Bird verwaltetes Template (sein Slug beginnt mit bird_) sendet von der Nummer, die Bird für diese Kategorie vorhält, daher lassen Sie from weg. Es zu setzen gibt einen 422 WhatsAppSenderNotAllowed zurück.
• Alles andere benennt seinen eigenen Absender in from: eine Service-Nachricht jedes Typs und jedes Template, das Ihr Workspace erstellt hat. Die Nummer muss eine sein, die Ihr Workspace besitzt. Sie wegzulassen gibt einen 422 WhatsAppSenderRequired zurück, und eine Nummer, von der der Workspace nicht senden kann, gibt einen 422 WhatsAppSenderNotFound zurück. Ein selbst erstelltes Template muss außerdem auf demselben WhatsApp Business Account liegen wie die Nummer, sonst gibt der Send einen 422 WhatsAppSenderWABAMismatch zurück.

Service-Nachrichten

• text: { "body": "..." }, bis zu 4096 Zeichen. Fügen Sie "preview_url": true hinzu, um eine Link-Vorschau für die erste URL in body zu rendern.
• image, video, audio, sticker, document: Jedes nimmt eine öffentliche https-URL, die WhatsApp zur Sendezeit abruft (url), sodass eine signierte URL den Send überdauern muss. Eine http-URL wird direkt abgelehnt. WhatsApp ruft die Datei selbst ab, sodass eine URL, die nicht erreichbar ist, die einen nicht unterstützten Typ liefert oder eine Datei über dem Größenlimit für ihren Typ darstellt, angenommen wird und dann fehlschlägt, mit media_rejected auf dem last_error der Nachricht und dem eigenen Grund von WhatsApp in description. image, video und document nehmen außerdem ein optionales caption; document nimmt außerdem ein optionales filename; audio nimmt ein optionales voice-Flag für ein Sprachnachrichten-Rendering.
• location: { "latitude": ..., "longitude": ... } (beide erforderlich, Dezimalgrad) plus optionales name und address.
• contact_cards: Ein Array von bis zu fünf Kontakten, die in einer Nachricht geteilt werden. Der name jeder Karte benötigt formatted_name plus mindestens einen weiteren Teil (first_name, last_name, middle_name, prefix oder suffix); phone_numbers, emails, urls und addresses nehmen jeweils bis zu zehn Einträge, und org und birthday (als YYYY-MM-DD) sind optional. Eine phone_number in E.164 verleiht dieser Karte einen Button, der einen Chat damit öffnet.
• interactive: Body-Text plus ein antippbares Element, in einem von sechs Typen: Antwort-Buttons, ein Listenmenü, ein Link-Button, ein Medien-Karussell oder ein einzelner Button, der den Empfänger nach seinem Standort oder seiner Telefonnummer fragt. Interaktive Nachrichten behandelt die Wire-Struktur jedes Typs, die Antworten, die ein Tippen erzeugt, und die Limits.

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

Eine Nachricht zitieren

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

Tags und Metadaten

• tags: Bis zu 20 strukturierte { "name": ..., "value": ... }-Labels für Dimensionen mit niedriger Kardinalität, nach denen Sie filtern und berichten (eine Kampagne, eine Experimentvariante). Namen und Werte akzeptieren ASCII-Buchstaben, Ziffern, Unterstrich und Bindestrich; Namen sind auf 32 Zeichen begrenzt und innerhalb eines Sends eindeutig, Werte auf 64. Filtern Sie die Nachrichtenliste nach Tag (?tag=campaign oder ?tag=campaign:launch-week), und die Seite Metriken schlüsselt die Zustellung nach Tag auf.
• metadata: Ein beliebiges JSON-Objekt, bis zu 2 KB serialisiert, für sendespezifischen Kontext, den Sie nicht als Filterdimension benötigen (eine interne Bestell-ID, eine Session-Referenz).

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

Feldreferenz

Das asynchrone Modell: Was 202 bedeutet

Sicher erneut versuchen

Die Antwort empfangen

Kosten und Abrechnung

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.

• Beim 202 ist cost null. Nichts wurde bepreist.
• Nach der Verarbeitung ist transaction_amount gesetzt und amount entspricht ihm. passthrough_amount bleibt null.
• Nach einer zutreffenden delivered- oder read-Quittung füllt eine erfolgreich erfasste Meta-Gebühr passthrough_amount, und amount spiegelt die erfassten Komponenten wider.

Nächste Schritte

• Service-Nachrichten: Die neun Freitext-Inhaltstypen und was jeder davon erwartet
• WhatsApp-Nachrichten empfangen: Eingehende Nachrichten, Medien und der whatsapp.received-Webhook
• Geschäftsbezogene Benutzer-IDs: Einen Kontakt adressieren, der Sie ohne Telefonnummer erreicht hat
• Templates: Den Katalog durchsuchen und die Variablen eines Templates lesen
• Senden an eine WhatsApp-Gruppe: Eine Gruppe adressieren und ihre teilnehmerbezogenen Quittungen lesen
• Idempotenz: Sichere Wiederholungen mit dem Idempotency-Key-Header