Skip to main content

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.

Richiesta

Un template:
Un testo, entro le 24 ore:

Risposta

202 Accepted: WhatsApp ha preso in carico il messaggio. La consegna arriva dopo, con l’evento webhook message.status.
Con una 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 una Idempotency-Key puoi ripeterla senza rischio:
  • Stessa chiave, primo invio riuscito: ricevi 200 con lo stesso message_id e "duplicate": true. Nessun messaggio nuovo parte.
  • Stessa chiave, primo invio fallito: ricevi lo stesso errore del primo tentativo, con "duplicate": true dentro error. Per riprovare davvero usa una chiave nuova.
  • Stessa chiave mentre il primo invio è ancora in corso: 409 idempotency_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.
Una Idempotency-Key fuori formato, cioè vuota, con spazi o caratteri non ASCII, oppure più lunga di 200 caratteri, viene ignorata. La richiesta parte senza protezione dai doppioni. Usa solo lettere, numeri e simboli come -, _, :.

Da sapere

  • Opt-out. Se il cliente ha chiesto di non ricevere messaggi promozionali, scrivendo STOP, i template MARKETING verso di lui rispondono 403 opted_out. I template UTILITY e 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 è 429 daily_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

Con type text: 400 se text manca o non è una stringa, 422 se dopo la pulizia è vuoto o supera i 4096 caratteri.

400 - invalid_template

Con type 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 manca language. 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

Con type 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 stessa Idempotency-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.