WhatsApp-Vorlagen

Vom Unternehmen initiierte WhatsApp-Nachrichten verwenden eine vorab genehmigte Vorlage. Eine Vorlage enthält festen Text und Variablen. Beim Senden geben Sie daher nur Werte wie einen OTP-Code oder eine Bestellnummer an.

Bird stellt einen verwalteten Katalog bereit, registriert dessen Inhalte bei WhatsApp und sendet ihn von den eigenen Nummern von Bird. Die Slugs dieses Katalogs beginnen mit bird_. Ein Workspace, der eine eigene Nummer verbunden hat, kann außerdem Vorlagen in seinem eigenen WhatsApp Business Account erstellen. Die Seite Approved templates zeigt alle Vorlagen, die der Workspace senden kann, und wie jede davon dargestellt wird.

Vorlagen im Dashboard durchsuchen

Öffnen Sie Approved templates unter WhatsApp > Approved templates. Your templates enthält die Vorlagen, die dieser Workspace erstellt hat. All templates zeigt zusätzlich den von Bird verwalteten Katalog. Suchen Sie nach Namen oder filtern Sie nach Status und Kategorie. Mit dem Schalter neben den Filtern wechseln Sie zwischen Kartenraster und Listenansicht.

In der Listenansicht zeigt jede Zeile die Felder, die Sie zum Auswählen und Senden einer Vorlage brauchen:

Status: ob die Vorlage insgesamt gesendet werden kann. Vorlagen aus dem verwalteten Katalog melden active. Eine eigene Vorlage meldet den Stand ihrer eigenen Genehmigung. Prüfen Sie in der Sprachliste, ob die benötigte Sprache verfügbar ist.
Name: die Anzeigebezeichnung, darunter der slug der Vorlage. Verwenden Sie beim Senden den slug.
Languages: die Sprachen, in denen die Vorlage registriert ist, etwa 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 das WhatsApp Business Account, in dem sie liegt, und wird nur von einer Nummer desselben Accounts gesendet.
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 zeigt Nachrichtentext, Variablen und Buttons in einer Vorschau im Stil von WhatsApp.

Die Detailansicht enthält außerdem ein cURL-Beispiel für POST /v1/whatsapp/messages, das den regionalen Host und die Beispielwerte der Vorlage verwendet. Ersetzen Sie vor dem Senden den API-Schlüssel, den Empfänger und die Variablenwerte.

Am Beispiel sehen Sie am schnellsten, welche Struktur ein Sendevorgang einhalten muss. Über die API stammt derselbe Inhalt aus der Version der Vorlage (Inhalt einer Vorlage lesen).

Vorlagen über die API auflisten

GET /v1/whatsapp/templates gibt einen Katalog mit Cursor-Paginierung zurück. Die Anfrage erfordert Lesezugriff auf whatsapp_management. Verwenden Sie HTTP oder eine Methode für Raw-Requests eines SDK.

type Templates = { data: Array<{ slug: string; status: string }> };

const templates = await bird.request<Templates>({
  method: "GET",
  path: "/v1/whatsapp/templates",
});

templates = client.get("/v1/whatsapp/templates")

var out struct {
	Data []struct {
		Slug   string `json:"slug"`
		Status string `json:"status"`
	} `json:"data"`
}
if err := client.Get(context.Background(), "/v1/whatsapp/templates", &out); err != nil {
	log.Fatal(err)
}

$templates = $bird->get('/v1/whatsapp/templates');

curl https://us1.platform.bird.com/v1/whatsapp/templates \
  -H "Authorization: Bearer $BIRD_API_KEY"

Jeder Eintrag nennt die Vorlage, ihre Kategorie und ihre verfügbaren Sprachen. Den Nachrichteninhalt lesen Sie separat aus der Live-Version.

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 Sprachlisten von bird_otp ab.

Die Felder, von denen ein Versand abhängt:

slug: der Bezeichner, den ein Versand verwendet. Slugs verwalteter Templates beginnen mit bird_, einem für sie reservierten Präfix.
waba: das WhatsApp Business Account, in dem die Sprachen des Templates bei Meta liegen, und zugleich das Konto, zu dem eine Absendernummer gehören muss. Bei einem verwalteten Template fehlt das Feld, weil Bird dessen Konto verwaltet.
available_languages: Sprachen, die sich versenden lassen. Eine pausierte, deaktivierte, archivierte oder eingeschränkte Sprache fällt aus dieser Liste heraus.
on_missing_language: was passiert, wenn die angeforderte Sprache nicht verfügbar ist. Von Bird verwaltete WhatsApp-Templates verwenden fail und lehnen den Versand dann ab, statt eine andere Sprache einzusetzen.

Status und Sprachstatus

Von Bird verwaltete Templates melden status: active. languages.<tag>.status gibt den Zustand bei WhatsApp für eine einzelne Sprache an, etwa approved, paused oder disabled.

Auch ein aktives Template kann eine nicht verfügbare Sprache haben. Prüfen Sie anhand von available_languages, ob sich eine Sprache versenden lässt.

Inhalt eines Templates lesen

