WhatsApp-templates

Berichten die een bedrijf zelf via WhatsApp begint, gebruiken een vooraf goedgekeurde template. Een template bevat vaste tekst en variabelen, zodat je bij het versturen alleen waarden meegeeft, zoals een OTP-code of een ordernummer.

Bird levert een beheerde catalogus, registreert de inhoud daarvan bij WhatsApp en verstuurt die templates vanaf de eigen nummers van Bird. De slugs ervan beginnen met bird_. Een werkruimte die een eigen nummer heeft gekoppeld, kan ook templates maken op een eigen WhatsApp Business Account. De pagina Approved templates toont elke template die de werkruimte kan versturen en hoe elke template wordt weergegeven.

Templates bekijken in het dashboard

Open Approved templates via WhatsApp > Approved templates. Your templates bevat de templates die deze werkruimte heeft gemaakt. All templates voegt daar de door Bird beheerde catalogus aan toe. Zoek op naam of filter op status en categorie. Met de schakelaar naast de filters wissel je tussen de kaartweergave en de lijstweergave.

In de lijstweergave toont elke rij de velden die je nodig hebt om een template te kiezen en te versturen:

Status: of de template als geheel verstuurd kan worden. Templates uit de beheerde catalogus melden active. Een eigen template meldt hoe het met de eigen goedkeuring staat. Controleer in de lijst met talen of de taal die je nodig hebt beschikbaar is.
Name: het weergavelabel, met daaronder de slug van de template. Gebruik bij het versturen de slug.
Languages: de talen waarin de template is geregistreerd, zoals Engels en Nederlands.
Category: authentication, utility of marketing. De categorie bepaalt hoe WhatsApp het bericht behandelt, vanaf welk Bird-nummer een beheerde template wordt verzonden en, samen met het land van bestemming, de prijs.
WABA: Bird-managed voor catalogustemplates. Bij een eigen template staat hier het WhatsApp Business Account waarin de template staat. Zo'n template wordt alleen verzonden vanaf een nummer op datzelfde account.
Updated: wanneer de template voor het laatst is gewijzigd.

Klik op een rij om de details van de template te openen.

Wat een template bevat

De detailweergave toont de berichttekst, variabelen en knoppen in een voorbeeld in de stijl van WhatsApp.

De detailweergave bevat ook een cURL-voorbeeld voor POST /v1/whatsapp/messages, met de regionale host en de voorbeeldwaarden van de template. Vervang de API-sleutel, de ontvanger en de variabelewaarden voordat je verzendt.

Met het voorbeeld zie je het snelst welke vorm een verzending moet hebben. Via de API komt dezelfde inhoud uit de versie van de template (De inhoud van een template lezen).

Templates ophalen via de API

GET /v1/whatsapp/templates geeft een catalogus terug met cursorpaginering. Voor het verzoek heb je leesrechten voor whatsapp_management nodig. Gebruik HTTP of een methode voor ruwe verzoeken van SDK.

type Templates = { data: Array<{ slug: string; status: string }> };

const templates = await bird.request<Templates>({
  method: "GET",
  path: "/v1/whatsapp/templates",
});

templates = client.get("/v1/whatsapp/templates")

var out struct {
	Data []struct {
		Slug   string `json:"slug"`
		Status string `json:"status"`
	} `json:"data"`
}
if err := client.Get(context.Background(), "/v1/whatsapp/templates", &out); err != nil {
	log.Fatal(err)
}

$templates = $bird->get('/v1/whatsapp/templates');

curl https://us1.platform.bird.com/v1/whatsapp/templates \
  -H "Authorization: Bearer $BIRD_API_KEY"

Elk item noemt de template, de categorie en de beschikbare talen. Lees de live versie apart uit voor de inhoud van het bericht.

Codevoorbeeld

{
  "available_languages": ["en", "es", "pt-BR", "..."],
  "category": "authentication",
  "default_language": "en",
  "description": "One-time passcode",
  "id": "wat_01ky4x8e4genzb7way45txfkm1",
  "languages": {
    "en": { "status": "approved" },
    "es": { "status": "approved" },
    "pt-BR": { "status": "approved" },
    "...": "..."
  },
  "name": "bird_otp",
  "on_missing_language": "fail",
  "scope": "system",
  "slug": "bird_otp",
  "status": "active"
}

In het voorbeeldantwoord zijn de taallijsten van bird_otp ingekort.

De velden waarvan een verzending afhangt:

slug: de handle die je in een verzending gebruikt. Slugs van beheerde templates beginnen met bird_, een prefix dat voor hen is gereserveerd.
waba: het WhatsApp Business Account dat de talen van de template bij Meta beheert, en het account waartoe een afzendernummer moet behoren. Ontbreekt bij een beheerde template, omdat Bird het account ervan beheert.
available_languages: talen die je kunt verzenden. Een gepauzeerde, uitgeschakelde, gearchiveerde of beperkte taal verdwijnt uit deze lijst.
on_missing_language: wat er gebeurt als de gevraagde taal niet beschikbaar is. Door Bird beheerde WhatsApp-templates gebruiken fail, waarmee de verzending wordt geweigerd in plaats van dat een andere taal wordt gebruikt.

Status en taalstatus

Door Bird beheerde templates melden status: active. languages.<tag>.status geeft de status van WhatsApp voor één taal, zoals approved, paused of disabled.

Een actieve template kan toch een niet-beschikbare taal hebben. Gebruik available_languages om te bepalen of je een taal kunt verzenden.

