Genuka WA docs

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:

POST /api/v1/templates
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:

StatoCodiceCausa
402plan_limit_messagesL'elenco non rientra in ciò che resta della quota del periodo. Conta ogni destinatario pending, compresi quelli esclusi poi per opt-out
402subscription_past_dueLa prova o il periodo pagato è scaduto
400send_templateIl modello non è approved (in revisione, rifiutato, in pausa): il messaggio dice quale
409send_configIl numero è stato scollegato dall'API nell'app WhatsApp Business (coesistenza): ricollegalo
409number_releasedIl numero è stato rilasciato dal tuo piano: ricollegalo tramite l'Embedded Signup
403account_deactivatedIl cliente a cui appartiene il numero è sospeso
404campaign_not_foundL'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.

LivelloNumeri maxMessaggi inclusi per numero per periodo
Starter5500
Growth155.000
Scale10030.000
Enterprisesu misurasu 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 MetaCosa diceCosa vedi
Limite di messaggiDestinatari 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 utenteWhatsApp 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 statunitensiWhatsApp al momento non consegna modelli marketing ai numeri di telefono degli Stati Uniti (stessa pagina)Il destinatario fallisce
Throughput80 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 marcati skipped, con il motivo. Non consumano né quota né fatturazione Meta.
  • Le campagne UTILITY e AUTHENTICATION non 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:

GET /api/v1/campaigns/cmp_9
{
  "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).

StatoSignificato
pendingNon ancora inviato
sentAccettato da Meta
deliveredArrivato sul telefono
readLetto: solo se il destinatario ha le conferme di lettura attive
failedRifiutato, con il motivo di Meta in errorMessage
skippedEscluso 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. Interroga GET /api/v1/campaigns/{id} finché status non è più running. Non chiamare mai launch su una campagna running: 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 running 15 minuti dopo la chiamata, l'esecuzione è stata interrotta: i destinatari ancora pending non sono stati inviati, e chiamare di nuovo launch li riprende.
  • Nessuna pianificazione. Non c'è un campo data: chiama launch quando 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

In questa pagina