Inviare messaggi WhatsApp

Questa guida descrive l'endpoint di invio, POST /v1/whatsapp/messages. Costruisci un unico payload JSON con un destinatario e un solo tipo di contenuto: un template pre-approvato oppure un messaggio di servizio con testo, un'immagine, un video, un audio, uno sticker, un documento, una posizione, schede contatto o un elemento da toccare. Bird restituisce 202 Accepted con un ID messaggio e consegna in modo asincrono. Quale dei due puoi inviare dipende dalla finestra di assistenza clienti. Ogni richiesta invia un messaggio a un destinatario e non esiste un endpoint batch.

Un invio minimo

Il payload valido più piccolo è composto da un destinatario to e da un template con il relativo slug. Aggiungi language se vuoi una lingua specifica; se lo ometti, viene inviata la lingua predefinita del template. Compila le eventuali variabili dichiarate dal template tramite parameters.

La chiamata curl usa l'host statunitense; se la tua chiave inizia con bk_eu1_, chiama invece https://eu1.platform.bird.com. Gli SDK ricavano la regione dalla chiave, quindi non impostano alcun host.

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://{region}.platform.bird.com/v1/whatsapp/messages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15551234567",
    "template": {
      "slug": "bird_otp",
      "language": "en",
      "parameters": {
        "code": "123456"
      }
    }
  }'

La finestra di assistenza clienti

Quale dei due puoi inviare dipende da un solo stato: se la finestra di assistenza clienti è aperta.

Il contatto apre la finestra inviando un messaggio o chiamando il numero della tua azienda. La finestra resta aperta per 24 ore e si azzera ogni volta che il contatto ti scrive di nuovo. Mentre è aperta puoi inviare un messaggio di servizio, cioè qualsiasi contenuto libero: testo, immagine, video, audio, sticker, documento, posizione, schede contatto o contenuto interattivo. Quando scade, al contatto arriva solo un template pre-approvato, e la sua risposta riapre la finestra.

Bird tiene traccia della finestra per te, quindi un messaggio di servizio inviato a finestra chiusa viene rifiutato prima che venga creato o addebitato qualcosa: la richiesta restituisce un 422 E15044 WhatsAppServiceWindowClosed. Il controllo è best effort e in caso di dubbio lascia passare la richiesta, quindi un 202 non prova che la finestra fosse davvero aperta al momento dell'invio. Se la finestra scade tra l'accettazione e l'invio, il messaggio fallisce in modo asincrono, con service_window_expired nel suo last_error.

Consulta la finestra di assistenza clienti per il ciclo di vita completo: cosa la apre, cosa la azzera e come incide sui prezzi.

Costruire il payload

Destinatario

to indica una sola destinazione, sotto forma di numero di telefono, ID utente con ambito aziendale o ID di gruppo. Un numero di telefono è in formato E.164: un + iniziale, il prefisso internazionale e il numero dell'abbonato, ad esempio +14155550100. Convalidiamo il numero, quindi un valore che non può essere un numero reale e componibile (lunghezza errata, prefisso non assegnato) viene rifiutato con un 422 WhatsAppInvalidRecipient prima di qualsiasi addebito. Non esistono un array di destinatari né un invio in blocco, quindi per raggiungere molte persone che non fanno parte di un unico gruppo serve una chiamata per ogni destinatario.

Un ID utente con ambito aziendale come US.13491208655302741918 indirizza un contatto di cui non hai il numero di telefono: è così che rispondi a un contatto che ti ha scritto senza mostrarlo. Cambiano due cose: il numero mittente deve appartenere allo stesso portfolio aziendale a cui si riferisce l'ID, e un template di codice di verifica monouso richiede un numero di telefono. Un template gestito da Bird viene rifiutato all'accettazione con un 422 WhatsAppRecipientNotSupportedForTemplate; un template di autenticazione creato dal tuo spazio di lavoro viene accettato e poi fallisce, perché Meta richiede un numero di telefono.

to accetta anche un'altra forma: un ID di gruppo WhatsApp come wag_01krdgeqcxet5s7t44vh8rt9mg, che invia il messaggio a tutti i partecipanti di quella chat di gruppo. Un invio di gruppo omette from e riporta la consegna sull'intero gruppo anziché su un singolo destinatario, per questo è trattato in una pagina dedicata: Invio a un gruppo WhatsApp.

Template

template indica il template pre-approvato da inviare:

