WhatsApp-Authentifizierungsvorlagen

Eine Authentifizierungsvorlage stellt einen einmaligen Bestätigungscode zu. Den Wortlaut gibt Meta vor, wenn Sie die Vorlage erstellen. Beim Senden übergeben Sie den Code als Body-Parameter.

Vor dem Senden

Entscheiden Sie, ob Sie eine von Bird verwaltete Vorlage verwenden oder eine Vorlage in Ihrem eigenen Unternehmenskonto erstellen.

Für das Senden der vorrätigen Katalogvorlagen von Bird, bird_otp und bird_otp_authifly, benötigen Sie keine eigene Verifizierung. Diese Vorlagen liegen in den eigenen WhatsApp Business Accounts von Bird, und der verwaltete Sendeweg prüft den Verifizierungsstatus Ihres Unternehmens nie.

Meldet das verbundene Unternehmenskonto not_verified, lehnt Bird das Erstellen oder Duplizieren von Authentifizierungsvorlagen mit 412 E15043 WhatsAppTemplateBusinessNotVerified ab. Prüfen Sie das verbundene Konto und seinen zuletzt synchronisierten Status. Den Ablauf der Verifizierung und den Umgang mit dem Status beschreibt WhatsApp-Unternehmensverifizierung.

Das Erstellen von Utility- und Marketingvorlagen ist von dieser Voraussetzung nicht betroffen. Sie können diese Vorlagen unabhängig von Ihrem Verifizierungsstatus weiter erstellen und bearbeiten.

Erstellen Sie Vorlagen im Dashboard, mit der bird CLI oder über den MCP-Server. Den vollständigen Ablauf beschreibt Authentifizierungsvorlagen erstellen.

Einen Bestätigungscode senden

POST /v1/whatsapp/messages mit einem template-Objekt, das einen Katalog-Slug angibt:

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

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

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	bird "github.com/messagebird/bird-sdk-go"
	"github.com/messagebird/bird-sdk-go/option"
)

func main() {
	client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
	if err != nil {
		log.Fatal(err)
	}
	msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
		To:         "+14155550100",
		Template:   "bird_otp",
		Language:   "en",
		Parameters: map[string]any{"code": "481920"},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Status)
}

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

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

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

Für diese Kategorie gelten vier besondere Regeln:

Lassen Sie from weg. Eine von Bird verwaltete Vorlage wählt ihren Absender selbst anhand von Kategorie und Region. Wenn Sie from setzen, erhalten Sie daher 422 E15018 WhatsAppSenderNotAllowed. Ein Freiform-Versand verlangt dagegen from. Das ist wichtig, wenn Sie von den Seiten zu interaktiven Nachrichten kommen.
to muss eine Telefonnummer im Format E.164 sein. Eine Authentifizierungsvorlage kann nicht an eine unternehmensbezogene Benutzer-ID gehen. In diesem Fall erhalten Sie 422 E15014 WhatsAppRecipientNotSupportedForTemplate.
Der Code gehört in parameters.code. Er füllt den Platzhalter im Textkörper und die Schaltfläche zum Kopieren des Codes. Ein Versand mit components erwartet stattdessen genau einen positionellen Textkörper-Parameter, nämlich den Code. Ohne Parameter oder mit einem benannten Parameter erhalten Sie 422 E15003 WhatsAppTemplateParameterMismatch.
Sie benötigen kein Kundenservice-Fenster. Der Versand von Vorlagen ist nicht an das Fenster gebunden. Genau deshalb gibt es Vorlagen für Bestätigungscodes: Sie müssen auch Personen erreichen, die Ihnen noch nie geschrieben haben.

Die verfügbaren Sprachen für bird_otp oder bird_otp_authifly finden Sie im Vorlagenkatalog. Ist die angeforderte Sprache nicht verfügbar, schlägt der Versand fehl, statt eine andere Sprache zu verwenden.

Die Schaltfläche zum Kopieren des Codes

Meta schreibt den Textkörper einer Authentifizierungsvorlage selbst, als Vorgabe mit einem einzigen Platzhalter für den Code. Sie liefern daher Optionen statt Text. Bei einem Versand mit parameters wird die Schaltfläche aus code gefüllt. Bei einem Versand mit components ist die Schaltflächenkomponente optional: Wenn Sie keine angeben, fügt Bird sie mit demselben Code wie im Textkörper hinzu. Sie können sie auch selbst angeben:

Codebeispiel

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

In beiden Fällen erreicht genau eine Schaltfläche WhatsApp, nämlich die Schaltfläche zum Kopieren des Codes: Ein Tippen darauf kopiert den Code in die Zwischenablage. Bird unterstützt nur copy_code. Die beiden anderen Schaltflächenverhalten, die Meta für Authentifizierungsvorlagen dokumentiert, das automatische Ausfüllen per Tippen und ohne Tippen, sind auf Bird nicht verfügbar.

Die Schaltfläche einer Vorlage erstellen Sie nach demselben Muster: eine Schaltfläche vom Typ otp, und die Vorlage akzeptiert keinen anderen Schaltflächentyp. Statt Text zu schreiben, geben Sie add_security_recommendation (ein boolescher Wert, im Textkörper angezeigt) und code_expiration_minutes (1 bis 90, in der Fußzeile angezeigt) an.

Was Meta in einer Authentifizierungsvorlage erlaubt

Meta legt die Struktur einer Authentifizierungsvorlage fest und prüft ihren Inhalt: Die Vorlage darf nirgends URLs, Medien oder Emojis enthalten, und der Code-Parameter ist auf 15 Zeichen begrenzt. Die Kategorie ändert auch, wie WhatsApp die Nachricht zustellt: Sie geht nur an das Hauptgerät des Empfängers. Die feste Struktur, die Zeichenlimits und den Prüfprozess finden Sie vollständig unter Template guidelines.

Kosten

Kategorie und Zielland bestimmen den Preis. Unter WhatsApp authentication-international rates erfahren Sie, wie sich der Preis ändern kann, wenn Sie in ein anderes Land als Ihren primären Standort senden, und unter Kosten und Abrechnung, wann ein Versand berechnet wird. Die konkreten Tarife finden Sie unter WhatsApp-Preise.

Worauf Sie achten sollten

Die vorrätigen Templates von Bird werden in neun Ländern nicht zugestellt. bird_otp und bird_otp_authifly werden von den eigenen WhatsApp Business Accounts von Bird gesendet, und diese Konten stellen keine Authentifizierungsnachrichten nach Ägypten, Indien, Indonesien, Malaysia, Nigeria, Pakistan, Saudi-Arabien, Südafrika oder in die Vereinigten Arabischen Emirate zu. Ein solcher Versand wird mit 422 E15063 WhatsAppDestinationRestricted abgelehnt, bevor Kosten anfallen. Ein Template, das Sie in Ihrem eigenen Konto erstellt haben und von Ihrer eigenen Nummer senden, erreicht diese Länder normal. Auch Verify erreicht sie, indem es den Bestätigungscode selbstständig über einen anderen Kanal sendet.
Ein Versand eines selbst erstellten Templates erfordert from, und der Absender muss zum selben WhatsApp Business Account gehören wie das Template. Ein Absender aus einem anderen Konto wird mit 422 E15023 WhatsAppSenderWABAMismatch abgelehnt, bevor Kosten anfallen.
Sie können nur eine Sprache senden, deren Version genehmigt und aktiv ist. Eine Sprache im Entwurf, in Prüfung, abgelehnt oder pausiert lässt sich nicht senden.
Meta kann ein Template von sich aus neu kategorisieren. Sie können dem nicht widersprechen, und dabei ändern sich die Preis- und Zustellregeln, die von der Kategorie abhängen.
Die Kategorie des Templates und die Kategorie seiner Sprache können voneinander abweichen. Unter WhatsApp-Templates erfahren Sie, wie der Versand das auflöst.
Ein importiertes Authentifizierungs-Template lässt sich nicht duplizieren. Bird kann den von WhatsApp generierten Text nicht in die Einstellungen zurücklesen, aus denen ein neues Template erstellt wird; das ergibt 422 E15024 WhatsAppTemplateContentNotDuplicable. Erstellen Sie stattdessen ein neues Template mit eigener Sicherheitsempfehlung und eigener Code-Ablaufzeit.

Nächste Schritte

WhatsApp-Templates: den Katalog durchsuchen und der gemeinsame Vertrag für den Versand per Template
Utility-Templates: Bestellaktualisierungen, Terminerinnerungen und Kontohinweise
WhatsApp-Unternehmensverifizierung: Wie die Verifizierung funktioniert und was sie sonst noch freischaltet

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

Übung ausprobieren und ein Implementierungs-Briefing erhalten

Verwandte Ressourcen