Documentatie
Sign inGet started
Aan de slag
Gidsen
API Reference
SDK's
CLI
Kennisbank
Changelog

WhatsApp-templates maken

De beheerde catalogus van Bird dekt de gangbare gevallen, maar een template in je eigen woorden moet je maken op een WhatsApp Business Account die je hebt gekoppeld. Deze pagina gaat over het maken ervan; WhatsApp-templates gaat over het bekijken en verzenden van wat er al is.
Drie dingen bepalen de hele flow:
  • Een template bevat versies, en een versie bevat één entry per taal. Wat daadwerkelijk wordt verzonden is een taal van een versie, niet de template.
  • Content wordt naar een concept geschreven. Een template heeft maximaal één open concept, en niets erin bereikt WhatsApp totdat je het indient.
  • Goedkeuring komt per taal terug. De ene taal kan worden goedgekeurd terwijl een andere op dezelfde versie wordt afgewezen.

Voordat je begint

Je hebt een gekoppeld eigen nummer nodig; dat geeft je werkruimte een WhatsApp Business Account om op te werken. Een account dat je niet hebt gekoppeld wordt geweigerd, en dat geldt ook voor het bewerken van een van de ingebouwde bird_-templates van Bird: die staan op het eigen account van Bird, dus dupliceer er een naar het jouwe.
Een authentication-template maken vereist daarnaast een geverifieerd bedrijf; utility en marketing niet. Zie Authentication templates voor die vereiste.
Maak een template in het dashboard onder WhatsApp > Templates, met de bird CLI, of via de MCP-server. Het dashboard doorloopt dezelfde stappen die deze pagina beschrijft; de voorbeelden verderop gebruiken de CLI.

In het dashboard

New template biedt twee manieren. Start with a template opent de galerij, de snelste route: kies er een die al bijna zegt wat je nodig hebt, ook een van Bird, en de kopie komt op je account als een open concept.
De templategalerij in het Bird-dashboard: een raster van templatekaarten, elk met een voorbeeld van het bericht en voorzien van naam, slug, status, categorie en talen, naast filters voor templatebron, categorie en taal
Start from scratch vraagt om de categorie, een naam en een standaardtaal voordat de editor opent. Een marketingtemplate kiest ook een berichttype. De naam wordt de slug, en de slug en de categorie zijn de twee keuzes die je later niet meer kunt wijzigen.
De stap Maak een nieuwe template in het Bird-dashboard: tegels voor de categorieën Marketing, Utility en Authentication boven een naamveld en een selector voor de standaardtaal, met een knop Maak template
De editor schrijft één taal tegelijk: de zijbalk toont de talen van de template met de beoordelingsstatus van elke taal, de middelste kolom bevat de content en de telefoonpreview rendert het bericht met ingevulde voorbeeldwaarden.
De template-editor in het Bird-dashboard voor de utility-template Order update: Engels gemarkeerd als Approved naast Nederlands in de taalsidebar, en een telefoonpreview van het gerenderde bericht met de knoppen Track order en Contact support
De editor past zich aan de template aan. Een carousel voegt een tab per kaart toe naast het bericht, en elke kaart moet de structuur van kaart 1 herhalen: hetzelfde headerformaat en dezelfde knoppen in dezelfde volgorde.
De template-editor in het Bird-dashboard voor een carousel-marketingtemplate: tabs Message, Card 1, Card 2 en Card 3 boven de berichttekst, met een sectie Variable samples eronder, naast een telefoonpreview met het bericht gevolgd door veegbare afbeeldingskaarten elk met een Show me-knop
Een authentication-template heeft geen berichteditor. WhatsApp schrijft de tekst, dus de editor biedt alleen de twee instellingen waaruit het schrijft: Add security recommendation en Code expiration (minutes).
De template-editor in het Bird-dashboard voor een authentication-template: een paneel Authentication settings met een schakelaar Add security recommendation en een veld Code expiration (minutes), naast een telefoonpreview van het verificatiecodebericht dat WhatsApp schrijft, met de knop Copy code
Save as draft bewaart je werk zonder WhatsApp te contacteren. Submit for review bevriest de versie en stuurt deze naar WhatsApp. De submit van de CLI hieronder voert dezelfde bevriezing uit.