• slug (obbligatorio): lo slug del template, ad esempio bird_order_confirmation. Deve corrispondere a un template del tuo catalogo (lettere minuscole, cifre e trattini bassi).
• language: il tag di lingua del template, ad esempio en o pt-BR. Omettilo per inviare la lingua predefinita del template; se indichi una lingua che il template non ha, ricevi un 422 con l'elenco di quelle disponibili. Il messaggio accettato riporta la lingua risolta.
• parameters: i valori che compilano le variabili del template, in un unico oggetto con chiavi per nome (vedi Componenti e parametri). Omettilo per un template senza variabili.
• components: gli stessi valori nella struttura a componenti di Meta, al posto di parameters. Alcuni template accettano solo questa forma.

Consulta i tuoi template, le loro lingue e un'anteprima di ciascuno nella pagina Templates.

Componenti e parametri

I template contengono variabili, con nome ({{ref}}, {{amount}}) o numerate ({{1}}, {{2}}). Compilale tramite parameters, un unico oggetto. Il campo variables della versione del template elenca le chiavi accettate e indica quelle facoltative. Ogni chiave è una delle seguenti:

• il nome di una variabile con nome, ad esempio order_id
• il numero di una variabile numerata, ad esempio 1
• header_url, header_filename o header_location per un'intestazione multimediale o di posizione, e header_url_1, header_url_2 e così via per l'intestazione di una scheda del carosello
• button_url per il suffisso numerato di un pulsante URL, e button_url_1, button_url_2 e così via per il pulsante di una scheda del carosello. Un suffisso con nome usa il proprio nome.
• code per il codice di un template di autenticazione e per il valore di un pulsante di copia del codice
• un input letto dai binding dei parametri della lingua

Ogni valore è una stringa, un numero o un booleano. header_location accetta un oggetto con latitude e longitude. Se ometti un'intestazione multimediale, viene inviato il campione approvato del template. Un template importato da Meta non ha un campione, quindi richiede la chiave dell'intestazione multimediale. Le chiavi che la lingua non usa vengono ignorate.

{
  "to": "+15551234567",
  "from": "+13124495648",
  "template": {
    "slug": "order_update",
    "language": "en",
    "parameters": { "order_id": "A-4192", "first_name": "Ava" }
  }
}

Con CLI, passa l'oggetto con --parameters:

bird whatsapp send --to +15551234567 --from +13124495648 \
  --template order_update --language en \
  --parameters '{"order_id":"A-4192","first_name":"Ava"}'

Un template di autenticazione il cui corpo è {{1}} is your verification code e il cui pulsante copia il codice riceve il codice una sola volta come code. Bird lo inserisce sia nel corpo sia nel pulsante:

{
  "parameters": { "code": "481920" }
}

Una lingua i cui binding leggono dati del contatto, come bird.contact.first_name, non può essere inviata come singolo messaggio e restituisce E15091. Inviala invece in un broadcast, dove i dati di ciascun destinatario la compilano. Un broadcast salta il destinatario i cui dati del contatto lasciano vuoto un valore obbligatorio. Invia parameters oppure components, non entrambi. Alcuni template accettano solo parameters: quelli la cui lingua calcola i valori con i binding dei parametri e quelli con variabili con nome in una scheda del carosello o nell'URL di un pulsante.

Alcuni template accettano solo components, perché una sola chiave non riesce a distinguere i loro slot. Succede quando un template numera {{1}} in più di un blocco, ad esempio nell'intestazione e nel corpo. Succede anche quando un blocco ha due pulsanti url con suffissi numerati, oppure una variabile {{button_url}} accanto a un pulsante url numerato. Se invii un template di questo tipo con parameters, ricevi 422.

Compilare un template per componente. components è l'alternativa a parameters ed è l'unica forma possibile per un template che una sola chiave non riesce a indirizzare. Ogni componente indica un type (header, body, button o carousel) e un array parameters. Un carousel accetta invece un array cards, con una voce per ogni scheda approvata, nell'ordine di approvazione. Ogni scheda contiene il proprio array components di voci header, body e button. Ogni parametro indica il proprio type (text, image, video, gif, document o location) e contiene il campo corrispondente: per text una semplice stringa, per image/video/gif/document un url https pubblico, per location un punto sulla mappa. Un template con parametri nominati richiede un name su ogni parametro, che corrisponda esattamente ai nomi dichiarati dal template (vedi Riferimento dei campi). Un template posizionale omette name e riceve i valori nell'ordine di {{n}}, quindi il primo parametro compila {{1}}. In entrambi i casi, i parametri che non corrispondono a quanto dichiarato dal template restituiscono un 422 WhatsAppTemplateParameterMismatch. Un componente header su un template gestito da Bird viene scartato, perché nessun template gestito da Bird dichiara una variabile di intestazione; su un template creato dal tuo spazio di lavoro viene invece inoltrato, ed è così che un template utility o marketing con intestazione multimediale riceve la sua immagine.

