API Messaggi di marketing

L’API Messaggi di marketing (MM API) è l’endpoint di invio avanzato di Meta per i modelli di marketing WhatsApp. Si affianca alla Cloud API standard e attiva un insieme di funzionalità — Ottimizzazioni creative, tracciamento dei clic, TTL dei messaggi e metriche di conversione — non disponibili quando si invia tramite il normale endpoint POST /<phone_id>/messages.

Cloud API vs API Messaggi di marketing

Funzionalità	Cloud API	API Messaggi di marketing
Endpoint di invio	`POST /<phone_id>/messages`	`POST /<phone_id>/marketing_messages`
TTL del messaggio	Non configurabile	Da 12 ore a 30 giorni
Ottimizzazioni creative	No	Sì (+13,9% CTR medio)
Tracciamento clic	No	Sì
Metriche di conversione	No	Sì
Benchmark tasso di lettura	No	Sì
Categoria prezzi webhook	`marketing`	`marketing_lite`
Comportamento di fallback	—	`CLOUD_API_FALLBACK` o `STRICT`
Requisito di onboarding	Nessuno	ToS WABA firmati + `ONBOARDED`

Come attivarla

Firma i Termini di Servizio WABA

Vai su Meta Business Manager → Account WhatsApp → [il tuo WABA] → Impostazioni. Accetta i Termini di Servizio dei Messaggi di marketing se richiesto. Non puoi procedere senza questo passaggio.

Verifica lo stato di onboarding

In Switchbord, vai su Impostazioni → Canale. Il campo onboarding_status deve indicare ONBOARDED. Se mostra NOT_ONBOARDED o è assente, completa prima il flusso di onboarding di Meta.

Attiva in Switchbord

Vai su Impostazioni → Canale → API Messaggi di marketing e attiva l’opzione. Switchbord memorizza questa preferenza e instrada automaticamente gli invii di modelli di marketing idonei tramite l’endpoint della MM API.

TTL del messaggio

Il TTL (time-to-live) controlla per quanto tempo WhatsApp mantiene un messaggio in attesa di consegna prima di scartarlo. Il TTL predefinito della Cloud API è 30 giorni per tutti i messaggi. Con la MM API puoi impostarlo per singolo messaggio:

12 ore: vendite flash, promemoria per il giorno dell’evento — scarta se l’utente è offline troppo a lungo
7 giorni: newsletter settimanale, campagna standard
30 giorni: re-engagement, winback (come il valore predefinito della Cloud API)

Imposta ttl nel corpo della richiesta MM API (in secondi). Un valore di 43200 = 12 ore, 604800 = 7 giorni, 2592000 = 30 giorni.

POST /<PHONE_NUMBER_ID>/marketing_messages
{
  "messaging_product": "whatsapp",
  "to": "+393289214993",
  "ttl": 43200,
  "product_policy": "CLOUD_API_FALLBACK",
  "template": {
    "name": "summer_flash_sale",
    "language": { "code": "it" }
  }
}

Ottimizzazioni creative

Quando creative_optimizations è attivato nelle impostazioni del tuo canale, il sistema di consegna di Meta può adattare automaticamente i tempi di invio, la selezione della variante del testo o l’ordine dei bottoni per massimizzare l’engagement. Nei test interni di Meta questo ha aumentato il CTR medio del 13,9%. Le ottimizzazioni si applicano al momento della consegna e sono invisibili nel payload dell’API — invii lo stesso modello, Meta decide il rendering ottimale per ciascun destinatario.

Tracciamento clic e metriche di conversione

La MM API traccia automaticamente:

Clic sui link: tocchi sui bottoni URL nel modello
Conversioni: eventi di acquisto o prenotazione a valle (richiede l’integrazione di Meta Pixel o CAPI)
Tasso di lettura: percentuale di messaggi consegnati aperti entro 24 ore

Queste metriche appaiono in Meta Business Manager → WhatsApp Manager → Approfondimenti e sono disponibili anche tramite gli endpoint di reportistica della Graph API. Switchbord mostra un riepilogo del tasso di lettura nella pagina di dettaglio della campagna.

`product_policy`

Controlla cosa succede se il numero di telefono non è completamente onboarded per la MM API:

Valore	Comportamento
`CLOUD_API_FALLBACK`	Se la consegna tramite MM API fallisce per problemi di onboarding, il messaggio ricade automaticamente sull’invio standard della Cloud API. Nessun errore restituito al tuo server.
`STRICT`	Se la consegna tramite MM API non è disponibile, il messaggio fallisce con un errore. Usa questa opzione se devi garantire che le funzionalità della MM API (ad es. il TTL) vengano applicate.

`message_activity_sharing`

Controlla se le conferme di lettura per questo specifico messaggio vengono condivise con Meta per l’ottimizzazione della consegna. Il valore predefinito è true. Impostalo su false se il tuo spazio di lavoro ha una politica sulla privacy che vieta la condivisione dei segnali di engagement.

Limiti di consegna per utente

WhatsApp limita il numero di messaggi di marketing consegnati a utenti con basso engagement. Questo è indipendente dalla MM API — si applica a tutti i modelli di marketing indipendentemente dal percorso di invio.

Codici di errore

Codice	Significato	Azione
`131049`	Limite di marketing per utente raggiunto. Messaggio non consegnato.	Attendi almeno 24 ore prima di riprovare con questo utente.
`131050`	L’utente ha interrotto la ricezione di messaggi di marketing da questa azienda.	Aggiorna `subscriber_status = unsubscribed`. Non riprovare — questo è un opt-out permanente.
`131063`	I modelli di marketing sono disabilitati sulla Cloud API per questo numero di telefono.	Passa all’endpoint della MM API.

Limiti silenziosi

Se un messaggio non viene consegnato e non viene restituito nessun codice di errore, l’utente ha raggiunto il limite silenzioso per utente di WhatsApp. Monitora i tassi di lettura delle campagne — un calo improvviso senza errori di consegna è il segnale principale.

Esenzioni regionali

Le seguenti regioni sono esenti dai limiti di consegna marketing per utente:

Spazio Economico Europeo (SEE)
Regno Unito
Giappone
Corea del Sud

Numeri statunitensi

La consegna di modelli di marketing a numeri di telefono statunitensi (+1) è sospesa da aprile 2025. I modelli non verranno consegnati a numeri statunitensi né tramite Cloud API né tramite MM API finché Meta non revocherà la restrizione.

Targeting per tag del contatto

Per inviare solo a segmenti coinvolti, filtra i destinatari della campagna per tag prima dell’invio. Pattern di tag comuni:

Tag	Significato
`import:list-name`	Importato da un elenco specifico
`confirmed-2026`	Prenotazione confermata nel 2026
`futura-agency`	Contatto agenzia

Vedi Importazione contatti per come vengono assegnati i tag durante l’importazione in blocco.

Vedi anche

Configurare i messaggi di marketing — attivare la MM API passo dopo passo
Modelli di marketing — regole di categoria e requisiti di opt-out
Regole dei modelli — riferimento alle regole di validazione di Meta

Per iniziare

Funzionalità

WhatsApp

Guide

Contribuire

Piattaforma

Operazioni

Sicurezza e Conformità

API Messaggi di marketing

Cloud API vs API Messaggi di marketing

Come attivarla

TTL del messaggio

Ottimizzazioni creative

Tracciamento clic e metriche di conversione

`product_policy`

`message_activity_sharing`

Limiti di consegna per utente

Codici di errore

Limiti silenziosi

Esenzioni regionali

Numeri statunitensi

Targeting per tag del contatto

Vedi anche

​Cloud API vs API Messaggi di marketing

​Come attivarla

​TTL del messaggio

​Ottimizzazioni creative

​Tracciamento clic e metriche di conversione

​product_policy

​message_activity_sharing

​Limiti di consegna per utente

​Codici di errore

​Limiti silenziosi

​Esenzioni regionali

​Numeri statunitensi

​Targeting per tag del contatto

​Vedi anche

Cloud API vs API Messaggi di marketing

Come attivarla

TTL del messaggio

Ottimizzazioni creative

Tracciamento clic e metriche di conversione

`product_policy`

`message_activity_sharing`

Limiti di consegna per utente

Codici di errore

Limiti silenziosi

Esenzioni regionali

Numeri statunitensi

Targeting per tag del contatto

Vedi anche