Der Nachrichteninhalt gehört zu einer Sprache in der Live-Version. Lesen Sie live_version_id aus dem Template 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",
});

language = client.get(
    "/v1/whatsapp/templates/bird_order_confirmation/versions/{version_id}/languages/en"
)

var language map[string]any
if err := client.Get(context.Background(),
	"/v1/whatsapp/templates/bird_order_confirmation/versions/{version_id}/languages/en",
	&language); err != nil {
	log.Fatal(err)
}

$language = $bird->get('/v1/whatsapp/templates/bird_order_confirmation/versions/{version_id}/languages/en');

curl https://us1.platform.bird.com/v1/whatsapp/templates/bird_order_confirmation/versions/{version_id}/languages/en \
  -H "Authorization: Bearer $BIRD_API_KEY"

Die Template-Referenz 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"
}

Ein Versand füllt diese Platzhalter anhand ihres Namens. example_parameters identifiziert jeden einzelnen. In diesem Beispiel nimmt parameters des Versands die Schlüssel ref und amount entgegen. Bei einer positionsbasierten Vorlage sind die Schlüssel ihre Nummern, etwa 1, mit zwei Ausnahmen: Der Code einer Authentifizierungsvorlage verwendet code, und das nummerierte Suffix eines URL-Buttons verwendet button_url. Parametrisierte Buttons haben ein eigenes example_parameters.

Die category der Sprache ist die Meta-Kategorie, nach der die Preise berechnet werden. Sie kann von der registrierten Kategorie der Vorlage abweichen, wenn Meta die Sprache neu einstuft.

Die Liste variables der Version fasst jeden Platzhalter mit Schlüssel, Typ, Pflichtkennzeichen und Einschränkung zusammen. Benannte Platzhalter verwenden ihren Namen als Schlüssel. Positionsplatzhalter verwenden ihre Nummer, mit Ausnahme eines Authentifizierungscodes (code) und des Suffixes eines URL-Buttons (button_url). Das Feld parameters eines Versands nimmt diese Schlüssel entgegen.

Mit einer Vorlage senden

Geben Sie die Vorlage im Objekt template des Versands an und befüllen Sie ihre Variablen über parameters. Den vollständigen Payload finden Sie unter WhatsApp-Nachrichten senden:

const msg = await bird.whatsapp.send({
  to: "+15551234567",
  template: {
    slug: "bird_otp",
    parameters: { code: "123456" },
  },
});
console.log(msg.id, msg.status);

msg = client.whatsapp.send(
    to="+15551234567",
    template="bird_otp",
    language="en",
    parameters={"code": "123456"},
)
print(msg.id, msg.status)

msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
	To:         "+15551234567",
	Template:   "bird_otp",
	Language:   "en",
	Parameters: map[string]any{"code": "123456"},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)

$message = $bird->whatsapp->send(
    to: '+15551234567',
    template: 'bird_otp',
    language: 'en',
    parameters: ['code' => '123456'],
);
echo $message->getId(), ' ', $message->getStatus();

bird whatsapp send \
  --language en \
  --parameters '{"code":"123456"}' \
  --template bird_otp \
  --to +15551234567

curl -X POST https://us1.platform.bird.com/v1/whatsapp/messages \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155550100",
    "template": {
      "slug": "bird_otp",
      "language": "en",
      "parameters": { "code": "481920" }
    }
  }'

Senden nach Kategorie

Jede Vorlage gehört zu einer der drei Kategorien von Meta. Die Kategorie bestimmt, was Sie vor einem erfolgreichen Versand erledigen müssen und was er kostet. Um eine eigene Authentifizierungsvorlage zu erstellen oder zu kopieren, benötigen Sie ein verifiziertes Unternehmen, für den Versand jedoch nicht: Die verwaltete bird_otp von Bird liegt im eigenen WhatsApp Business Account von Bird und wird ohne Ihre Verifizierung gesendet. Marketingvorlagen werden immer über einen eigenen WhatsApp Business Account gesendet, und zwar über eine zweite Meta-API, an die Bird automatisch weiterleitet. Utility-Vorlagen haben von den dreien die wenigsten Voraussetzungen.

Authentifizierungsvorlagen: Einmal-Bestätigungscodes, die Schaltfläche zum Kopieren des Codes und die Verifizierung, die zum Erstellen einer solchen Vorlage nötig ist
Utility-Vorlagen: Bestellaktualisierungen, Terminerinnerungen und Kontohinweise
Marketingvorlagen: Werbenachrichten, das erforderliche Business Account und die erwartete Abmeldemöglichkeit

Nächste Schritte

WhatsApp-Nachrichten senden: der vollständige Versand-Payload, in den das Objekt template eingefügt wird
Richtlinien für WhatsApp-Vorlagen: die Regeln, nach denen Meta eine Vorlage prüft
Authentifizierungsvorlagen: Einmal-Bestätigungscodes und die erforderliche Unternehmensverifizierung, bevor Sie eine solche Vorlage erstellen können
WhatsApp-Preise: wie Kategorie und Zielland den Preis bestimmen

Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema.

Übung ausprobieren und ein Implementierungs-Briefing erhalten

Verwandte Ressourcen