WhatsApp-berichten versturen

Een minimale verzending

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

msg = client.whatsapp.send(
    to="+31612345678",
    template="bird_otp",
    language="en",
    components=[{"type": "body", "parameters": [{"type": "text", "text": "123456"}]}],
)
print(msg.id, msg.status)

code := "123456"
msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
	To:       "+15551234567",
	Template: "bird_otp",
	Language: "en",
	Components: []bird.WhatsAppMessageTemplateComponent{{
		Type:       "body",
		Parameters: &[]bird.WhatsAppMessageTemplateComponentParameter{{Type: "text", Text: &code}},
	}},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)

$message = $bird->whatsapp->send(
    to: '+15551234567',
    template: 'bird_otp',
    language: 'en',
    components: [
        (new WhatsAppMessageTemplateComponent())
            ->setType('body')
            ->setParameters([
                (new WhatsAppMessageTemplateComponentParameter())->setType('text')->setText('123456'),
            ]),
    ],
);
echo $message->getId(), ' ', $message->getStatus();

bird whatsapp send \
  --components '[{"parameters":[{"text":"1234","type":"text"}],"type":"body"},{"parameters":[{"text":"1234","type":"text"}],"type":"button"}]' \
  --language en \
  --template bird_otp \
  --to +31612345678

curl -X POST "https://{region}.platform.bird.com/v1/whatsapp/messages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+31612345678",
    "template": {
      "slug": "bird_otp",
      "language": "en",
      "components": [
        {
          "type": "body",
          "parameters": [
            {
              "type": "text",
              "text": "1234"
            }
          ]
        },
        {
          "type": "button",
          "parameters": [
            {
              "type": "text",
              "text": "1234"
            }
          ]
        }
      ]
    }
  }'

Het klantenservicevenster

De payload opbouwen

Ontvanger

Template

• slug (verplicht): de slug van het template, zoals bird_order_confirmation. Het moet overeenkomen met een template in je catalogus (kleine letters, cijfers en underscores).
• language: de taaltag van het template, zoals en of pt-BR. Laat het weg om de standaardtaal van het template te verzenden; een taal opgeven die het template niet heeft geeft een 422 terug met de talen die het wél heeft. Het geaccepteerde bericht echoot de bepaalde taal.
• components: de waarden die de variabelen van het template invullen (zie Componenten en parameters). Laat het weg voor een template zonder variabelen.

Componenten en parameters

{
  "components": [
    { "type": "body", "parameters": [{ "type": "text", "text": "481920" }] },
    { "type": "button", "parameters": [{ "type": "text", "text": "481920" }] }
  ]
}

Categorie en afzender

• Een Bird-beheerd template (de slug begint met bird_) verstuurt vanaf het nummer dat Bird voor die categorie bewaart, dus laat from weg. Het instellen ervan geeft een 422 WhatsAppSenderNotAllowed terug.
• Al het andere benoemt zijn eigen afzender in from: een servicebericht van elk type, en elk template dat je werkruimte heeft gemaakt. Het nummer moet er een zijn dat je werkruimte bezit. Het weglaten ervan geeft een 422 WhatsAppSenderRequired terug, en een nummer waarvandaan de werkruimte niet kan verzenden geeft een 422 WhatsAppSenderNotFound terug. Een zelfgemaakt template moet ook op hetzelfde WhatsApp Business Account staan als het nummer, anders geeft de verzending een 422 WhatsAppSenderWABAMismatch terug.

Serviceberichten

