Je eerste WhatsApp-bericht versturen

Stuur met Bird WhatsApp een WhatsApp-bericht naar je eigen telefoon en lees het bericht daarna terug om de aflevering te bevestigen. Berichten die een bedrijf zelf start, gebruiken een vooraf goedgekeurd sjabloon. Deze quickstart verstuurt vanuit de beheerde sjablooncatalogus van Bird (zoals bird_delivery_update of bird_otp), die een gedeelde, door Bird beheerde WhatsApp-afzender gebruikt. Je hoeft niet eerst een WhatsApp Business Account te koppelen of een nummer te registreren.

Zorg voordat je begint dat er saldo in de wallet van je organisatie staat. WhatsApp-sjabloonberichten worden van de wallet afgeschreven, en Bird weigert een verzending die het saldo niet dekt met 402 WalletInsufficientBalance. In Betaalmethoden en wallet lees je hoe je opwaardeert.

1. Maak een API-sleutel aan

Ga in het dashboard naar Platform tools > API keys en maak een sleutel aan met de scope whatsapp:write, waarmee je berichten kunt versturen en lezen. Sleutels zijn aan een regio gebonden en zien eruit als bk_us1_... of bk_eu1_.... De regio in het voorvoegsel bepaalt welke API-host je aanroept: https://us1.platform.bird.com of https://eu1.platform.bird.com.

De pagina API Keys in het Bird-dashboard, met sleutels, hun gemaskeerde voorvoegsel, scopes en het tijdstip van laatste gebruik

De volledige sleutel wordt één keer getoond, bij het aanmaken. Kopieer hem naar een veilige plek en exporteer hem daarna voor de cURL-voorbeelden:

Codevoorbeeld

export BIRD_API_KEY="bk_us1_..."

2. Verstuur een sjabloonbericht

Stuur het vooraf goedgekeurde bird_delivery_update-sjabloon uit de beheerde catalogus van Bird naar je telefoon, of gebruik bird_otp om een eenmalige verificatiecode te versturen. Beheerde sjablonen beginnen met bird_ en worden verstuurd vanaf een gedeeld Bird-nummer, dus je laat from weg. Installeer de Bird SDK voor je programmeertaal via de bijbehorende SDK-quickstart. Gebruik je het tabblad Bird CLI, installeer het dan eerst (curl -fsSL https://cli.bird.com/install.sh | sh) en meld je aan met schrijfrechten (bird auth login --scope whatsapp:write).

Vervang in de SDK-tabbladen de voorbeeldsleutel voor API, en vervang +15551234567 door je mobiele nummer in E.164-notatie. De CLI gebruikt je aanmelding, en het cURL-tabblad gebruikt BIRD_API_KEY.

import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({ apiKey: "bk_XXXXXXXXXXXXXXXXXXXXXXXX" });

const msg = await bird.whatsapp.send({
  to: "+15551234567",
  template: {
    slug: "bird_delivery_update",
    components: [
      {
        type: "body",
        parameters: [
          { type: "text", name: "ref", text: "A1B2C3D4" },
          { type: "text", name: "date", text: "10 Jul 2026" },
        ],
      },
    ],
  },
});

console.log(msg.id, msg.status);

from bird import APIError, Bird

with Bird(api_key="bk_XXXXXXXXXXXXXXXXXXXXXXXX") as client:
    try:
        message = client.whatsapp.send(
            to="+15551234567",
            template="bird_delivery_update",
            components=[
                {
                    "type": "body",
                    "parameters": [
                        {"type": "text", "name": "ref", "text": "A1B2C3D4"},
                        {"type": "text", "name": "date", "text": "10 Jul 2026"},
                    ],
                }
            ],
        )
        print(message.id, message.status)
    except APIError as err:
        print("send failed:", err)

package main

import (
	"context"
	"fmt"
	"log"

	bird "github.com/messagebird/bird-sdk-go"
	"github.com/messagebird/bird-sdk-go/option"
)

func main() {
	client, err := bird.NewClient(option.WithAPIKey("bk_XXXXXXXXXXXXXXXXXXXXXXXX"))
	if err != nil {
		log.Fatal(err)
	}

	msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
		To:       "+15551234567",
		Template: "bird_delivery_update",
		Components: []bird.WhatsAppMessageTemplateComponent{{
			Type: "body",
			Parameters: &[]bird.WhatsAppMessageTemplateComponentParameter{
				{Type: "text", Name: bird.String("ref"), Text: bird.String("A1B2C3D4")},
				{Type: "text", Name: bird.String("date"), Text: bird.String("10 Jul 2026")},
			},
		}},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Status)
}

<?php

declare(strict_types=1);

require __DIR__ . '/../vendor/autoload.php';

use MessageBird\Bird;
use MessageBird\Wire\Model\WhatsAppMessageTemplateComponent;
use MessageBird\Wire\Model\WhatsAppMessageTemplateComponentParameter;

$bird = new Bird('bk_XXXXXXXXXXXXXXXXXXXXXXXX');

$message = $bird->whatsapp->send(
    to: '+15551234567',
    template: 'bird_delivery_update',
    components: [
        (new WhatsAppMessageTemplateComponent())
            ->setType('body')
            ->setParameters([
                (new WhatsAppMessageTemplateComponentParameter())->setType('text')->setName('ref')->setText('A1B2C3D4'),
                (new WhatsAppMessageTemplateComponentParameter())->setType('text')->setName('date')->setText('10 Jul 2026'),
            ]),
    ],
);

