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 invariables[].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.
Richiesta
Risposta
201 Created
id: serve per tutte le chiamate successive.
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.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
Mancaname, è vuoto o supera i 120 caratteri.
400 - number_required
L’account ha più numeri collegati e mancafrom. 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
Mancatemplate, oppure non è un oggetto con name.
422 - template_language_required
Il template esiste in più lingue: indicalanguage. 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.
