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);msg = client.whatsapp.send(
to="+16505551234",
template="bird_order_confirmation",
language="en",
components=[
{
"type": "body",
"parameters": [
{"type": "text", "name": "ref", "text": "A1B2C3D4"},
{"type": "text", "name": "amount", "text": "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)
}
ref := "A1B2C3D4"
amount := "USD 49.99"
refName := "ref"
amountName := "amount"
components := []bird.WhatsAppMessageTemplateComponent{{
Type: "body",
Parameters: &[]bird.WhatsAppMessageTemplateComponentParameter{
{Type: "text", Name: &refName, Text: &ref},
{Type: "text", Name: &amountName, Text: &amount},
},
}}
msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
To: "+16505551234",
Template: "bird_order_confirmation",
Language: "en",
Components: components,
})
if err != nil {
log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)
}$components = [
(new WhatsAppMessageTemplateComponent())
->setType('body')
->setParameters([
(new WhatsAppMessageTemplateComponentParameter())->setType('text')->setName('ref')->setText('A1B2C3D4'),
(new WhatsAppMessageTemplateComponentParameter())->setType('text')->setName('amount')->setText('USD 49.99'),
]),
];
$message = $bird->whatsapp->send(
to: '+16505551234',
template: 'bird_order_confirmation',
language: 'en',
components: $components,
);
echo $message->getId(), ' ', $message->getStatus();bird whatsapp send \
--components '[{"parameters":[{"name":"ref","text":"A1B2C3D4","type":"text"},{"name":"amount","text":"USD 49.99","type":"text"}],"type":"body"}]' \
--language en \
--template bird_order_confirmation \
--to +16505551234{
"name": "whatsapp_send",
"arguments": {
"template": {
"components": [
{
"parameters": [
{
"name": "ref",
"text": "A1B2C3D4",
"type": "text"
},
{
"name": "amount",
"text": "USD 49.99",
"type": "text"
}
],
"type": "body"
}
],
"language": "en",
"slug": "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",
"components": [
{
"type": "body",
"parameters": [
{
"type": "text",
"name": "ref",
"text": "A1B2C3D4"
},
{
"type": "text",
"name": "amount",
"text": "USD 49.99"
}
]
}
]
}
}'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
- WhatsApp-Templates: Den Katalog durchsuchen und der gemeinsame Vertrag für den Template-Versand
- Authentifizierungstemplates: Einmal-Bestätigungscodes und die Verifizierungspflicht beim Erstellen
- Marketing-Templates: Werbliche Versendungen und der Account, den Sie zum Erstellen benötigen
Verwandte Ressourcen
Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema. Die Ressourcen sind auf Englisch.
Anleitung ansehenConnecting WhatsApp to Bird: from buying a number to a live channelDas Konzept verstehenWhat is the 24-hour customer service window on WhatsApp?Das Tool verwendenWhatsApp message builderDie Funktion erkundenWhatsApp
Übung ausprobieren und ein Implementierungs-Briefing erhalten