Twee manieren om te beginnen

Een bestaande template dupliceren

Een duplicaat draagt de content van de bron als een open concept en roept WhatsApp nul keer aan, dus er wordt niets ingediend totdat je dat kiest. Twee dingen over een kopie zijn goed om te weten voordat je er een maakt:
  • De categorie wordt overgenomen en kan niet worden gewijzigd. Als je een andere categorie nodig hebt, begin dan helemaal opnieuw.
  • Je kunt de talen beperken, nooit uitbreiden. Een catalogustemplate met 70 talen hoeft niet 70 talen van jou te worden: kies de subset die je daadwerkelijk gaat onderhouden. Een taal opvragen die de bron niet heeft wordt geweigerd met E15060, en het antwoord vermeldt welke niet overeenkwamen. Voeg extra talen achteraf toe aan de kopie.
De taalsubset is een array, dus die gaat in een request body in plaats van een vlag:
Codevoorbeeld
bird whatsapp templates duplicate bird_order_confirmation --body-file copy.json
Codevoorbeeld
{
  "waba": "102290129340398",
  "slug": "acme_order_update",
  "include_languages": ["en", "es-ES"],
  "default_language": "en"
}
Laat include_languages weg en de kopie neemt alle talen van de bron over. Laat default_language weg en de kopie behoudt de standaardtaal van de bron als je subset die nog bevat; anders neemt het de eerste taal van de kopie op canonieke tag, wat niet per se de eerste is die je opgaf, dus stel het expliciet in als het ertoe doet.

Helemaal opnieuw beginnen

Een template maken vereist een slug, een account, een categorie en een standaardtaal:
Codevoorbeeld
bird whatsapp templates create order_update \
  --waba 102290129340398 \
  --category utility \
  --default-language en
De slug en de categorie zijn beide permanent. WhatsApp leidt zijn eigen templatenaam af van de slug, en noch die naam noch de categorie kan later worden gewijzigd; een andere betekent een nieuwe template. Het bird_-prefix is gereserveerd voor de catalogus van Bird. De categorie die je kiest is niet per se waar een verzending op wordt geprijsd: Meta past zijn eigen categorie per taal toe en kan die verplaatsen, en de prijs volgt die van Meta.

Elke taal schrijven

Open het concept en schrijf dan één taal tegelijk:
Codevoorbeeld
bird whatsapp templates versions create order_update
bird whatsapp templates versions languages set order_update <version-id> en --body-file en.json
Een concept openen kan je veilig herhalen: een template heeft er maar één, dus dit geeft het open concept terug in plaats van een tweede te maken. De template meldt het ook als draft_version_id.
Bij het opslaan van een taalversie wordt deze volledig vervangen, niet samengevoegd met de bestaande versie. Het bestand draagt elke keer de volledige components van die taal, dus lees de taal eerst en schrijf hem in zijn geheel terug; alleen het blok sturen dat je hebt gewijzigd verwijdert de rest.
Elke variabele heeft een voorbeeldwaarde nodig. WhatsApp beoordeelt het ingevulde bericht in plaats van de template, dus een blok met placeholders en geen voorbeeldparameters wordt bij het indienen geweigerd, niet bij het schrijven.

Controleren en dan indienen

