WhatsApp API FAQ

Installieren Sie das SDK, erstellen Sie einen API-Schlüssel und rufen Sie den Sende-Endpoint mit einem vorab genehmigten Template auf. Bird stellt verwaltete Absendernummern bereit – es ist kein Nummern-Provisionierungsschritt vor Ihrem ersten Versand nötig.

Ein einzelner Send-Endpoint, der ein Template oder frei formulierten Inhalt entgegennimmt, ein vorab genehmigter Vorlagenkatalog, Zustell- und Lesebestätigungs-Events über die API und Webhooks, eine Ereignis-Timeline pro Nachricht, eingehende Nachrichten und Medien, aggregierte Zustellmetriken und von Bird verwaltete Absendernummern für Ihren ersten Versand. Dieselben API-Schlüssel und regionalen Hosts wie bei Bird Email und SMS.

Sie bedeutet, dass Bird Ihre Nachricht angenommen hat und sie asynchron zustellt. Die 202 ist keine Zustellbestätigung. Zustellung, Lesebestätigungen und Fehler treffen später als Events ein, die Sie abfragen oder per Webhooks empfangen können.

Beides. Ein Template erreicht jeden Kontakt zu jeder Zeit – deshalb ist es der einzige Weg, eine Konversation zu starten. Frei formulierter Inhalt erreicht einen Kontakt innerhalb des 24-Stunden-Kundenservice-Fensters, das dessen eigene Nachricht öffnet, und nur von einer Nummer, die Ihrem Workspace gehört. Bird verfolgt dieses Fenster nicht für Sie, daher wird ein frei formulierter Versand außerhalb eines solchen Fensters zwar angenommen, schlägt dann aber mit service_window_expired fehl.

Ja. Die Nachricht eines Kontakts kommt über den whatsapp.received-Webhook an, erscheint im WhatsApp-Protokoll im Dashboard und wird auf dem Tab „Eingehend

Pro Nachricht, basierend auf der Kategorie des Templates (Authentifizierung, Utility oder Marketing) und dem Land des Empfängers. Die Berechnung erfolgt, wenn Bird die Nachricht annimmt, nicht wenn der Empfänger sie liest.

Ein höherer Preis pro Nachricht, den Meta berechnet, wenn sich Ihr Unternehmen außerhalb des Landes des Empfängers befindet und Sie Authentifizierungsvorlagen senden. Die Berechtigung beginnt, nachdem Sie innerhalb eines gleitenden 30-Tage-Zeitraums mehr als 750.000 Authentifizierungsvorlagen-Nachrichten an Nutzer in einem Land gesendet haben. Ihr primärer Unternehmensstandort, der im Meta Business Manager festgelegt wird, bestimmt, welche Sendungen qualifiziert sind.

Geteilte Absender zahlen immer den internationalen Tarif für Authentifizierungsvorlagen, unabhängig von Ihrer Volumenschwelle. Alle WhatsApp-Nummern werden derzeit von Bird verwaltet, daher gilt dieser Tarif für Authentifizierungsnachrichten, bei denen sich Ihr Unternehmen außerhalb des Landes des Empfängers befindet.

Die Seiten „Nutzung" und „Ausgaben" im Dashboard zeigen Ihre WhatsApp-Kosten. Das Nachrichtenprotokoll zeigt die Kategorie und die Kosten jeder einzelnen Nachricht, sobald sie bepreist wurde.

Nein. Jede WhatsApp-Nachricht ist ein separater API-Aufruf an POST /v1/whatsapp/messages mit einem Empfänger. Um an viele Empfänger zu senden, iterieren Sie über den Sende-Endpoint.

Die Rate-Gruppe whatsapp_send gilt für den Sende-Endpoint. Jede Antwort enthält einen IETF-RateLimit-Header mit dem verbleibenden Kontingent und der Reset-Zeit – richten Sie sich danach statt nach einer fest codierten Zahl. Kostenpflichtige Pläne erhöhen das Basislimit.

Ja, als Freiform-Inhalt. Der Send-Endpoint unterstützt Bild, Video, Audio, Sticker, Dokument und Standort neben Text. Wie bei jedem Freiform-Versand wird ein offenes 24-Stunden-Kundenservice-Fenster und eine Nummer benötigt, die Ihrem Workspace gehört. Template-Parameter selbst bleiben textbasiert.