De inhoud van een template lezen

De berichtinhoud hoort bij een taal in de live versie. Lees live_version_id uit de template en vraag daarna de gewenste taal op:

const language = await bird.request({
  method: "GET",
  path: "/v1/whatsapp/templates/bird_order_confirmation/versions/{version_id}/languages/en",
});

language = client.get(
    "/v1/whatsapp/templates/bird_order_confirmation/versions/{version_id}/languages/en"
)

var language map[string]any
if err := client.Get(context.Background(),
	"/v1/whatsapp/templates/bird_order_confirmation/versions/{version_id}/languages/en",
	&language); err != nil {
	log.Fatal(err)
}

$language = $bird->get('/v1/whatsapp/templates/bird_order_confirmation/versions/{version_id}/languages/en');

curl https://us1.platform.bird.com/v1/whatsapp/templates/bird_order_confirmation/versions/{version_id}/languages/en \
  -H "Authorization: Bearer $BIRD_API_KEY"

De templateverwijzing accepteert een slug- of wat_-ID. GET …/versions/{version_id}/languages toont de talen van de versie zonder hun inhoud.

Codevoorbeeld

{
  "category": "utility",
  "components": [
    {
      "example_parameters": [
        { "name": "ref", "text": "A1B2C3D4", "type": "text" },
        { "name": "amount", "text": "USD 49.99", "type": "text" }
      ],
      "text": "Your order {{ref}} has been confirmed for a total of {{amount}}. Thanks for shopping with us.",
      "type": "body"
    }
  ],
  "language": "en",
  "status": "approved"
}

Een verzending vult deze placeholders op naam in. example_parameters identificeert elke placeholder. In dit voorbeeld neemt parameters van de verzending de sleutels ref en amount. Bij een positionele template zijn de sleutels de nummers, zoals 1, met twee uitzonderingen: de code van een authenticatietemplate gebruikt code, en het genummerde achtervoegsel van een url-knop gebruikt button_url. Knoppen met parameters hebben hun eigen example_parameters.

De category van de taal is de Meta-categorie die voor de prijs wordt gebruikt. Deze kan afwijken van de geregistreerde categorie van de template als Meta de taal herclassificeert.

De lijst variables van de versie vat elke placeholder samen met de sleutel, het type, de verplicht-vlag en de beperking. Benoemde placeholders gebruiken hun naam als sleutel. Positionele placeholders gebruiken hun nummer, behalve een authenticatiecode (code) en het achtervoegsel van een url-knop (button_url). De parameters van een verzending gebruikt deze sleutels.

Verzenden met een template

Noem de template in het object template van de verzending en vul de variabelen in via parameters. Zie WhatsApp-berichten verzenden voor de volledige payload:

const msg = await bird.whatsapp.send({
  to: "+15551234567",
  template: {
    slug: "bird_otp",
    parameters: { code: "123456" },
  },
});
console.log(msg.id, msg.status);

msg = client.whatsapp.send(
    to="+15551234567",
    template="bird_otp",
    language="en",
    parameters={"code": "123456"},
)
print(msg.id, msg.status)

msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
	To:         "+15551234567",
	Template:   "bird_otp",
	Language:   "en",
	Parameters: map[string]any{"code": "123456"},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)

$message = $bird->whatsapp->send(
    to: '+15551234567',
    template: 'bird_otp',
    language: 'en',
    parameters: ['code' => '123456'],
);
echo $message->getId(), ' ', $message->getStatus();

bird whatsapp send \
  --language en \
  --parameters '{"code":"123456"}' \
  --template bird_otp \
  --to +15551234567

curl -X POST https://us1.platform.bird.com/v1/whatsapp/messages \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155550100",
    "template": {
      "slug": "bird_otp",
      "language": "en",
      "parameters": { "code": "481920" }
    }
  }'

Verzenden per categorie

Elke template heeft een van de drie categorieën van Meta. De categorie bepaalt wat je moet doen voordat een verzending slaagt en wat die kost. Voor het opstellen of kopiëren van een eigen authenticatietemplate heb je een geverifieerd bedrijf nodig, maar voor het verzenden niet: de beheerde bird_otp van Bird staat op het eigen WhatsApp Business Account van Bird en wordt verzonden zonder dat jij een verificatie nodig hebt. Marketingtemplates worden altijd verzonden vanaf een eigen WhatsApp Business Account, via een tweede Meta-API waarnaar Bird automatisch doorstuurt. Utilitytemplates hebben de minste vereisten van de drie.

Authenticatietemplates: eenmalige verificatiecodes, de knop om de code te kopiëren en de verificatievereiste voor het opstellen ervan
Utilitytemplates: orderupdates, afspraakherinneringen en accountmeldingen
Marketingtemplates: promotionele verzendingen, het bedrijfsaccount dat je nodig hebt en de verwachting rond afmelden

Volgende stappen

WhatsApp-berichten verzenden: de volledige verzendpayload waarin het object template past
Richtlijnen voor WhatsApp-templates: de regels waaraan Meta een template toetst
Authenticatietemplates: eenmalige verificatiecodes en de vereiste bedrijfsverificatie voordat je er zelf een opstelt
Prijzen van WhatsApp: hoe categorie en bestemming de prijs bepalen

Ga verder met de documentatie, handleidingen en voorbeelden voor dit onderwerp.

Probeer de oefening en ontvang een implementatieoverzicht

Gerelateerde bronnen