Sign inGet Started

Ihre erste WhatsApp-Nachricht senden

Senden Sie mit Bird WhatsApp eine WhatsApp-Nachricht an Ihr eigenes Telefon und rufen Sie die Nachricht anschließend ab, um die Zustellung zu bestätigen. Vom Unternehmen initiierte Nachrichten verwenden eine vorab genehmigte Vorlage. Dieser Schnellstart sendet aus dem verwalteten Vorlagenkatalog von Bird (etwa bird_delivery_update oder bird_otp), der einen gemeinsam genutzten, von Bird verwalteten WhatsApp-Absender verwendet. Sie müssen vorher weder ein WhatsApp Business Account verbinden noch eine Nummer registrieren.

Stellen Sie vorab sicher, dass das Wallet Ihrer Organisation Guthaben hat. WhatsApp-Vorlagennachrichten werden vom Wallet abgebucht, und Bird lehnt eine Nachricht, die das Guthaben nicht deckt, mit 402 WalletInsufficientBalance ab. Wie Sie Guthaben aufladen, erfahren Sie unter Zahlungsmethoden und Wallet.

1. Einen API-Schlüssel erstellen

Öffnen Sie im Dashboard Platform tools > API keys und erstellen Sie einen Schlüssel mit dem Scope whatsapp:write, der das Senden und Lesen von Nachrichten abdeckt. Schlüssel gelten jeweils für eine Region und sehen aus wie bk_us1_... oder bk_eu1_.... Die Region im Präfix gibt an, welchen API-Host Sie aufrufen: https://us1.platform.bird.com oder https://eu1.platform.bird.com.

Die Seite API Keys im Bird-Dashboard mit einer Liste der Schlüssel samt maskiertem Präfix, Scopes und Zeitpunkt der letzten Nutzung

Der vollständige Schlüssel wird nur einmal angezeigt, beim Erstellen. Speichern Sie ihn an einem sicheren Ort und exportieren Sie ihn dann für die cURL-Beispiele:

Codebeispiel
export BIRD_API_KEY="bk_us1_..."

2. Eine Vorlagennachricht senden

Senden Sie die vorab genehmigte Vorlage bird_delivery_update aus dem verwalteten Katalog von Bird an Ihr Telefon, oder verwenden Sie bird_otp, um einen einmaligen Bestätigungscode zu senden. Verwaltete Vorlagen beginnen mit bird_ und werden von einer gemeinsam genutzten Bird-Nummer gesendet, daher lassen Sie from weg. Installieren Sie das Bird SDK für Ihre Sprache anhand des zugehörigen SDK-Schnellstarts. Wenn Sie den Tab Bird CLI verwenden, installieren Sie es zuerst (curl -fsSL https://cli.bird.com/install.sh | sh) und authentifizieren Sie sich mit Schreibzugriff (bird auth login --scope whatsapp:write).

Ersetzen Sie in den SDK-Tabs den Beispiel-API-Schlüssel und ersetzen Sie +15551234567 durch Ihre Mobilnummer im Format E.164. Die CLI verwendet Ihre Anmeldung, der cURL-Tab verwendet BIRD_API_KEY.

import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({ apiKey: "bk_XXXXXXXXXXXXXXXXXXXXXXXX" });

const msg = await bird.whatsapp.send({
  to: "+15551234567",
  template: {
    slug: "bird_delivery_update",
    components: [
      {
        type: "body",
        parameters: [
          { type: "text", name: "ref", text: "A1B2C3D4" },
          { type: "text", name: "date", text: "10 Jul 2026" },
        ],
      },
    ],
  },
});

console.log(msg.id, msg.status);

Wenn Ihr Schlüssel mit bk_eu1_ beginnt, rufen Sie stattdessen https://eu1.platform.bird.com auf.

Die API antwortet mit 202 Accepted und der erstellten Nachricht. Ihre id beginnt mit wam_, und ihr status ist accepted: Bird hat die Nachricht angenommen und stellt sie asynchron zu. Notieren Sie sich die id für den nächsten Schritt.

3. Zustellstatus prüfen

Rufen Sie die Nachricht über ihre wam_-ID ab. Ersetzen Sie WHATSAPP_MESSAGE_ID durch die id aus Schritt 2 und den Beispielschlüssel für API in den SDK-Tabs durch Ihren eigenen:

import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({ apiKey: "bk_XXXXXXXXXXXXXXXXXXXXXXXX" });

const msg = await bird.whatsapp.get("WHATSAPP_MESSAGE_ID");

console.log(msg.id, msg.status);

Das Feld status gibt an, wo sich die Nachricht befindet:

  • accepted: Bird hat die Nachricht angenommen und bereitet die Übergabe an WhatsApp vor.
  • sent: WhatsApp hat die Nachricht angenommen, und sent_at hält den Zeitpunkt fest.
  • delivered: WhatsApp hat die Zustellung auf das Gerät des Empfängers bestätigt, und delivered_at hält den Zeitpunkt fest. Wenn der Empfänger die Nachricht liest, wird read_at gesetzt, während status auf delivered bleibt.
  • failed oder rejected: Die Nachricht hat das Telefon nicht erreicht. last_error nennt den Grund, und Message status events listet die Fehlercodes auf.

Fragen Sie den Status ab, bis er accepted und sent verlässt, oder abonnieren Sie WhatsApp-Webhooks, um jede Änderung des Zustell- und Lesestatus zu erhalten (whatsapp.sent, whatsapp.delivered, whatsapp.read, whatsapp.failed). Gemeinsam genutzte, von Bird verwaltete Nummern senden nur ausgehend und leiten eingehende Antworten nicht an Ihren Workspace weiter. Um Antworten zu empfangen, verbinden Sie Ihre eigene Nummer. Jede Nachricht erscheint außerdem mit ihrem Ereignisverlauf auf der Seite Messages.

Fehlgeschlagenen Versand beheben

  • 402 WalletInsufficientBalance: Das Guthaben im Wallet reicht für die Nachricht nicht aus. Laden Sie das Wallet auf und senden Sie die Nachricht erneut.
  • 403 InsufficientScope: Dem API-Schlüssel fehlt der Scope whatsapp. Bearbeiten Sie die Scopes des Schlüssels oder erstellen Sie einen Schlüssel mit whatsapp:write.
  • 422 WhatsAppInvalidRecipient: Die Nummer in to ist keine gültige Telefonnummer im E.164-Format. Prüfen Sie das führende +, die Ländervorwahl und die Teilnehmerziffern.

Nächste Schritte

  • WhatsApp-Nachrichten senden: Senden Sie Vorlagen und frei formulierte Servicenachrichten innerhalb des 24-stündigen Kundenservice-Fensters.
  • WhatsApp-Vorlagen: Durchsuchen Sie den verwalteten Katalog (bird_otp, bird_delivery_update und weitere) oder erstellen Sie eigene Vorlagen.
  • Telefonnummer verbinden: Verbinden Sie Ihr eigenes WhatsApp Business Account und Ihre eigene Absendernummer, damit Ihr Workspace auch eingehende Antworten empfangen kann.
  • WhatsApp-Webhooks: Empfangen Sie Zustellbestätigungen und Lesebestätigungen (sowie eingehende Nachrichten, wenn Sie Ihre eigene verbundene Nummer verwenden).
  • WhatsApp API-Referenz: das vollständige Schema für Anfragen und Antworten.