Lo stesso template per il codice di verifica riceve il codice sia come parametro del corpo sia come parametro del pulsante, in modo posizionale (senza name):

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

Categoria e mittente

La categoria di un template (authentication, utility o marketing) determina come WhatsApp tratta il messaggio e, insieme al paese di destinazione, quanto costa.

Chi possiede il mittente determina se devi indicarlo:

• Un template gestito da Bird (il cui slug inizia con bird_) viene inviato dal numero che Bird riserva a quella categoria, quindi ometti from. Se lo imposti, ricevi un 422 WhatsAppSenderNotAllowed.
• In tutti gli altri casi indichi il mittente in from: per un service message di qualsiasi tipo e per qualsiasi template creato dal tuo spazio di lavoro. Il numero deve appartenere al tuo spazio di lavoro. Se lo ometti, ricevi un 422 WhatsAppSenderRequired; un numero da cui lo spazio di lavoro non può inviare restituisce un 422 WhatsAppSenderNotFound. Un template creato da te deve inoltre trovarsi sullo stesso WhatsApp Business Account del numero, altrimenti l'invio restituisce un 422 WhatsAppSenderWABAMismatch.

Configurazione dei numeri di telefono descrive entrambi i tipi di numero e come collegare un numero tuo.

Service message

Al posto di template, includi esattamente uno tra text, image, video, audio, sticker, document, location, contact_cards o interactive. Sono tutti e nove service message, quindi richiedono una finestra di assistenza clienti aperta. Ognuno richiede anche from, un numero di proprietà del tuo spazio di lavoro: i numeri gestiti da Bird non possono inviarli.

• text: { "body": "..." }, fino a 4096 caratteri. Aggiungi "preview_url": true per mostrare l'anteprima del primo link presente 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 fino a invio completato. Un URL http viene rifiutato subito. WhatsApp scarica il file in autonomia, quindi un URL che non riesce a raggiungere, uno che restituisce 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 nel campo last_error del messaggio e il motivo indicato da WhatsApp in description. image, video e document accettano anche un caption facoltativo; document accetta anche un filename facoltativo; audio accetta un flag voice facoltativo per la visualizzazione come messaggio vocale.
• location: { "latitude": ..., "longitude": ... } (entrambi obbligatori, in gradi decimali) più name e address facoltativi.
• 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 facoltativi. Se una scheda contiene un phone_number in formato E.164, riceve un pulsante che apre una chat con quel numero.
• interactive: testo del corpo più un elemento da toccare, in uno di sei tipi: pulsanti di risposta, un menu a elenco, un pulsante link, un carosello multimediale oppure un singolo pulsante che chiede al destinatario la sua posizione o il suo numero di telefono. Messaggi interattivi descrive il formato di ciascun tipo, le risposte generate da un tocco e i limiti.

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

Una richiesta senza contenuto, o con più di un tipo di contenuto, viene rifiutata con un 422.

Citare un messaggio

Imposta in_reply_to_message_id sull'ID di un messaggio WhatsApp per inviare il tuo messaggio come risposta a quello, come quando si tocca Rispondi nell'app WhatsApp per citare un messaggio. Il destinatario vede il tuo messaggio con quello citato sopra, e il campo viene restituito a ogni lettura del messaggio.

Funziona anche in senso inverso: un messaggio in entrata che WhatsApp contrassegna come risposta riporta nello stesso campo l'ID del messaggio citato, così puoi capire a quale dei tuoi messaggi risponde. Un messaggio in entrata che WhatsApp non contrassegna non riporta alcun ID, e anche la risoluzione può non riuscire. Per una correlazione affidabile, usa identificatori di risposta interattivi espliciti insieme allo stato della conversazione o dell'attività salvato dalla tua applicazione. I metadata in uscita restano sul record in uscita e non vengono copiati automaticamente sulla risposta.

