Sign inGet Started

WhatsApp-Vorlagen

Vom Unternehmen initiierte WhatsApp-Nachrichten verwenden eine vorab genehmigte Vorlage. Eine Vorlage enthält festen Text und Variablen, sodass ein Versand nur Werte wie einen OTP-Code oder eine Bestellnummer liefert.
Bird liefert einen verwalteten Katalog, registriert dessen Inhalte bei WhatsApp und versendet ihn über die eigenen Nummern von Bird; die Slugs beginnen mit bird_. Ein Workspace, der eine eigene Nummer verbunden hat, kann auch Templates auf seinem eigenen WhatsApp Business Account erstellen. Die Seite Templates zeigt jedes Template, das der Workspace senden kann, und wie es gerendert wird.
Die WhatsApp-Vorlagenseite im Bird-Dashboard mit der Vorlagenliste. Über der Tabelle befinden sich ein Suchfeld sowie Filter für Status und Kategorie. Jede Zeile zeigt den Status einer Vorlage (Entwurf oder Aktiv), ihren Namen und Slug, ihre Kategorie, die verfügbaren Sprachen, das zugehörige WABA und den Zeitpunkt der letzten Änderung.

Vorlagen im Dashboard durchsuchen

Öffnen Sie Templates unter WhatsApp > Templates. Your templates enthält die Vorlagen, die dieser Workspace erstellt hat; All templates ergänzt den von Bird verwalteten Katalog. Suchen Sie nach Name oder filtern Sie nach Status und Kategorie und wechseln Sie mit dem Schalter neben den Filtern zwischen Kachelansicht und Listenansicht.
In der Listenansicht zeigt jede Zeile die Felder, die Sie brauchen, um eine Vorlage auszuwählen und zu senden:
  • Status: ob die Vorlage insgesamt sendbar ist. Verwaltete Katalogvorlagen zeigen active; eine eigene Vorlage zeigt den aktuellen Stand ihrer Genehmigung. Prüfen Sie die Sprachliste, um sicherzustellen, dass die benötigte Sprache verfügbar ist.
  • Name: die Anzeigebezeichnung, mit dem slug der Vorlage darunter. Senden Sie mit dem slug.
  • Languages: die Sprachen, in denen die Vorlage registriert ist, z. B. Englisch und Niederländisch.
  • Category: authentication, utility oder marketing. Die Kategorie bestimmt, wie WhatsApp die Nachricht behandelt, von welcher Bird-Nummer eine verwaltete Vorlage gesendet wird, und zusammen mit dem Zielland den Preis.
  • WABA: Bird-managed bei Katalogvorlagen. Eine eigene Vorlage zeigt den WhatsApp Business Account, dem sie gehört, und sendet nur über eine Nummer auf demselben Account.
  • Updated: wann die Vorlage zuletzt geändert wurde.
Klicken Sie auf eine Zeile, um die Detailansicht der Vorlage zu öffnen.

Was eine Vorlage enthält

Die Detailansicht rendert den Nachrichtentext, die Variablen und die Buttons in einer WhatsApp-ähnlichen Vorschau.
Die Detailansicht bietet außerdem ein cURL-Beispiel für POST /v1/whatsapp/messages, das den regionalen Host und die Beispielwerte der Vorlage verwendet. Ersetzen Sie den API-Schlüssel, den Empfänger und die Variablenwerte vor dem Senden.
Das Beispiel ist der schnellste Weg, die Struktur zu sehen, der ein Versand entsprechen muss. Über die API erhalten Sie denselben Inhalt aus der Version der Vorlage (Inhalt einer Vorlage lesen).

Vorlagen über die API auflisten

GET /v1/whatsapp/templates gibt einen cursorpaginierten Katalog zurück. Die Anfrage erfordert whatsapp_management-Lesezugriff. Verwenden Sie HTTP oder eine SDK-Raw-Request-Methode.
type Templates = { data: Array<{ slug: string; status: string }> };

