Skip to main content

POST /v1/whatsapp/campaigns

Crea la bozza di una campagna: un messaggio promozionale da mandare a molti clienti con un template approvato da Meta. La bozza non manda niente. Dopo averla creata aggiungi i destinatari e poi lanciala con le due dichiarazioni obbligatorie. La campagna creata via API è identica a una creata nel pannello: compare in MyFlow → Campagne, ne segue le regole di invio e lì si può mettere in pausa, riprendere o annullare.
Le campagne usano solo template promozionali (categoria MARKETING) già approvati da Meta, senza immagine, video o documento nell’intestazione. Per un messaggio di servizio a un solo cliente (conferma, promemoria, avviso) usa POST /v1/whatsapp/messages.

Request Body

Le variabili

Ogni variabile del template si indica con la sua chiave, la stessa che trovi in variables[].key di GET /v1/whatsapp/templates: Per ogni chiave scegli uno dei due modi: Vanno indicate tutte le variabili del template, e solo quelle. I testi diventano una riga sola: gli a capo e i caratteri di controllo diventano spazi, e più di tre spazi di fila si riducono a tre, perché Meta li rifiuta.
Con il valore per destinatario il nome del cliente non si riempie da solo: se il template dice Ciao {{1}}, manda il nome come valore di body.1 per ogni destinatario, e metti un fallback come «Cliente» per chi non ce l’ha.

Richiesta

Risposta

201 Created
I campi sono spiegati in Elenco campagne. Conserva l’id: serve per tutte le chiamate successive.
Questa chiamata non accetta Idempotency-Key: se la ripeti nasce una seconda bozza. Se non sai se la prima è andata a buon fine, controlla con GET /v1/whatsapp/campaigns prima di riprovare. Una bozza in più non manda niente e si elimina con cancel.

Il flusso completo

1

Crea la bozza

POST /v1/whatsapp/campaigns con nome, numero, template e variabili. Ricevi l’id.
2

Aggiungi i destinatari

POST /v1/whatsapp/campaigns/{id}/recipients, a blocchi di fino a 1000, con i valori per destinatario. Chi ha chiesto di non ricevere promozioni viene escluso da solo.
3

Lancia

POST /v1/whatsapp/campaigns/{id}/launch con "consent": true e "costs": true, subito o con un’ora di partenza. Il titolare dell’account riceve un’email.
4

Segui l'andamento

GET /v1/whatsapp/campaigns/{id} per stato e statistiche, oppure i webhook message.status per l’esito di ogni messaggio. Le risposte dei clienti arrivano come message.received.
Un esempio dall’inizio alla fine, con la campagna 48 creata qui sopra:
Meta fa pagare i messaggi promozionali, sul metodo di pagamento collegato all’account WhatsApp Business. Il costo lo stabilisce Meta, non MyCentralino. Per questo il lancio chiede una dichiarazione esplicita.

Errori

422 - invalid_name

Manca name, è vuoto o supera i 120 caratteri.

400 - number_required

L’account ha più numeri collegati e manca from. La risposta elenca i numeri in error.numbers.

400 - invalid_from

from non è un numero valido. Usa il formato +E.164, per esempio +390212345678.

404 - number_not_found

from non è un numero collegato a MyFlow su questo account.

422 - invalid_template

Manca template, oppure non è un oggetto con name.

422 - template_language_required

Il template esiste in più lingue: indica language. La risposta elenca le lingue disponibili in error.languages.

422 - template_not_found

Su quel numero non c’è un template promozionale (MARKETING) approvato con questo nome e lingua. Controlla nome, lingua, categoria e stato in GET /v1/whatsapp/templates: un template di servizio (UTILITY) o ancora in revisione non si può usare.

422 - template_not_usable

Il template ha un’immagine, un video o un documento nell’intestazione, oppure parti che via API non si possono riempire: una posizione nell’intestazione, un carosello, un’offerta a tempo, pulsanti di tipo diverso da risposta rapida, link o telefono. Scegli un altro template.

422 - campaign_variables

Le variabili non corrispondono al template. L’errore aggiunge: Capita anche se variables non è un oggetto.
Gli errori comuni a tutte le rotte sono nell’introduzione.