Sign inGet started

WhatsApp-Utility-Templates

Ein Utility-Template knüpft an etwas an, 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 statt dem Namen: bird_signin_alert liest sich wie ein Authentifizierungstemplate, ist aber keines; es ist Utility.

Bevor Sie senden

Wählen Sie ein verwaltetes Katalog-Template oder erstellen Sie ein eigenes auf Ihrem verknüpften Business-Account.
Zum Senden der vorgefertigten Katalog-Templates von Bird ist keine eigene Verifizierung nötig, genau wie bei Authentifizierung. Auch zum Erstellen eines eigenen Utility-Templates brauchen Sie keine: Anders als bei Authentifizierung greift Metas Business-Verifizierungspflicht bei Utility nie, Sie können Utility-Templates also in einem nicht verifizierten Workspace erstellen und bearbeiten. Unter WhatsApp-Business-Verifizierung erfahren Sie, was die Verifizierung anderswo freischaltet.
to kann eine E.164-Telefonnummer oder eine unternehmensspezifische Benutzer-ID sein. Ein Utility-Template enthält keinen OTP-Button und erfordert daher keine Telefonnummer als einzig zulässige Empfängerkennung, wie es bei Authentifizierungstemplates der Fall ist.
Jedes verwaltete Katalog-Utility-Template ist ausschließlich in en registriert, mit on_missing_language: fail. Wird eine Sprache angefordert, die der Katalog nicht führt, schlägt der Versand fehl; ein Fallback auf Englisch oder eine andere Sprache findet nicht statt.

Ein Utility-Template senden

POST /v1/whatsapp/messages mit einem template-Objekt, das einen Katalog-Slug benennt:
const msg = await bird.whatsapp.send({
  to: "+16505551234",
  template: {
    slug: "bird_order_confirmation",
    language: "en",
    components: [
      {
        type: "body",
        parameters: [
          { type: "text", name: "ref", text: "A1B2C3D4" },
          { type: "text", name: "amount", text: "USD 49.99" },
        ],
      },
    ],
  },
});
console.log(msg.id, msg.status);
Wie bei jedem verwalteten Template lassen Sie from weg: Bird wählt die Sendenummer anhand von Kategorie und Region, und ein gesetzter Wert liefert 422 E15018 WhatsAppSenderNotAllowed zurück. Ein eigenes Utility-Template zu erstellen und zu senden funktioniert genauso wie jeder andere Versand mit einem eigenen Template; unter Mit einem Template senden finden Sie den allgemeinen Vertrag.

Die Variablen ausfüllen

Utility-Parameter sind benannt, das Gegenteil des einzelnen positionalen Codes bei Authentifizierung. Jeder Parameter trägt einen name, und die Reihenfolge eines benannten Parameters im Array ist bedeutungslos. Senden Sie einen components-Eintrag für jeden Block, der tatsächlich einen Platzhalter enthält; ein Body ohne Variablen bekommt überhaupt keinen components-Eintrag.
Ein URL-Button ist die einzige Ausnahme: Seine Variable ist immer positional {{1}}, und der Versand übergibt den reinen Wert statt einer vollständigen Adresse:
Codebeispiel
{ "type": "button", "parameters": [{ "type": "text", "text": "A-4192" }] }
Die gemeinsamen Regeln zu Komponenten, sub_type, und wie die components-Werte eines Versands mit den deklarierten Platzhaltern eines Templates zusammenpassen, finden Sie unter Mit einem Template senden und Komponenten und Parameter.

Kosten

Ein Utility-Template, das innerhalb eines offenen Kundenservice-Fensters zugestellt wird, kann sich für Metas kostenfreien Tarif qualifizieren. Die Ausgangsgebühr von Bird wird während der Nachrichtenverarbeitung berechnet, noch vor der Übermittlung. Ein späterer Zustellungs- oder Lese-Callback bestimmt, ob eine Meta-Gebühr anfällt. Berücksichtigen Sie beide Komponenten bei der Kostenschätzung.
Siehe Kosten und Abrechnung für den Zeitpunkt der Berechnung und WhatsApp-Preise für die Tarife.

Worauf Sie achten sollten

  • Meta kann ein Utility-Template eigenmächtig als Marketing umkategorisieren, und die Nachricht wird weiter zum neuen, höheren Preis gesendet. Ein Unternehmen, das Meta bereits wegen falscher Kategorisierung verwarnt hat, erhält seit April 2025 keinerlei Vorankündigung mehr; die Änderung greift sofort. Halten Sie werbliche Sprache, Angebote oder Upsells aus dem Text eines Utility-Templates heraus, denn genau das löst die Umkategorisierung aus. Unter Template-Richtlinien erfahren Sie, was als werblich gilt.
  • Ein gif-Header oder ein copy_code-Button wird außerhalb von Marketing abgelehnt. Beides sind Marketing-exklusive Komponenten; wird eines davon auf einem Utility-Template deklariert, schlägt es fehl.
  • Ein Versand mit einem eigenen Template wird vor der Berechnung nicht auf die Parameteranzahl geprüft. Senden Sie die falsche Anzahl Parameter bei einem eigenen Template, wird die Nachricht akzeptiert und berechnet, dann aber von Meta abgelehnt. Verwaltete Katalog-Versendungen haben diese Lücke nicht.
  • Ein Absender auf dem falschen WhatsApp Business Account wird vor jeder Berechnung abgelehnt. from muss auf demselben Account wie das Template liegen; andernfalls schlägt der Versand fehl 422 E15023 WhatsAppSenderWABAMismatch.

Nächste Schritte