echo $message->getId(), ' ', $message->getStatus(), "\n";

bird whatsapp send \
  --components '[{"parameters":[{"name":"ref","text":"A1B2C3D4","type":"text"},{"name":"date","text":"10 Jul 2026","type":"text"}],"type":"body"}]' \
  --template bird_delivery_update \
  --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": "+15551234567",
    "template": {
      "slug": "bird_delivery_update",
      "components": [
        {
          "type": "body",
          "parameters": [
            { "type": "text", "name": "ref", "text": "A1B2C3D4" },
            { "type": "text", "name": "date", "text": "10 Jul 2026" }
          ]
        }
      ]
    }
  }'

Begint je sleutel met bk_eu1_? Roep dan https://eu1.platform.bird.com aan.

De API antwoordt met 202 Accepted en het aangemaakte bericht. De id ervan begint met wam_ en de status is accepted: Bird heeft het bericht geaccepteerd en levert het asynchroon af. Bewaar de id voor de volgende stap.

3. Controleer de afleverstatus

Haal het bericht op met de wam_-ID. Vervang WHATSAPP_MESSAGE_ID door de id uit stap 2 en vervang de voorbeeldsleutel voor API in de SDK-tabbladen door je eigen sleutel:

import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({ apiKey: "bk_XXXXXXXXXXXXXXXXXXXXXXXX" });

const msg = await bird.whatsapp.get("WHATSAPP_MESSAGE_ID");

console.log(msg.id, msg.status);

from bird import APIError, Bird

with Bird(api_key="bk_XXXXXXXXXXXXXXXXXXXXXXXX") as client:
    try:
        message = client.whatsapp.get("WHATSAPP_MESSAGE_ID")
        print(message.id, message.status)
    except APIError as err:
        print("read failed:", err)

package main

import (
	"context"
	"fmt"
	"log"

	bird "github.com/messagebird/bird-sdk-go"
	"github.com/messagebird/bird-sdk-go/option"
)

func main() {
	client, err := bird.NewClient(option.WithAPIKey("bk_XXXXXXXXXXXXXXXXXXXXXXXX"))
	if err != nil {
		log.Fatal(err)
	}

	msg, err := client.Whatsapp.Get(context.Background(), "WHATSAPP_MESSAGE_ID")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Status)
}

<?php

declare(strict_types=1);

require __DIR__ . '/../vendor/autoload.php';

use MessageBird\Bird;

$bird = new Bird('bk_XXXXXXXXXXXXXXXXXXXXXXXX');

$message = $bird->whatsapp->get('WHATSAPP_MESSAGE_ID');

echo $message->getId(), ' ', $message->getStatus(), "\n";

bird whatsapp get WHATSAPP_MESSAGE_ID

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

Het veld status geeft aan waar het bericht zich bevindt:

accepted: Bird heeft het bericht toegelaten en bereidt de overdracht aan WhatsApp voor.
sent: WhatsApp heeft het bericht geaccepteerd en sent_at legt vast wanneer.
delivered: WhatsApp heeft de aflevering op het apparaat van de ontvanger bevestigd en delivered_at legt vast wanneer. Als de ontvanger het bericht leest, wordt read_at ingesteld terwijl status delivered blijft.
failed of rejected: het bericht heeft de telefoon niet bereikt. last_error geeft de reden en Message status events bevat de foutcodes.

Vraag de status herhaaldelijk op totdat deze niet meer accepted of sent is, of abonneer je op WhatsApp-webhooks om elke wijziging in de aflever- en leesstatus te ontvangen (whatsapp.sent, whatsapp.delivered, whatsapp.read, whatsapp.failed). Gedeelde, door Bird beheerde nummers zijn alleen voor uitgaande berichten en sturen inkomende antwoorden niet door naar je werkruimte. Wil je antwoorden ontvangen, koppel dan je eigen nummer. Elk bericht verschijnt ook met de tijdlijn van gebeurtenissen op de pagina Messages.

Een mislukte verzending oplossen

402 WalletInsufficientBalance: het saldo in de wallet is onvoldoende voor het bericht. Waardeer de wallet op en verstuur het bericht opnieuw.
403 InsufficientScope: de API-sleutel heeft de scope whatsapp niet. Pas de scopes van de sleutel aan of maak een sleutel met whatsapp:write.
422 WhatsAppInvalidRecipient: het to-nummer is geen geldig E.164-telefoonnummer. Controleer de voorloop-+, de landcode en de abonneecijfers.

Volgende stappen

WhatsApp-berichten versturen: verstuur templates en vrije serviceberichten binnen het klantenservicevenster van 24 uur.
WhatsApp-templates: blader door de beheerde catalogus (bird_otp, bird_delivery_update en andere) of maak je eigen templates.
Een telefoonnummer koppelen: gebruik je eigen WhatsApp Business Account en afzendernummer, zodat je werkruimte ook inkomende antwoorden kan ontvangen.
WhatsApp-webhooks: ontvang afleverbevestigingen en leesbevestigingen (en inkomende berichten als je je eigen gekoppelde nummer gebruikt).
WhatsApp API-referentie: het volledige schema voor verzoeken en antwoorden.

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

Probeer de oefening en ontvang een implementatieoverzicht