Invio di messaggi WhatsApp

Un invio minimale

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"
            }
          ]
        }
      ]
    }
  }'

La finestra di servizio clienti

Costruire il payload

Destinatario

Template

• slug (obbligatorio): lo slug del template, ad esempio bird_order_confirmation. Deve corrispondere a un template nel vostro catalogo (lettere minuscole, cifre e underscore).
• language: il tag lingua del template, ad esempio en o pt-BR. Omettetelo per inviare la lingua predefinita del template; specificare una lingua che il template non possiede restituisce un 422 che elenca quelle disponibili. Il messaggio accettato riporta la lingua risolta.
• components: i valori che riempiono le variabili del template (vedi Componenti e parametri). Omettetelo per un template senza variabili.

Componenti e parametri

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

Categoria e mittente

• Un template gestito da Bird (il cui slug inizia con bird_) viene inviato dal numero che Bird mantiene per quella categoria, quindi omettete from. Impostarlo restituisce un 422 WhatsAppSenderNotAllowed.
• Tutto il resto specifica il proprio mittente in from: un messaggio di servizio di qualsiasi tipo e qualsiasi template creato dal vostro spazio di lavoro. Il numero deve appartenere al vostro spazio di lavoro. Ometterlo restituisce un 422 WhatsAppSenderRequired, e un numero dal quale lo spazio di lavoro non può inviare restituisce un 422 WhatsAppSenderNotFound. Un template creato da voi deve inoltre trovarsi sullo stesso WhatsApp Business Account del numero, altrimenti l'invio restituisce un 422 WhatsAppSenderWABAMismatch.

Messaggi di servizio

• text: { "body": "..." }, fino a 4096 caratteri. Aggiungete "preview_url": true per mostrare un'anteprima del link per il primo URL in body.
• image, video, audio, sticker, document: ciascuno accetta un URL https pubblico che WhatsApp scarica al momento dell'invio (url), quindi un URL firmato deve restare valido oltre l'invio. Un URL http viene rifiutato immediatamente. WhatsApp scarica il file stesso, quindi un URL non raggiungibile, che serve un tipo non supportato o un file che supera il limite di dimensione per quel tipo viene accettato e poi fallisce, con media_rejected sullo last_error del messaggio e la motivazione propria di WhatsApp in description. image, video e document accettano anche un caption opzionale; document accetta anche un filename opzionale; audio accetta un flag voice opzionale per la resa come nota vocale.
• location: { "latitude": ..., "longitude": ... } (entrambi obbligatori, gradi decimali) più name e address opzionali.
• contact_cards: un array di massimo cinque contatti condivisi in un unico messaggio. Il campo name di ogni scheda richiede formatted_name più almeno un'altra parte (first_name, last_name, middle_name, prefix o suffix); phone_numbers, emails, urls e addresses accettano ciascuno fino a dieci voci, mentre org e birthday (come YYYY-MM-DD) sono opzionali. Un phone_number in E.164 aggiunge alla scheda un pulsante che apre una chat con quel contatto.
• interactive: testo nel body più un elemento interattivo, in uno dei sei tipi: pulsanti di risposta, un menu a lista, un pulsante con link, un carosello multimediale o un singolo pulsante che chiede al destinatario la propria posizione o il proprio numero di telefono. Messaggi interattivi copre la struttura wire di ogni tipo, le risposte generate da un tap e i limiti.

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

Citare un messaggio

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

Tag e metadati

• tags: fino a 20 etichette { "name": ..., "value": ... } strutturate per dimensioni a bassa cardinalità su cui filtrare e creare report (una campagna, una variante di esperimento). Nomi e valori accettano lettere ASCII, cifre, underscore e trattino; i nomi sono limitati a 32 caratteri e univoci all'interno di un invio, i valori a 64. Filtrate l'elenco messaggi per tag (?tag=campaign o ?tag=campaign:launch-week) e la pagina Metriche suddivide le consegne per tag.
• metadata: un singolo oggetto JSON arbitrario, fino a 2 KB serializzato, per contesto per-invio che non serve come dimensione di filtro (un ID ordine interno, un riferimento di sessione).

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

Riferimento campi

Il modello asincrono: cosa significa 202

Riprovare in sicurezza

Ricevere la risposta

Costi e fatturazione

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.

• Al momento del 202, cost è null. Nulla è stato tariffato.
• Dopo l'elaborazione, transaction_amount è impostato e amount lo eguaglia. passthrough_amount resta null.
• Dopo una ricevuta delivered o read applicabile, un addebito Meta registrato con successo popola passthrough_amount e amount riflette le componenti registrate.

Prossimi passi

• Messaggi di servizio: invia testo, media e contenuti interattivi all'interno della finestra di servizio clienti
• Template: scegli un template e fornisci le sue variabili
• Ricezione dei messaggi WhatsApp: leggi le risposte e recupera i media in entrata
• Webhook sullo stato dei messaggi: ricevi aggiornamenti su consegna e errori
• Idempotenza: riprovare in sicurezza con l'header Idempotency-Key