La citazione viene risolta prima che l'invio sia accettato, quindi una citazione che non può essere visualizzata fa fallire la richiesta stessa e nulla viene creato o addebitato. Un ID che non corrisponde a nessun messaggio presente in questo spazio di lavoro, o a un messaggio più vecchio dei 15 giorni in cui un messaggio resta citabile, restituisce un 404 E15071 WhatsAppReferencedMessageNotFound. Un ID che indica un messaggio mai arrivato a WhatsApp, o un messaggio di una conversazione diversa da quella definita da to e from di questo invio, restituisce un 422 E15072 WhatsAppMessageNotQuotable. Se Bird non riesce a raggiungere l'archivio che fornisce la risposta, l'invio restituisce un 503 E15073 WhatsAppMessageLookupUnavailable, per cui conviene riprovare. La citazione funziona sia con l'invio di un template sia con un invio a formato libero.

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

Tag e metadati

Tre campi facoltativi associano a un messaggio un tuo contesto; tutti e tre vengono restituiti nelle letture API e accompagnano ogni evento webhook del messaggio:

• tags: fino a 20 etichette { "name": ..., "value": ... } strutturate per dimensioni a bassa cardinalità su cui filtri e generi report (una campagna, una variante di un esperimento). Nomi e valori accettano lettere ASCII, cifre, trattino basso e trattino; i nomi hanno un massimo di 32 caratteri e devono essere univoci all'interno di un invio, i valori un massimo di 64. Filtra l'elenco dei messaggi per tag (?tag=campaign o ?tag=campaign:launch-week); la pagina Metrics suddivide il recapito per tag.
• metadata: un oggetto JSON arbitrario, fino a 2 KB una volta serializzato, per il contesto del singolo invio che non ti serve come dimensione di filtro (un ID ordine interno, un riferimento di sessione).
• reference: una stringa da 1 a 255 caratteri con cui vuoi ritrovare il messaggio, ad esempio un numero d'ordine o di ticket. ?reference= nell'elenco dei messaggi la confronta in modo esatto, distinguendo maiuscole e minuscole, e più messaggi possono condividere lo stesso valore. Impostala solo quando devi cercare in base a essa e inserisci qualsiasi altro dato in metadata.

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

Riferimento dei campi

* language è facoltativo; se lo ometti, viene inviata la lingua predefinita del template. † name è obbligatorio su ogni parametro di un template con parametri denominati. Omettilo per un template posizionale. Vedi Componenti e parametri. ** Includi esattamente uno tra template e un campo di contenuto per messaggi di servizio (text, image, video, audio, sticker, document, location, contact_cards, interactive); vedi Messaggi di servizio.

Il modello asincrono: cosa significa 202

Un invio riuscito restituisce 202 Accepted con un ID messaggio e status: accepted. Il 202 viene restituito solo dopo che l'invio è stato accettato in modo durevole: un invio non viene mai accettato e poi scartato in silenzio. Gli errori definitivi che puoi correggere falliscono subito con un 422: un destinatario non valido, uno slug o una lingua del template sconosciuti, parametri non corrispondenti, oppure un messaggio di servizio inviato con la finestra di assistenza clienti chiusa (WhatsAppServiceWindowClosed). Un wallet senza fondi non rientra tra questi casi: l'invio viene accettato e il messaggio termina in rejected con insufficient_balance quando Bird prova ad addebitarlo. La consegna effettiva avviene in modo asincrono: il messaggio passa a sent quando lo consegniamo a WhatsApp, poi a uno stato finale (delivered o failed) quando arriva la ricevuta, segnalato tramite eventi, webhook e gli endpoint di lettura. Una conferma di lettura viene esposta separatamente come timestamp read_at e come evento whatsapp.read, non come stato.

Una nota sulla privacy: per i template della categoria authentication, la API non restituisce mai i valori inseriti. L'eco 202 e ogni lettura successiva riportano un array components vuoto per questi messaggi, così un codice di verifica non riappare mai.

Riprovare in sicurezza

Invia l'header Idempotency-Key con un valore univoco per ogni invio logico, così i nuovi tentativi diventano sicuri. Se la prima richiesta è riuscita ma non hai ricevuto la risposta (timeout, connessione interrotta), ripeterla con la stessa chiave restituisce il risultato originale invece di inviare, e addebitare, un messaggio duplicato. La risposta ripetuta include un header Idempotency-Replay. Consulta idempotenza per il formato e la conservazione delle chiavi.

Ricevere la risposta

