POST /v1/whatsapp/messages
Manda un messaggio WhatsApp a un cliente, da uno dei numeri collegati a MyFlow. Il messaggio parte come quelli scritti dall’Inbox e compare nella conversazione, segnato come inviato dal gestionale. Ci sono due tipi di messaggio, e la regola che li separa è di WhatsApp:
Se non sai se la finestra è aperta, guarda
conversation.window_open nello storico o nell’ultimo webhook. Un text a finestra chiusa risponde 409 window_closed: in quel caso manda un template.
Request Body
L’oggetto template
Ogni valore di
variables è una stringa (o un numero) da 1 a 1024 caratteri. A capo e tabulazioni diventano spazi e più di tre spazi di fila si riducono a tre: Meta non li accetta dentro una variabile.
Header
Richiesta
Un template:Risposta
202 Accepted: WhatsApp ha preso in carico il messaggio. La consegna arriva dopo, con l’evento webhook message.status.
Idempotency-Key già usata: 200 OK, la stessa risposta del primo invio e "duplicate": true. Nessun messaggio nuovo parte.
Campi della risposta
Idempotency-Key
Se una chiamata va in timeout non sai se il messaggio è partito. Con unaIdempotency-Key puoi ripeterla senza rischio:
- Stessa chiave, primo invio riuscito: ricevi
200con lo stessomessage_ide"duplicate": true. Nessun messaggio nuovo parte. - Stessa chiave, primo invio fallito: ricevi lo stesso errore del primo tentativo, con
"duplicate": truedentroerror. Per riprovare davvero usa una chiave nuova. - Stessa chiave mentre il primo invio è ancora in corso:
409idempotency_in_progress. Aspetta un attimo e ripeti. - La chiave identifica l’invio, non il contenuto. Con la stessa chiave e un body diverso ricevi l’esito del primo invio, e il secondo non parte.
- Vale per l’account, non per la singola chiave API, e resta legata all’invio per un anno.
- I controlli sul body (campi mancanti, template sbagliato, variabili) avvengono prima. Una richiesta respinta lì non consuma la chiave.
Da sapere
- Opt-out. Se il cliente ha chiesto di non ricevere messaggi promozionali, scrivendo STOP, i template
MARKETINGverso di lui rispondono403opted_out. I templateUTILITYe i messaggi di testo partono comunque. - Agente AI. Un messaggio dal gestionale conta come la risposta di un operatore. Se su quella conversazione risponde un agente AI, l’agente si mette da parte per il tempo impostato nell’agente, come quando scrive una persona dall’Inbox.
- Tetto giornaliero. Gli invii via API hanno un tetto al giorno per account, che si azzera a mezzanotte, ora italiana. Gli invii non riusciti non contano. Oltre il tetto la risposta è
429daily_send_limit. Per scrivere a molti clienti insieme usa le Campagne, fatte apposta. - Template senza file. L’API per ora non allega file: i template con un’immagine, un video o un documento nell’intestazione rispondono
template_not_usable. Vale lo stesso per caroselli e offerte a tempo. - Costi di Meta. L’invio di un template può avere un costo di Meta, secondo il listino di Meta e la categoria del template. Il testo libero dentro la finestra delle 24 ore non ha costi di Meta.
Errori
400 - invalid_type
type manca o non è text né template.
400 - invalid_phone
to manca o non è un numero di telefono valido.
400 - invalid_text · 422 - invalid_text
Contype text: 400 se text manca o non è una stringa, 422 se dopo la pulizia è vuoto o supera i 4096 caratteri.
400 - invalid_template
Contype template: manca l’oggetto template o il suo name.
422 - template_not_found
Nessun template con quel nome sull’account WhatsApp Business del numero. L’elenco è in GET /v1/whatsapp/templates.422 - template_not_approved
Il template esiste ma non è approvato. Il messaggio dice lo stato, es. «Il template non è approvato da Meta (stato: PENDING).».422 - template_language_required
Il template è approvato in più lingue e mancalanguage. error.languages elenca le lingue.
422 - template_not_usable
Il template non si può inviare via API: intestazione con un file, carosello, offerta a tempo, posizione o bottoni di un tipo non gestito. Il messaggio dice perché.422 - template_variables
Le variabili non corrispondono al template. La risposta dice cosa correggere:
Lo stesso codice, senza questi campi, arriva se
variables non è un oggetto.
403 - opted_out
Il cliente ha chiesto di non ricevere messaggi promozionali (STOP), e il template èMARKETING.
409 - window_closed
Contype text: il cliente non ti ha mai scritto da questo numero, oppure sono passate più di 24 ore dal suo ultimo messaggio. error.needs_template è true: manda un template.
409 - idempotency_in_progress
Un invio con la stessaIdempotency-Key è ancora in corso.
429 - daily_send_limit
Raggiunto il tetto giornaliero di invii via API dell’account. Riprova dopo mezzanotte, oppure usa le Campagne.502 - meta_error
WhatsApp ha rifiutato l’invio. Il messaggio è la spiegazione in italiano dell’errore di WhatsApp.error.meta_code è il codice originale di Meta, es. 131026 (il numero non è su WhatsApp) o 131047 (finestra di 24 ore chiusa). Il messaggio non è partito.
400 - number_required / invalid_from · 404 - number_not_found
from manca con più numeri, non è valido o non è collegato all’account. Vedi l’elenco dei template.
Gli errori comuni a tutte le rotte sono nell’introduzione.