Inviare una campagna WhatsApp tramite l'API
Invia una campagna WhatsApp tramite l'API: modello marketing, destinatari, lancio, quote del piano, limiti marketing di Meta e tracciamento delle consegne.
Per inviare una campagna WhatsApp tramite l'API con Genuka WA, fai approvare da Meta un modello
MARKETING, crei la campagna con POST /api/v1/campaigns e il suo elenco di destinatari, poi la
lanci con POST /api/v1/campaigns/{id}/launch. Ogni destinatario viene seguito fino alla lettura, e
Meta fattura i messaggi consegnati direttamente al tuo WhatsApp Business Account.
Ultimo aggiornamento: 8 ottobre 2026
Cosa ti serve prima di inviare una campagna
- Un numero collegato e il suo
connectionId: vedi Collegare un numero. - Una chiave API, usata solo lato server: vedi Autenticazione.
- Un metodo di pagamento sul tuo account Meta. Genuka è un Meta Tech Provider, non un BSP: Meta
fattura direttamente il tuo WhatsApp Business Account (WABA), e un cliente registrato tramite un
Tech Provider deve aggiungere il proprio metodo di pagamento
(Meta, Partners).
Senza, il modello viene approvato ma ogni invio torna indietro con l'errore
131042. - Destinatari che hanno accettato di ricevere tue notizie. È una regola di WhatsApp, non una buona pratica: la sezione sull'opt-in più sotto ne parla.
Come creo il modello marketing?
Fuori dalla finestra del servizio clienti di 24 ore, viene consegnato solo un modello approvato. Una
campagna ne usa sempre uno. Invialo con la categoria MARKETING:
curl -X POST https://wa.genuka.com/api/v1/templates \
-H "Authorization: Bearer $GENUKA_WA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"connectionId": "con_1",
"name": "october_sale",
"language": "en_US",
"category": "MARKETING",
"components": [
{ "type": "BODY",
"text": "Hi {{1}}, 20% off the whole shop until Sunday.",
"example": { "body_text": [["Awa"]] } },
{ "type": "BUTTONS", "buttons": [
{ "type": "URL", "text": "See the offers", "url": "https://example.com/sale" }
] }
]
}'La risposta è un 201 con l'id del modello e il suo stato. Meta lo esamina: la revisione può
richiedere fino a 24 ore
(Meta, Template fundamentals).
Il verdetto arriva ai tuoi webhook (template.status_changed) e a
GET /api/v1/templates/{id}. Una campagna parte solo con un modello approved.
Ogni variabile del corpo ({{1}}, {{2}}…) richiede un esempio, altrimenti il modello viene
rifiutato. Il riferimento API tratta header media, parametri con nome e
pulsanti.
Come creo e lancio la campagna?
Crea la campagna
POST /api/v1/campaigns accetta quattro campi, tutti obbligatori: connectionId, templateId,
name e recipients. Ogni destinatario porta il suo numero in formato internazionale (+ e
prefisso del paese) e le proprie variables. La campagna viene creata come draft: non viene
ancora inviato nulla.
Lanciala
POST /api/v1/campaigns/{id}/launch invia a tutti i destinatari ancora pending e risponde con il
conteggio: sent, failed, skipped. sent significa che Meta ha accettato il messaggio, non che
è arrivato: consegna e lettura arrivano dopo, via webhook.
Segui gli stati
Leggi i contatori su GET /api/v1/campaigns/{id} e il dettaglio per destinatario su
GET /api/v1/campaigns/{id}/recipients. La sezione sul tracciamento più sotto li tratta entrambi.
# 1. Crea la campagna (bozza)
curl -X POST https://wa.genuka.com/api/v1/campaigns \
-H "Authorization: Bearer $GENUKA_WA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"connectionId": "con_1",
"templateId": "tpl_123",
"name": "October sale",
"recipients": [
{ "to": "+237690000001", "variables": ["Awa"] },
{ "to": "+237690000002", "variables": ["Paul"] }
]
}'
# { "data": { "id": "cmp_9", "name": "October sale", "status": "draft", "_count": { "recipients": 2 } } }
# 2. Lanciala
curl -X POST https://wa.genuka.com/api/v1/campaigns/cmp_9/launch \
-H "Authorization: Bearer $GENUKA_WA_API_KEY"
# { "data": { "sent": 2, "failed": 0, "skipped": 0 } }variables è un array posizionale per i parametri del corpo. Per un header media, un pulsante
dinamico o parametri con nome, passa invece un oggetto:
{ "body": [...], "bodyNamed": { "first_name": "Awa" }, "header": {...}, "buttons": [...] }, la
stessa forma dell'invio di un modello. I valori di un modello con parametri
con nome vanno in bodyNamed: messi in body, verrebbero inviati come parametri posizionali.
Perché il lancio viene rifiutato?
Questi controlli vengono eseguiti prima del primo invio: un lancio rifiutato non ha inviato nulla. I rifiuti più comuni:
| Stato | Codice | Causa |
|---|---|---|
402 | plan_limit_messages | L'elenco non rientra in ciò che resta della quota del periodo. Conta ogni destinatario pending, compresi quelli esclusi poi per opt-out |
402 | subscription_past_due | La prova o il periodo pagato è scaduto |
400 | send_template | Il modello non è approved (in revisione, rifiutato, in pausa): il messaggio dice quale |
409 | send_config | Il numero è stato scollegato dall'API nell'app WhatsApp Business (coesistenza): ricollegalo |
409 | number_released | Il numero è stato rilasciato dal tuo piano: ricollegalo tramite l'Embedded Signup |
403 | account_deactivated | Il cliente a cui appartiene il numero è sospeso |
404 | campaign_not_found | L'id non esiste o è fuori dall'ambito della tua chiave |
Alla creazione, un templateId e un connectionId appartenenti a due clienti diversi rispondono
400 template_connection_mismatch, e un elenco senza un solo to utilizzabile risponde
400 no_valid_recipients. Gli altri codici sono nel riferimento degli errori.
Quanti messaggi può inviare una campagna?
Genuka non addebita mai un messaggio; Meta invece addebita le proprie tariffe per messaggio direttamente al tuo WABA, senza ricarico da parte di Genuka. Il tuo piano include una quota di messaggi in uscita per numero pagato e per periodo di fatturazione (tariffe di Meta escluse), condivisa tra invii via API e destinatari delle campagne. La quota del periodo è: numeri pagati × la quota per numero del livello. Il contatore riparte da zero a ogni nuovo periodo: ogni mese con un abbonamento mensile, al rinnovo con uno annuale.
| Livello | Numeri max | Messaggi inclusi per numero per periodo |
|---|---|---|
| Starter | 5 | 500 |
| Growth | 15 | 5.000 |
| Scale | 100 | 30.000 |
| Enterprise | su misura | su misura |
Esempio: 3 numeri su Growth danno 15.000 messaggi per il periodo. La prova gratuita di 7 giorni gira
sul livello Growth con un numero, quindi 5.000 messaggi. Vengono contati solo i messaggi accettati
da Meta: un invio che Meta rifiuta sulla chiamata non consuma nulla, ma un messaggio accettato e poi
segnalato come failed via webhook resta conteggiato. I prezzi sono sulla
pagina dei prezzi e in Markdown su /pricing.md.
Quali limiti pone Meta alle campagne marketing?
La quota di Genuka non è l'unico tetto. Meta ne applica quattro propri, qualunque sia il tuo piano:
| Limite di Meta | Cosa dice | Cosa vedi |
|---|---|---|
| Limite di messaggi | Destinatari unici che puoi raggiungere fuori da una finestra del servizio clienti, su 24 ore mobili, a livello di portafoglio aziendale: 250 per un nuovo portafoglio, poi 2,000, 10,000, 100,000, illimitati (documentazione) | WhatsApp Manager, Account tools > Messaging limits (stessa pagina). Il messagingLimitTier di GET /api/v1/numbers?refresh=true è solo indicativo: proviene da un campo che Meta ha deprecato e può essere vuoto |
| Limite marketing per utente | WhatsApp può non consegnare un modello marketing a chi ne riceve molti e ne legge pochi. Attendi almeno 24 ore prima di reinviare (documentazione) | Errore 131049 sul webhook di stato, destinatario failed |
| Numeri statunitensi | WhatsApp al momento non consegna modelli marketing ai numeri di telefono degli Stati Uniti (stessa pagina) | Il destinatario fallisce |
| Throughput | 80 messaggi al secondo per numero per impostazione predefinita, 20 per un numero in coesistenza (throughput, coexistence) | Il lancio si adegua a questo ritmo |
Il limite marketing per utente non è attualmente attivo per i messaggi inviati da o verso lo Spazio economico europeo, il Regno Unito, il Giappone e la Corea del Sud (stessa pagina di Meta).
I modelli MARKETING di una campagna vengono prima proposti alla
Marketing Messages API
di Meta; se il tuo account non vi ha accesso, l'invio ripiega sull'endpoint classico senza fermare
la campagna.
Quanto costa una campagna lato Meta?
Meta addebita per messaggio consegnato, alla tariffa della categoria del modello e del prefisso internazionale del destinatario, sul tuo portafoglio aziendale (Meta, Pricing). Genuka non aggiunge ricarichi e non gestisce mai quel pagamento.
Mi serve l'opt-in per una campagna WhatsApp?
Sì. La policy di WhatsApp Business ti consente di contattare solo chi ti ha dato il suo numero e ha confermato di voler ricevere i tuoi messaggi (WhatsApp Business Messaging Policy). Meta aggiunge che la richiesta deve nominare la tua azienda e indicare chiaramente a cosa la persona sta dando il consenso, tramite qualsiasi canale tu preferisca: sito web, SMS, modulo cartaceo (Meta, Get opt-in). Una qualità che resta bassa per un periodo prolungato porta Meta a limitare la frequenza di invio del numero (stessa pagina).
Genuka applica per te gli opt-out marketing sulle campagne:
- Quando un utente blocca i messaggi marketing da dentro WhatsApp, Meta lo annuncia via webhook e
Genuka lo registra. Viene registrato anche un invio rifiutato con
131050("this recipient has chosen to stop receiving marketing messages"). - Quando parte una campagna
MARKETING, quei contatti vengono esclusi prima di qualsiasi invio e marcatiskipped, con il motivo. Non consumano né quota né fatturazione Meta. - Le campagne
UTILITYeAUTHENTICATIONnon vengono filtrate: non sono messaggi marketing.
Una tua parola chiave ("rispondi STOP") non viene interpretata automaticamente: le risposte ti
arrivano su message.received, e togliere quei contatti dai tuoi elenchi spetta a te.
Come seguo i risultati di una campagna?
GET /api/v1/campaigns/{id} restituisce la campagna, il suo modello, il suo numero e un oggetto
stats che conta i destinatari per stato:
{
"data": {
"id": "cmp_9",
"name": "October sale",
"status": "completed",
"template": { "id": "tpl_123", "name": "october_sale", "language": "en_US", "status": "approved" },
"_count": { "recipients": 1200 },
"stats": { "read": 640, "delivered": 410, "sent": 95, "failed": 41, "skipped": 14 }
}
}Ogni destinatario è contato una volta, sotto il suo stato più avanzato: un messaggio letto sta in
read, non in delivered. Il tasso di consegna si legge quindi (delivered + read) / (total − skipped).
| Stato | Significato |
|---|---|
pending | Non ancora inviato |
sent | Accettato da Meta |
delivered | Arrivato sul telefono |
read | Letto: solo se il destinatario ha le conferme di lettura attive |
failed | Rifiutato, con il motivo di Meta in errorMessage |
skipped | Escluso al lancio: ha fatto opt-out dal marketing |
Per gli errori, GET /api/v1/campaigns/{id}/recipients?status=failed&limit=1000 elenca ogni
destinatario con errorMessage, sentAt, deliveredAt, readAt e failedAt (200 righe per
impostazione predefinita, 1.000 al massimo). In tempo reale, iscrivi un endpoint a
message.delivered, message.read, message.failed e user_preference.stopped: vedi
Webhook.
Come reinvio ai destinatari bloccati dal limite marketing?
Il limite marketing per utente si manifesta dopo l'invio: Meta accetta il messaggio, poi il webhook
di stato torna failed con l'errore 131049
(Meta, Per-user limits).
Il destinatario passa a failed, con il testo di Meta in errorMessage (Meta descrive questo
errore come "This message was not delivered to maintain healthy ecosystem engagement"). Chiamare di
nuovo launch non li reinvia: riprende solo i destinatari pending.
Per riprovare con quelle persone, attendi almeno 24 ore, elenca
GET /api/v1/campaigns/{id}/recipients?status=failed, tieni quelli con quel motivo (o il codice
131049 ricevuto su message.failed) e crea con loro una nuova campagna. Nel caso più raro in cui
Meta rifiuta l'invio stesso con 131049, il destinatario resta pending, e chiamare di nuovo
launch 24 ore dopo lo riprende.
Limiti attuali
- Il lancio è sincrono e limitato nel tempo. La chiamata scorre l'elenco un destinatario dopo
l'altro: ogni invio attende la risposta di Meta, poi il salvataggio del suo stato, quindi il ritmo
reale resta ben al di sotto del tetto del numero. Dopo circa 2 minuti, la CDN davanti all'API
risponde
524(una pagina di errore, non JSON) mentre l'invio prosegue lato server (Cloudflare, error 524). Tieni le campagne a qualche centinaio di destinatari e dividi un pubblico ampio in più campagne. - Dopo un
524, segui la campagna invece di rilanciarla. InterrogaGET /api/v1/campaigns/{id}finchéstatusnon è piùrunning. Non chiamare mailaunchsu una campagnarunning: oggi nulla lo impedisce, e due esecuzioni in parallelo invierebbero il messaggio due volte ai destinatari che la prima esecuzione non ha ancora raggiunto. - Un'esecuzione che dura troppo viene interrotta. Il server non lascia girare una chiamata
all'infinito. Se la campagna è ancora
running15 minuti dopo la chiamata, l'esecuzione è stata interrotta: i destinatari ancorapendingnon sono stati inviati, e chiamare di nuovolaunchli riprende. - Nessuna pianificazione. Non c'è un campo data: chiama
launchquando vuoi che parta, da un tuo job pianificato.
E se voglio un'interfaccia invece di un'API?
Genuka WA non ha una console per le campagne: /api/v1/campaigns è una primitiva di integrazione
(modello + destinatari + stati). Se vuoi segmentare una base clienti e lanciare campagne senza
scrivere codice, Genuka Core, la piattaforma gestionale di Genuka, lo fa:
categorizza i tuoi clienti, analizza il loro comportamento d'acquisto e lancia campagne mirate su
WhatsApp, SMS ed email.
FAQ
Posso inviare una campagna a contatti che non mi hanno mai scritto?
Sì, con un modello approvato e il loro opt-in. È proprio a questo che serve un modello: è l'unico messaggio consegnato fuori dalla finestra di 24 ore. A questi invii si applica il limite di messaggi di Meta (250 destinatari unici ogni 24 ore per un nuovo portafoglio).
Quanto costa una campagna WhatsApp con Genuka WA?
Due voci separate. Meta fattura ogni modello consegnato al tuo portafoglio aziendale, per categoria e paese del destinatario. Genuka addebita un abbonamento per numero WhatsApp, con una quota di messaggi inclusa, e non applica ricarichi sulle tariffe di Meta.
Cosa succede se un destinatario ha fatto opt-out?
In una campagna MARKETING, viene escluso prima dell'invio e marcato skipped. Non usa la tua
quota e Meta non ti addebita nulla per lui.
Perché sent è alto ma delivered è basso?
sent significa solo che Meta ha accettato il messaggio. Le conferme di consegna seguono via
webhook; se non arrivano, guarda failed e gli errori 131049 (limite marketing) o 131026
(destinatario non raggiungibile).
Posso lanciare di nuovo la stessa campagna?
Sì, una volta che non è più running (completed o failed): launch invia allora solo i
destinatari ancora pending, mai un messaggio già partito. Non rilanciarla mentre è running,
nemmeno dopo un 524: aspetta che esca da quello stato, o 15 minuti se ci resta (vedi i limiti più
sopra).
Fonti
- Meta — Messaging limits
- Meta — Per-user marketing template message limits
- Meta — Throughput
- Meta — Pricing on the WhatsApp Business Platform
- Meta — Get opt-in for WhatsApp
- Meta — Template fundamentals
- Meta — Marketing Messages API: get started
- Meta — Partners (Tech Providers and Solution Partners)
- Meta — Error codes
- Meta — Onboard WhatsApp Business app users
- WhatsApp — Business Messaging Policy
- Cloudflare — Error 524: a timeout occurred
- Genuka — genuka.com
Notifiche d'ordine WhatsApp dal tuo backend
Invia da WhatsApp conferme d'ordine, aggiornamenti di spedizione e di consegna dal tuo backend: modelli di utilità, variabili, idempotenza e stati di consegna.
Ricevere risposte e stati WhatsApp via webhook
Ricevi sul tuo server le risposte WhatsApp e gli stati di consegna: registra un webhook, verifica la firma HMAC, deduplica, gestisci i nuovi tentativi e il replay.