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 tuo catalogo (lettere minuscole, cifre e underscore).
• language: il tag lingua del template, ad esempio en o pt-BR. Omettilo 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 compilano le variabili del template (vedi Componenti e parametri). Omettilo 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_) invia dal numero che Bird riserva per quella categoria, quindi ometti from. Impostarlo restituisce un 422 WhatsAppSenderNotAllowed.
• Qualsiasi altra cosa indica il proprio mittente in from: un messaggio di servizio di qualsiasi tipo e qualsiasi template creato dal tuo spazio di lavoro. Il numero deve appartenere al tuo spazio di lavoro. Ometterlo restituisce un 422 WhatsAppSenderRequired, e un numero da cui lo spazio di lavoro non può inviare restituisce un 422 WhatsAppSenderNotFound. Un template creato deve inoltre appartenere allo stesso WhatsApp Business Account del numero, altrimenti l'invio restituisce un 422 WhatsAppSenderWABAMismatch.

Messaggi di servizio

• text: { "body": "..." }, fino a 4096 caratteri. Aggiungi "preview_url": true per renderizzare 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 rimanere valido oltre l'invio. Un URL http viene rifiutato immediatamente. WhatsApp scarica il file stesso, quindi un URL che non riesce a raggiungere, uno che serve un tipo non supportato o un file che supera il limite di dimensione per il suo tipo viene accettato e poi fallisce, con media_rejected sul last_error del messaggio e il motivo specifico 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 messaggio. Il 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, e org e birthday (come YYYY-MM-DD) sono opzionali. Un phone_number in E.164 assegna a quella scheda un pulsante che apre una chat con esso.
• interactive: testo del corpo più qualcosa da toccare, 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 che un tocco produce 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 generare 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. Filtra la lista messaggi per tag (?tag=campaign o ?tag=campaign:launch-week), e la pagina Metriche suddivide le consegne per tag.
• metadata: un oggetto JSON arbitrario, fino a 2 KB serializzato, per contesto per-invio che non ti 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

• Al 202, cost è null. Nulla è stato prezzato.
• 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 correttamente popola passthrough_amount e amount riflette i componenti registrati.

Prossimi passi

• Messaggi di servizio: i nove tipi di contenuto libero e cosa accetta ciascuno
• Ricezione di messaggi WhatsApp: messaggi in entrata, media e il webhook whatsapp.received
• User ID con ambito business: indirizzare un contatto che ti ha raggiunto senza un numero di telefono
• Templates: sfoglia il catalogo e leggi le variabili di un template
• Idempotenza: come riprovare in sicurezza con l'header Idempotency-Key