• text: { "body": "..." }, maximaal 4096 tekens. Voeg "preview_url": true toe om een linkpreview te renderen voor de eerste URL in body.
• image, video, audio, sticker, document: elk neemt een publieke https URL die WhatsApp ophaalt bij verzending (url), dus een gesigneerde URL moet langer geldig zijn dan de verzending duurt. Een http URL wordt direct geweigerd. WhatsApp haalt het bestand zelf op, dus een URL die het niet kan bereiken, een die een niet-ondersteund type serveert, of een bestand boven de groottelimiet voor dat type wordt geaccepteerd en faalt daarna, met media_rejected op de last_error van het bericht en de eigen reden van WhatsApp in description. image, video en document nemen ook een optionele caption; document neemt ook een optionele filename; audio neemt een optionele voice-vlag voor een voicenoteweergave.
• location: { "latitude": ..., "longitude": ... } (beide verplicht, decimale graden) plus optioneel name en address.
• contact_cards: een array van maximaal vijf contacten die in één bericht worden gedeeld. De name van elke kaart heeft formatted_name nodig plus minstens één ander onderdeel (first_name, last_name, middle_name, prefix of suffix); phone_numbers, emails, urls en addresses nemen elk maximaal tien items, en org en birthday (als YYYY-MM-DD) zijn optioneel. Een phone_number in E.164 levert die kaart een knop op die een chat ermee opent.
• interactive: bodytekst plus iets om op te tikken, in een van zes typen: antwoordknoppen, een lijstmenu, een linkknop, een mediacarrousel, of een enkele knop die de ontvanger om zijn locatie of telefoonnummer vraagt. Interactieve berichten behandelt de wire-structuur van elk type, de antwoorden die een tik oplevert, en de limieten.

{
  "to": "+16505551234",
  "from": "+13124495648",
  "text": { "body": "Your order shipped: https://example.com/track/A1B2C3", "preview_url": true }
}

Een bericht citeren

{
  "to": "+16505551234",
  "from": "+13124495648",
  "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
  "text": { "body": "Yes, that slot is still free." }
}

Tags en metadata

• tags: maximaal 20 gestructureerde { "name": ..., "value": ... }-labels voor dimensies met lage kardinaliteit waarop je filtert en rapporteert (een campagne, een experimentvariant). Namen en waarden accepteren ASCII-letters, cijfers, underscore en koppelteken; namen zijn beperkt tot 32 tekens en uniek binnen een verzending, waarden tot 64. Filter de berichtenlijst op tag (?tag=campaign of ?tag=campaign:launch-week), en de pagina Metrics splitst bezorging uit per tag.
• metadata: één willekeurig JSON-object, maximaal 2 KB geserialiseerd, voor context per verzending die je niet als filterdimensie nodig hebt (een intern order-ID, een sessieverwijzing).

{
  "tags": [{ "name": "campaign", "value": "order-confirmations" }],
  "metadata": { "order_id": "ord_8271" }
}

Veldreferentie

Het asynchrone model: wat 202 betekent

Veilig opnieuw proberen

Het antwoord ontvangen

Kosten en facturering

Note: a service message carries no Meta share until September 30th 2026, and neither does a utility template delivered inside an open customer service window. From October 1st 2026 Meta charges for both, except inside a 72-hour free entry point window, and with 1,000 free service messages per business phone number per month: October 2026 pricing changes.

• Bij de 202 is cost null. Er is nog niets geprijsd.
• Na verwerking is transaction_amount ingesteld en is amount gelijk eraan. passthrough_amount blijft null.
• Na een toepasselijke delivered- of read-ontvangstbevestiging vult een succesvol geregistreerde Meta-afschrijving passthrough_amount in, en amount weerspiegelt de geregistreerde componenten.

Volgende stappen

• Serviceberichten: de negen vrije-vormcontent-armen en wat elk ervan nodig heeft
• WhatsApp-berichten ontvangen: inkomende berichten, media en de whatsapp.received-webhook
• Business-scoped user IDs: een contact adresseren dat je zonder telefoonnummer heeft bereikt
• Templates: blader door de catalogus en lees de variabelen van een template
• Verzenden naar een WhatsApp-groep: een groep adresseren en de ontvangstbevestigingen per deelnemer lezen
• Idempotency: veilig opnieuw proberen met de Idempotency-Key-header