Valideer voordat je iets bevriest. Een alleen-valideren-submit voert elke controle uit over alle talen en rapporteert elk probleem in één keer, zonder iets naar WhatsApp te sturen:
Codevoorbeeld
bird whatsapp templates versions submit order_update <version-id> --validate-only
Lees valid en errors; elke fout vermeldt de taal, het veld en de code waarmee een echte submit zou falen. Dien dan echt in door de vlag weg te laten. Dat bevriest het concept als een onveranderlijke versie en antwoordt 202. Gebruik een andere idempotency key voor de controle en de submit, want het hergebruiken van een key met een gewijzigde body wordt afgewezen.
Alleen talen waarvan de content afwijkt van hun goedgekeurde kopie gaan naar WhatsApp. Een taal die al overeenkomt, draagt de goedkeuring over, dus een submit waar niets is gewijzigd wordt direct afgehandeld zonder iets te hoeven pollen. Er opent daarna geen vervangend concept: de volgende bewerkingsronde begint met het opnieuw maken van een concept.
Een schone alleen-valideren-run voorspelt de beslissing van WhatsApp niet. WhatsApp biedt geen manier om het vooraf te vragen, dus het kan nog steeds content weigeren die elke lokale controle doorstond.

De beoordeling volgen

Goedkeuring komt later en per taal. De pending_version_id van de template blijft ingesteld zolang er een taal onopgelost is, en de lijst per taal draagt elk oordeel:
  • approved kan worden verzonden. available_languages op de template bevat precies de talen die een verzending op dit moment kan gebruiken.
  • rejected, submit_failed, paused vereisen een bewerking op een nieuw concept. WhatsApp accepteert een bewerking aan een gepauzeerde taal, en opnieuw indienen is wat het opheft.
  • disabled, limit_exceeded, in_appeal weigeren een bewerking volledig; ze hoeven alleen opnieuw gelezen te worden totdat WhatsApp hun status wijzigt.
De eigen status van de template is een aggregaat: active betekent dat minstens één taal verzendbaar is, niet alle.

Verzenden wat je hebt gemaakt

Een zelfgemaakte template verzendt via hetzelfde endpoint als elke andere, met één verschil ten opzichte van de catalogus van Bird: je moet from opgeven, en dat moet een nummer zijn op hetzelfde WhatsApp Business Account als de template. Een afzender op een ander account wordt geweigerd 422 E15023 voordat er iets in rekening wordt gebracht.
Een template kan de taal van de ontvanger vereisen via language_source_required. Anders bepaalt on_missing_language of de taalselectie mislukt of een goedgekeurde basistaal of default_language kan gebruiken. Test het geconfigureerde beleid tegen de goedgekeurde available_languages van de template; een niet-goedgekeurde standaardtaal is niet verzendbaar. De waarden die je opgeeft moeten de placeholders vullen van de taalversie die daadwerkelijk wordt geselecteerd, dus lees de content van die taal voordat je verzendt. Zie WhatsApp-berichten verzenden voor de volledige payload.

Aandachtspunten

  • De nieuwste versie is niet de versie die verzendt. Een versielijst is nieuwste-eerst en bevat elk open concept, dus de bovenste rij is vaak een concept of een versie die nog in beoordeling is. De template noemt de versie in dienst als live_version_id; een template zonder live versie kan helemaal niet worden verzonden.
  • Een taal in beoordeling weigert een schrijfactie. WhatsApp houdt de taal vast totdat de beoordeling klaar is, dus een bewerking tijdens pending faalt in plaats van in de wachtrij te gaan.
  • Een lijstrij bevat geen content. Templates opvragen vindt ze en toont de levenscyclusstatus; lezen wat er daadwerkelijk staat vereist een versielezing.
  • Verwijderen is onomkeerbaar. Het weggooien van een taal, het verwijderen van een concept en het verwijderen van een template vereisen allemaal een expliciete bevestiging, en het verwijderen van een template stopt elke verzending op die slug.

Volgende stappen

Gerelateerde bronnen

Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.

Begrijp het conceptWhat is a WhatsApp message template?Ontdek de mogelijkheidWhatsApp templatesVolg het leerpadBuild your first integration
Probeer de oefening en ontvang een implementatieoverzicht