Eine vorab genehmigte Nachrichtenstruktur, die über Meta bei WhatsApp registriert wird. Jedes Template hat einen Namen, eine oder mehrere Sprachen, eine Kategorie (Authentifizierung, Utility oder Marketing) und Platzhaltervariablen, die Sie beim Versand befüllen. Bird liefert einen verwalteten Katalog, den Sie sofort nutzen können, und Sie können eigene Templates erstellen, sobald Sie einen WhatsApp Business Account verbunden haben.

Meta prüft und genehmigt jedes Template – egal ob Bird oder Sie es eingereicht haben. Ein Template kann insgesamt aktiv sein, aber einzelne Sprachen können den Status „abgelehnt

Authentication (Einmalpasswörter und Login-Flows), Utility (Bestellupdates, Kontobenachrichtigungen) und Marketing (Werbeaktionen und Angebote). Die Kategorie bestimmt, welche Absendernummer Bird auswählt und wie die Nachricht bepreist wird.

Übergeben Sie beim Senden ein components-Array mit Body- und Button-Parametern. Parameter können benannt (zugeordnet über einen Key wie ‚name') oder positionell (zugeordnet über den Index) sein. Benannte Parameter sind sicherer, wenn sich die Variablenreihenfolge eines Templates ändern könnte.

Ja, auf der Templates-Seite im Dashboard, sobald Ihr Workspace einen eigenen WhatsApp Business Account verbunden hat. Der Builder unterstützt derzeit Fließtext in einer einzelnen Sprache. Das Erstellen über die öffentliche API ist nicht verfügbar, aber der Send-Endpoint akzeptiert jedes Template, das Ihr Workspace senden kann – verwaltet oder selbst erstellt.

Nein. Bird stellt verwaltete Absendernummern bereit. Authentifizierungs-Templates werden von einer dedizierten Nummer gesendet, Utility- und Marketing-Templates teilen sich eine Benachrichtigungsnummer. Die Nummern-Seite im Dashboard listet die für Ihren Workspace verfügbaren Nummern auf.

Ja, und die Verbindung einer eigenen Nummer ermöglicht den Versand unter Ihrer eigenen Marke: eigene Templates, Freiform-Inhalte innerhalb eines offenen Kundenservice-Fensters und eingehende Nachrichten. Von Bird verwaltete Nummern werden workspace-übergreifend geteilt und unterstützen nur verwaltete Templates – betrachten Sie sie als den einrichtungsfreien Weg zum ersten Versand, nicht als Endzustand.

Bei einem verwalteten Template richtet es sich nach der Kategorie: Authentifizierung nutzt eine dedizierte Absendernummer, während Utility und Marketing eine gemeinsame Benachrichtigungsnummer verwenden. Alles andere benennt seinen eigenen Absender im From-Feld – dieser muss eine Nummer sein, die Ihrem Workspace gehört. Ein von Ihnen erstelltes Template muss sich auf demselben WhatsApp Business Account befinden wie diese Nummer.

Senden Sie einen POST an /v1/whatsapp/messages mit der E.164-Telefonnummer des Empfängers, einem Template-Slug und Werten für die Variablen des Templates. Bird validiert die Anfrage, gibt 202 mit einer Nachrichten-ID zurück und stellt asynchron zu.

Übergeben Sie einen Idempotency-Key-Header, und eine wiederholte Anfrage gibt das ursprüngliche Ergebnis zurück, statt die Nachricht doppelt zu senden. Ohne diesen Header wird ein Retry als neue Nachricht behandelt, und der Empfänger erhält ein Duplikat.

Ja. Tags sind bis zu 20 strukturierte Labels, nach denen Sie im Nachrichtenprotokoll und in Metriken filtern und gruppieren können. Metadaten sind beliebiges JSON (bis zu 2 KB), das mit der Nachricht und ihren Events zurückgegeben wird – nützlich, um Sendungen mit Ihren eigenen Systemen zu verknüpfen.

Jede Statusänderung löst ein Webhook-Event aus: accepted, sent, delivered, read, failed oder rejected. Sie können die Event-Timeline der Nachricht auch über die API abfragen. Der Status „delivered" bedeutet, dass WhatsApp den Empfang auf dem Gerät des Empfängers bestätigt hat.

Sechs Lifecycle-Events: whatsapp.accepted (Bird hat sie in die Warteschlange gestellt), whatsapp.sent (an WhatsApp übermittelt), whatsapp.delivered (Gerät des Empfängers hat sie erhalten), whatsapp.read (Empfänger hat sie geöffnet), whatsapp.failed (WhatsApp hat sie nach der Übermittlung abgelehnt) und whatsapp.rejected (Bird hat sie vor der Übermittlung abgelehnt, keine Berechnung).

Nein. Ein Read-Event bedeutet, dass der Empfänger die Nachricht geöffnet hat, aber der Nachrichtenstatus bleibt auf „zugestellt". Die Lesebestätigung wird separat als Zeitstempel und whatsapp.read-Event gemeldet, nicht als Statusänderung.

Rejected bedeutet, dass Bird die Nachricht abgelehnt hat, bevor sie an WhatsApp übermittelt wurde – es fallen keine Kosten an. Failed bedeutet, dass Bird sie übermittelt hat, WhatsApp die Zustellung jedoch abgelehnt hat. Beide enthalten ein Fehlerobjekt mit Code, Beschreibung und Meta-Fehlercode, sofern zutreffend.

Auf zwei Wegen: Rufen Sie die Timeline für eine bestimmte Nachricht mit GET /v1/whatsapp/messages/{id}/events ab, oder abonnieren Sie einen Webhook-Endpoint für whatsapp.*-Event-Typen und empfangen Sie diese in Echtzeit. Die Nachrichten-Seite im Dashboard zeigt ebenfalls die Event-Timeline pro Nachricht an.

Auf der Metriken-Seite in der WhatsApp-Dashboard-App. Sie zeigt Zustellrate, Fehlerrate, akzeptiertes Volumen und Zustelllatenz (Verarbeitung und End-to-End) für alles, was Ihr Workspace sendet.

Nach Absendernummer, nach Template, nach Template-Kategorie und nach Tag. Eine Fehlerrate, die insgesamt unauffällig aussieht, entpuppt sich oft als ein einzelnes Template oder ein einzelner Tag, der die meisten Fehler verursacht.

Zwei: Verarbeitungslatenz (Bird-seitig, von Annahme bis Übermittlung) und Gesamtlatenz (End-to-End, von Annahme bis Zustellbestätigung). Beide werden als p50, p95 und p99 ausgewiesen.

Noch nicht für aggregierte Statistiken. Sie können eigene Aggregationen aus Webhook-Events oder aus der Nachrichtenlisten-API erstellen, die den Status und die Event-Timeline für jede Nachricht enthält.

WhatsApp bietet Ende-zu-Ende-Verschlüsselung für Nachrichten zwischen dem Absender und dem Gerät des Empfängers. Ihr API-Aufruf an Bird erfolgt über HTTPS, und Webhook-Events, die Bird an Sie sendet, sind HMAC-signiert.

Jedes Event ist HMAC-signiert. Verifizieren Sie die Signatur mit dem Secret Ihres Endpoints, bevor Sie den Payload verarbeiten, und rotieren Sie das Secret über das Dashboard, wenn nötig.

In der Region, in der Ihre Organisation gehostet wird – entweder us1 oder eu1. Ihr API-Key trägt die Region im Präfix (bk_us1_, bk_eu1_), sodass die SDKs und CLI automatisch den richtigen Endpoint wählen, ohne dass Sie einen konfigurieren müssen.

Nur das, wofür Sie ihn berechtigen. Ein Key enthält eine Liste von Scopes, jeweils mit Lese- oder Schreibzugriff. So kann ein Key, der WhatsApp-Nachrichten sendet, weder Ihre Nummern verwalten noch einen anderen Kanal lesen. Keys unterstützen außerdem IP-Allowlists und sichere Rotation mit einer konfigurierbaren Übergangsfrist.

Zertifizierungen und Sicherheitsdokumentation finden Sie unter trust.bird.com. Die Datenverarbeitungsvereinbarung, Datenschutzerklärung und Nutzungsrichtlinie finden Sie unter bird.com/legal. Für einen Vendor-Fragebogen wenden Sie sich an Ihr Bird-Account-Team.