Sign inGet started

WhatsApp utility-templates

Een utility-template haakt aan op iets wat de ontvanger al heeft gedaan: een bestelling, een betaling, een boeking, een aanmelding. De catalogus van Bird bevat er acht, waaronder bird_signin_alert en bird_delivery_update. Bepaal de categorie van een slug aan de hand van de templatelijst, niet de naam: bird_signin_alert lijkt op een authentication-template maar is het niet, het is utility.

Voordat je verstuurt

Kies een beheerd catalogustemplate of maak er zelf een aan op je gekoppelde zakelijke account.
Voor het versturen van de standaard catalogustemplates van Bird is geen verificatie van jouw kant nodig, net als bij authentication. Voor het maken van een eigen utility-template ook niet: anders dan bij authentication is Meta's bedrijfsverificatiepoort nooit van toepassing op utility, dus je kunt utility-templates aanmaken en bewerken op een niet-geverifieerde werkruimte. Zie WhatsApp bedrijfsverificatie voor wat verificatie elders ontsluit.
to kan een E.164-telefoonnummer of een business-scoped user ID zijn. Een utility-template bevat geen OTP-knop en vereist dus niet de ontvanger met alleen een telefoonnummer die authentication wel vereist.
Elke beheerde catalogus-utility-template is alleen geregistreerd in en, met on_missing_language: fail. Een taal opvragen die de catalogus niet heeft, laat de verzending mislukken in plaats van terug te vallen op Engels of iets anders.

Een utility-template versturen

POST /v1/whatsapp/messages met een template-object dat een catalogusslug benoemt:
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);
Laat bij elke beheerde template from weg: Bird kiest het verzendnummer op basis van de categorie en regio, en het instellen ervan retourneert 422 E15018 WhatsAppSenderNotAllowed. Een eigen utility-template maken en versturen werkt hetzelfde als elke andere verzending met een eigen template; zie Versturen met een template voor het algemene contract.

De variabelen invullen

Utility-parameters zijn benoemd, het omgekeerde van authentication's enkele positionele code. Elke parameter heeft een name, en de volgorde van een benoemde parameter in de array heeft geen betekenis. Stuur één components-entry voor elk blok dat daadwerkelijk een placeholder bevat; een body zonder variabelen krijgt helemaal geen components-entry.
Een URL-knop is de enige uitzondering: de variabele is altijd positioneel {{1}}, en de verzending bevat de kale waarde in plaats van een volledig adres:
Codevoorbeeld
{ "type": "button", "parameters": [{ "type": "text", "text": "A-4192" }] }
Zie Versturen met een template en Components en parameters voor de gedeelde regels over componenten, sub_type, en hoe de components van een verzending overeenkomen met de gedeclareerde placeholders van een template.

Kosten

Een utility-template dat wordt afgeleverd binnen een open klantenservicevenster kan in aanmerking komen voor Meta's gratis tarief. De uitgaande kosten van Bird worden in rekening gebracht tijdens de berichtverwerking, vóór verzending. Een latere afleverings- of leesbevestiging bepaalt of er Meta-kosten van toepassing zijn. Houd rekening met beide componenten bij het inschatten van het totaal.
Zie Kosten en facturering voor wanneer een verzending in rekening wordt gebracht, en WhatsApp-tarieven voor de prijzen.

Aandachtspunten

  • Meta kan een utility-template op eigen initiatief hercategoriseren als marketing, en het bericht blijft verstuurd worden tegen de nieuwe, hogere prijs. Een bedrijf dat al door Meta is gewaarschuwd voor verkeerde categorisering krijgt sinds april 2025 helemaal geen voorafgaande melding meer; de wijziging gaat direct in. Houd promotionele taal, aanbiedingen of upsells uit de tekst van een utility-template, want dat is wat de verschuiving veroorzaakt. Zie Templaterichtlijnen voor wat als promotioneel wordt beschouwd.
  • Een gif-header of een copy_code-knop wordt geweigerd buiten marketing. Beide zijn marketing-only componenten; een van beide declareren op een utility-template mislukt.
  • Een verzending met een eigen template wordt niet gecontroleerd op het aantal parameters voordat er kosten in rekening worden gebracht. Stuur het verkeerde aantal parameters bij een eigen template en het bericht wordt geaccepteerd en in rekening gebracht, en daarna afgewezen door Meta. Beheerde catalogusverzendingen hebben dit probleem niet.
  • Een afzender op het verkeerde WhatsApp Business Account wordt geweigerd vóór enige kosten. from moet op hetzelfde account staan als de template; anders mislukt de verzending 422 E15023 WhatsAppSenderWABAMismatch.

Volgende stappen