const templates = await bird.request<Templates>({
  method: "GET",
  path: "/v1/whatsapp/templates",
});
Jeder Eintrag identifiziert die Vorlage, ihre Kategorie und die verfügbaren Sprachen. Lesen Sie die Live-Version separat für den Nachrichteninhalt.
Codebeispiel
{
  "available_languages": ["en", "es", "pt-BR", "..."],
  "category": "authentication",
  "default_language": "en",
  "description": "One-time passcode",
  "id": "wat_01ky4x8e4genzb7way45txfkm1",
  "languages": {
    "en": { "status": "approved" },
    "es": { "status": "approved" },
    "pt-BR": { "status": "approved" },
    "...": "..."
  },
  "name": "bird_otp",
  "on_missing_language": "fail",
  "scope": "system",
  "slug": "bird_otp",
  "status": "active"
}
Die Beispielantwort kürzt die bird_otp-Sprachlisten ab.
Die Felder, von denen ein Versand abhängt:
  • slug: das Handle, das beim Senden verwendet wird. Slugs verwalteter Vorlagen beginnen mit bird_, einem für sie reservierten Präfix.
  • waba: der WhatsApp Business Account, der die Sprachen der Vorlage bei Meta hält, und der Account, zu dem eine Absendernummer gehören muss. Fehlt bei verwalteten Vorlagen, weil Bird den Account verwaltet.
  • available_languages: Sprachen, die gesendet werden können. Eine pausierte, deaktivierte, archivierte oder eingeschränkte Sprache verlässt diese Liste.
  • on_missing_language: was passiert, wenn die angeforderte Sprache nicht verfügbar ist. Von Bird verwaltete WhatsApp-Vorlagen verwenden fail, das den Versand ablehnt, anstatt eine andere Sprache einzusetzen.

Status und Sprachstatus

Von Bird verwaltete Vorlagen zeigen status: active. languages.<tag>.status gibt den Zustand von WhatsApp für eine Sprache an, z. B. approved, paused oder disabled.
Eine aktive Vorlage kann dennoch eine nicht verfügbare Sprache haben. Verwenden Sie available_languages, um zu entscheiden, ob eine Sprache sendbar ist.

Inhalt einer Vorlage lesen

Nachrichteninhalt gehört zu einer Sprache in der Live-Version. Lesen Sie live_version_id aus der Vorlage und fordern Sie dann die benötigte Sprache an:
const language = await bird.request({
  method: "GET",
  path: "/v1/whatsapp/templates/bird_order_confirmation/versions/{version_id}/languages/en",
});
Die Vorlagenreferenz akzeptiert eine slug- oder wat_-ID. GET …/versions/{version_id}/languages listet die Sprachen der Version ohne deren Inhalt auf.
Codebeispiel
{
  "category": "utility",
  "components": [
    {
      "example_parameters": [
        { "name": "ref", "text": "A1B2C3D4", "type": "text" },
        { "name": "amount", "text": "USD 49.99", "type": "text" }
      ],
      "text": "Your order {{ref}} has been confirmed for a total of {{amount}}. Thanks for shopping with us.",
      "type": "body"
    }
  ],
  "language": "en",
  "status": "approved"
}
Die components des Versands muss mit der Vorlage übereinstimmen. example_parameters identifiziert jeden Platzhalter. In diesem Beispiel verwenden die Body-Parameter name: "ref" und name: "amount". Eine positionelle Vorlage lässt name weg und nimmt Werte in {{n}}-Reihenfolge entgegen. Parametrisierte Buttons haben eigene example_parameters.
Die category der Sprache ist die Meta-Kategorie für die Preisberechnung. Sie kann von der registrierten Kategorie der Vorlage abweichen, wenn Meta die Sprache umklassifiziert.
Die variables-Liste der Version fasst jeden Platzhalter mit Schlüssel, Typ, Pflichtfeld-Flag und Einschränkung zusammen. Benannte Platzhalter verwenden ihre Namen als Schlüssel. Positionelle Platzhalter verwenden ihre Nummer.

Mit einer Vorlage senden

Geben Sie die Vorlage im template-Objekt des Versands an und füllen Sie die Variablen über components; siehe WhatsApp-Nachrichten senden für die vollständige Payload:
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);

Senden nach Kategorie

Jede Vorlage trägt eine von Metas drei Kategorien, und die Kategorie bestimmt, was Sie vor einem erfolgreichen Versand tun müssen und was er kostet. Das Erstellen oder Kopieren einer eigenen Authentifizierungsvorlage erfordert ein verifiziertes Unternehmen, das Senden hingegen nicht: Die verwaltete bird_otp von Bird liegt auf dem eigenen WhatsApp Business Account von Bird und wird ohne Ihre Verifizierung gesendet. Marketing-Vorlagen werden immer von einem eigenen WhatsApp Business Account gesendet, über einen zweiten Meta-API, an den Bird automatisch weiterleitet. Utility-Vorlagen haben die wenigsten Voraussetzungen der drei.
  • Authentifizierungsvorlagen: Einmal-Bestätigungscodes, der Code-kopieren-Button und die Verifizierungsanforderung beim Erstellen
  • Utility-Vorlagen: Bestellaktualisierungen, Terminerinnerungen und Kontohinweise
  • Marketing-Vorlagen: Werbenachrichten, der benötigte Business Account und die Opt-out-Erwartung

Nächste Schritte