Template WhatsApp

I template WhatsApp sono messaggi pre-approvati da Meta che possono essere inviati in qualsiasi momento, anche al di fuori della finestra 24h. Sono obbligatori per avviare una conversazione con un utente.

Endpoint

Metodo	Path	Descrizione
GET	/api/message-server/whatsapp/templates	Lista template
GET	/api/message-server/whatsapp/templates/{id}	Dettaglio template
POST	/api/message-server/whatsapp/templates?phoneNumberId={id}	Crea template
PATCH	/api/message-server/whatsapp/templates/{id}	Aggiorna template
DELETE	/api/message-server/whatsapp/templates/{id}	Elimina template

Il parametro query phoneNumberId nella creazione specifica a quale numero WhatsApp Business associare il template.

Campi creazione template

Campo	Tipo	Obb.	Descrizione
name	string	Sì	Nome template (snake_case, solo lettere minuscole, numeri e underscore)
lang	string	Sì	Codice lingua (es. it, en, es)
category	string	Sì	Categoria: MARKETING, UTILITY, AUTHENTICATION
body	string	Sì	Testo del corpo con placeholder {nomePlaceholder}
headerText	string	No	Testo header (esclusivo con headerFormat)
headerFormat	string	No	Formato media header: IMAGE, VIDEO, DOCUMENT
headerMediaUrl	string	No	URL media per l'header
footer	string	No	Testo del footer
buttons	array	No	Lista bottoni interattivi
placeholderFields	object	No	Definizione link tracciati
trackButtonLinks	boolean	No	Traccia click sui bottoni URL

Categorie

Categoria	Quando usarla	Esempi
MARKETING	Promozioni, offerte, newsletter	Saldi, nuovi prodotti, eventi
UTILITY	Comunicazioni transazionali	Conferma ordine, tracking, promemoria
AUTHENTICATION	Verifica identità	OTP, codici di verifica

Stati del template

Stato	Significato
APPROVED	Approvato da Meta, utilizzabile per l'invio
PENDING	In attesa di revisione da Meta
REJECTED	Rifiutato da Meta (verificare le linee guida)
PAUSED	Messo in pausa
DISABLED	Disabilitato

Bottoni

Campo	Tipo	Obb.	Descrizione
type	string	Sì	Tipo: URL, PHONE_NUMBER, QUICK_REPLY
text	string	Sì	Testo visualizzato
url	string	Solo URL	URL da aprire
phoneNumber	string	Solo PHONE_NUMBER	Numero da chiamare

Link tracciati

I link tracciati permettono di monitorare i click degli utenti.

Nel body del template

Inserisci il placeholder {shortLinkT1} nel testo e definisci l'URL reale in placeholderFields:

{
  "body": "Ciao {firstName}, clicca qui {shortLinkT1} per la tua offerta.",
  "placeholderFields": {
    "WHATSAPP": {
      "shortLinkT1": "https://example.com/offerta"
    }
  }
}

Nei bottoni

Aggiungi "trackButtonLinks": true alla richiesta:

{
  "buttons": [
    { "type": "URL", "text": "Apri offerta", "url": "https://example.com/offerta" }
  ],
  "trackButtonLinks": true
}

Esempi

Template semplice con testo

{
  "name": "marketing_Welcome",
  "lang": "it",
  "category": "MARKETING",
  "headerText": "Welcome",
  "body": "Ciao {firstName} siamo contentissimi di averti tra noi",
  "footer": "Per info visita il sito"
}

Template con bottoni

{
  "name": "marketing_Welcome",
  "lang": "it",
  "category": "MARKETING",
  "headerText": "Welcome",
  "body": "Ciao {firstName} siamo contentissimi di averti tra noi",
  "footer": "Per info visita il sito",
  "buttons": [
    { "type": "URL", "text": "Apri il sito", "url": "https://agiletelecom.com/" },
    { "type": "PHONE_NUMBER", "text": "Chiamaci", "phoneNumber": "+39 123123123" },
    { "type": "QUICK_REPLY", "text": "Voglio essere contattato" }
  ]
}

Template con header immagine

{
  "name": "marketing_Welcome",
  "lang": "it",
  "category": "MARKETING",
  "headerFormat": "IMAGE",
  "headerMediaUrl": "https://example.com/image.jpg",
  "body": "Ciao {firstName} siamo contentissimi di averti tra noi",
  "footer": "Per info visita il sito"
}

Template con link tracciato nel body

{
  "name": "marketing_Welcome",
  "lang": "it",
  "category": "MARKETING",
  "headerFormat": "IMAGE",
  "headerMediaUrl": "https://example.com/image.jpg",
  "body": "Ciao {firstName} siamo contentissimi di averti tra noi. Clicca qui {shortLinkT1} per accedere all'area riservata.",
  "footer": "Per info visita il sito",
  "placeholderFields": {
    "WHATSAPP": {
      "shortLinkT1": "https://www.example.com/landing-page"
    }
  }
}

Template con link tracciato nel bottone

{
  "name": "marketing_Welcome",
  "lang": "it",
  "category": "MARKETING",
  "headerFormat": "IMAGE",
  "headerMediaUrl": "https://example.com/image.jpg",
  "body": "Ciao {firstName} siamo contentissimi di averti tra noi.",
  "footer": "Per info visita il sito",
  "buttons": [
    { "type": "URL", "text": "Apri il sito", "url": "https://agiletelecom.com/" }
  ],
  "trackButtonLinks": true
}

Filtri lista template

Parametro	Descrizione
category	MARKETING, UTILITY, AUTHENTICATION
status	APPROVED, PENDING, REJECTED, PAUSED, DISABLED
phoneNumberId	Filtra per numero associato
page	Numero pagina (0-based)
limit	Elementi per pagina

Aggiornamento

Con PATCH /templates/{id} puoi aggiornare solo i campi che vuoi modificare. Il template tornerà in stato PENDING per la ri-approvazione da parte di Meta.