WhatsApp-Utility-Templates

Ein Utility-Template bezieht sich auf etwas, das der Empfänger bereits getan hat: eine Bestellung, eine Zahlung, eine Buchung, eine Anmeldung. Der Katalog von Bird enthält acht davon, darunter bird_signin_alert und bird_delivery_update. Entnehmen Sie die Kategorie eines Slugs der Template-Liste, nicht seinem Namen: bird_signin_alert klingt nach einem Authentifizierungs-Template, ist aber ein Utility-Template.

Vor dem Senden

Wählen Sie ein verwaltetes Katalog-Template oder erstellen Sie ein Utility-Template in Ihrem verbundenen Geschäftskonto.

Für das Senden der Katalog-Templates von Bird benötigen Sie keine eigene Verifizierung, genau wie bei der Authentifizierung. Auch für das Erstellen eines eigenen Utility-Templates ist keine nötig: Anders als bei der Authentifizierung gilt Metas Unternehmensverifizierung für Utility nie, sodass Sie Utility-Templates auch in einem nicht verifizierten Workspace erstellen und bearbeiten können. Was die Verifizierung an anderer Stelle freischaltet, finden Sie unter WhatsApp-Unternehmensverifizierung.

to kann eine E.164-Telefonnummer oder eine unternehmensbezogene Benutzer-ID sein. Ein Utility-Template enthält keine OTP-Schaltfläche und erfordert deshalb nicht wie die Authentifizierung einen Empfänger mit Telefonnummer.

Jedes verwaltete Utility-Template im Katalog ist nur in en registriert, mit on_missing_language: fail. Wenn Sie eine Sprache anfordern, die der Katalog nicht enthält, schlägt das Senden fehl, statt auf Englisch oder eine andere Sprache auszuweichen.

Ein Utility-Template senden

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

const msg = await bird.whatsapp.send({
  to: "+16505551234",
  template: {
    slug: "bird_order_confirmation",
    language: "en",
    parameters: { ref: "A1B2C3D4", amount: "USD 49.99" },
  },
});
console.log(msg.id, msg.status);

msg = client.whatsapp.send(
    to="+16505551234",
    template="bird_order_confirmation",
    language="en",
    parameters={"ref": "A1B2C3D4", "amount": "USD 49.99"},
)
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:         "+16505551234",
		Template:   "bird_order_confirmation",
		Language:   "en",
		Parameters: map[string]any{"ref": "A1B2C3D4", "amount": "USD 49.99"},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Status)
}

$message = $bird->whatsapp->send(
    to: '+16505551234',
    template: 'bird_order_confirmation',
    language: 'en',
    parameters: ['ref' => 'A1B2C3D4', 'amount' => 'USD 49.99'],
);
echo $message->getId(), ' ', $message->getStatus();

bird whatsapp send \
  --language en \
  --parameters '{"amount":"USD 49.99","ref":"A1B2C3D4"}' \
  --template bird_order_confirmation \
  --to +16505551234

curl -X POST "https://us1.platform.bird.com/v1/whatsapp/messages" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "to": "+16505551234",
      "template": {
        "slug": "bird_order_confirmation",
        "language": "en",
        "parameters": {
          "ref": "A1B2C3D4",
          "amount": "USD 49.99"
        }
      }
    }'

Lassen Sie wie bei jedem verwalteten Template from weg: Bird wählt die Absendernummer anhand von Kategorie und Region, und wenn Sie den Wert setzen, erhalten Sie 422 E15018 WhatsAppSenderNotAllowed. Ein eigenes Utility-Template erstellen und senden Sie wie jedes andere selbst erstellte Template; den allgemeinen Ablauf beschreibt Senden mit einem Template.

Variablen befüllen

Utility-Variablen sind benannt, daher ist jede ein eigener Schlüssel in parameters, etwa ref und amount. Ein URL-Button mit einem nummerierten {{1}}-Suffix verwendet stattdessen den Schlüssel button_url. Ein benanntes Suffix verwendet seinen eigenen Namen. Der Versand enthält nur den reinen Wert, keine vollständige Adresse:

{ "parameters": { "ref": "A1B2C3D4", "button_url": "A-4192" } }

Ein components-Versand benennt stattdessen jeden Body-Parameter, und die Reihenfolge eines benannten Parameters im Array hat keine Bedeutung. Die gemeinsamen Regeln zu Komponenten, zu sub_type und dazu, wie die components eines Versands den deklarierten Platzhaltern eines Templates zugeordnet werden, finden Sie unter Sending with a template und Components and parameters.

Kosten

Für ein Utility-Template, das innerhalb eines offenen Kundenservice-Fensters zugestellt wird, gilt bis zum 30. September 2026 der kostenlose Tarif von Meta. Ab dem 1. Oktober 2026 berechnet Meta dafür Gebühren wie für jedes andere Utility-Template (Preisänderungen im Oktober 2026). Die ausgehende Gebühr von Bird wird während der Nachrichtenverarbeitung berechnet, also vor der Übermittlung. Ob eine Meta-Gebühr anfällt, entscheidet ein späterer Delivered- oder Read-Callback. Berücksichtigen Sie beide Bestandteile, wenn Sie die Gesamtkosten schätzen.

Wann ein Versand berechnet wird, erfahren Sie unter Kosten und Abrechnung, die Tarife unter WhatsApp-Preise.

Worauf Sie achten sollten

• Meta kann ein Utility-Template eigenständig als Marketing umkategorisieren, und die Nachricht wird weiter zum neuen, höheren Preis versendet. Ein Unternehmen, das Meta bereits wegen falscher Kategorisierung verwarnt hat, erhält seit April 2025 keinerlei Vorankündigung mehr; die Änderung greift sofort. Verzichten Sie im Text eines Utility-Templates auf werbliche Sprache, Angebote oder Upselling, denn genau das löst die Umstufung aus. Was als werblich gilt, finden Sie unter Template-Richtlinien.
• Ein gif-Header oder ein copy_code-Button wird außerhalb von Marketing abgelehnt. Beide sind reine Marketing-Komponenten; wenn Sie eine davon in einem Utility-Template deklarieren, schlägt dies fehl.
• Bei einem selbst erstellten Template wird ein components-Versand nicht auf die Parameteranzahl geprüft, bevor er berechnet wird. Senden Sie bei einem eigenen Template die falsche Anzahl an Parametern in components, wird die Nachricht angenommen und berechnet und anschließend von Meta abgelehnt. Ein parameters-Versand, dem ein erforderlicher Schlüssel fehlt, wird abgelehnt, bevor Kosten entstehen. Bei Versänden mit verwalteten Katalog-Templates besteht diese Lücke nicht.
• Ein Absender im falschen WhatsApp Business Account wird abgelehnt, bevor Kosten entstehen. from muss sich im selben Account wie das Template befinden; andernfalls schlägt der Versand 422 E15023 WhatsAppSenderWABAMismatch fehl.

Nächste Schritte

• WhatsApp-Vorlagen: den Katalog durchsuchen und der gemeinsame Vertrag für das Senden mit Vorlagen
• Authentifizierungsvorlagen: Einmal-Bestätigungscodes und die Verifizierungspflicht beim Erstellen einer solchen Vorlage
• Marketingvorlagen: Werbesendungen und das Konto, das Sie zum Erstellen einer solchen Vorlage benötigen