I messaggi in entrata arrivano sulla stessa risorsa di quelli in uscita, e ognuno di essi reimposta la finestra di servizio. Ricevere messaggi WhatsApp spiega come leggerli tramite API, come recuperare i contenuti multimediali inviati da un contatto e il webhook whatsapp.received.

Costi e fatturazione

WhatsApp ha un prezzo per messaggio, basato sulla categoria del template e sul paese del destinatario; consulta prezzi di WhatsApp. Un messaggio viene addebitato in due fasi, in due momenti diversi, e l'oggetto cost del messaggio le riporta entrambe:

Entrambi gli importi sono stringhe decimali, al netto delle imposte.

Nota: fino al 30 settembre 2026 un service message non include alcuna quota Meta, e lo stesso vale per un template utility consegnato mentre la finestra di assistenza clienti è aperta. Dal 1° ottobre 2026 Meta addebita entrambi, salvo all'interno di una finestra free entry point di 72 ore e con 1.000 service message gratuiti per numero di telefono aziendale al mese: modifiche ai prezzi di ottobre 2026.

Le due componenti hanno un prezzo calcolato su dati diversi. La tariffa di Bird usa la categoria del template inviato e il paese del destinatario. Il paese deriva dal prefisso internazionale del numero di telefono oppure, per un invio indirizzato a un ID utente con ambito aziendale, dal prefisso di due lettere di quell'ID. La quota Meta usa la categoria che Meta stessa riporta nella ricevuta applicabile, che può differire da quella del template: Meta può riportare authentication-international quando si applicano le sue regole su destinazione, sede dell'azienda e idoneità. Consulta tariffe authentication-international di WhatsApp.

Il contenuto di cost dipende dal punto in cui si trova il messaggio:

• Al momento della 202, cost è null. Non è stato ancora calcolato alcun prezzo.
• Dopo l'elaborazione, transaction_amount è valorizzato e amount ha lo stesso valore. passthrough_amount resta null.
• Dopo una ricevuta delivered o read applicabile, un addebito Meta registrato correttamente valorizza passthrough_amount, e amount riflette le componenti registrate.

Una componente null indica che in quella proiezione non è registrato alcun importo; non dimostra che il messaggio fosse gratuito. Una componente con prezzo esplicitamente pari a zero vale "0.00000".

I due addebiti falliscono anche in modo diverso. La tariffa di Bird fallisce in modo chiuso: se non può essere addebitata dopo la 202 perché il wallet non copre l'invio o la rotta non ha un prezzo configurato, il messaggio termina rejected con il codice di errore insufficient_balance o price_not_found, e non viene addebitato nulla. Un messaggio rejected non ha mai raggiunto WhatsApp, ed è questo che lo distingue da failed. La quota Meta fallisce in modo aperto: se all'arrivo della ricevuta il wallet non ha fondi sufficienti o manca la tariffa, l'addebito viene saltato senza annullare lo stato osservato del messaggio. Il secondo addebito non ritarda mai la consegna.

Un messaggio addebitato da Bird mantiene quell'addebito in uscita anche se la consegna fallisce in seguito. La tariffa Meta viene elaborata da un callback delivered o read applicabile quando Meta riporta un prezzo regolare con categoria e destinazione determinabili. Entrambi i percorsi di callback usano la stessa identità della tariffa e si affidano alla deduplicazione del servizio di fatturazione. Riconcilia le ricevute ripetute con i record di fatturazione, invece di trattare la proiezione del messaggio come una ricevuta di addebito definitiva. I prezzi per i service message o per le free entry point possono azzerare la componente Meta; una componente non determinata non dimostra che il messaggio fosse gratuito.

Per la riconciliazione finanziaria usa il registro di fatturazione. I campi cost del messaggio sono proiezioni degli addebiti e possono essere in ritardo o restare incompleti. Consulta metriche di WhatsApp per la differenza tra osservazioni sui messaggi e record di fatturazione.

Gli eventi WhatsApp non includono il costo. Per leggere una delle due componenti, rileggi il messaggio con GET /v1/whatsapp/messages/{id}.

Passaggi successivi

• Messaggi di servizio: invia testo, contenuti multimediali e contenuti interattivi all'interno della finestra di assistenza clienti
• Template: scegli un template e fornisci le sue variabili
• Ricevere messaggi WhatsApp: leggi le risposte e scarica i contenuti multimediali in arrivo
• Webhook di stato dei messaggi: ricevi aggiornamenti su consegne ed errori
• Idempotenza: riprova in sicurezza con l'header Idempotency-Key