De Palma Labs, distributore per l'Italia della piattaforma AYROMEX, Meta Tech Provider

Template

Per scrivere a un destinatario fuori dalla finestra di 24 ore serve un template approvato da Meta. I template appartengono all'account WhatsApp del cliente: ogni cliente ha i suoi.

Creare un template

curl -X POST https://api.depalmalabs.it/v1/customers/cus_xxxxxxxxxxxx/templates \
  -H "Authorization: Bearer $DPL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "promemoria_appuntamento",
    "language": "it",
    "category": "UTILITY",
    "components": [{
      "type": "BODY",
      "text": "Ciao {{1}}, ti ricordiamo l'\''appuntamento di {{2}}. A presto!",
      "example": { "body_text": [["Maria", "domani alle 10:00"]] }
    }]
  }'

Lo stato iniziale è PENDING; l'esito (di solito entro pochi minuti, a volte fino a 24 ore) arriva con l'evento template.status. Con chiave sandbox il template è solo locale e risulta subito APPROVED.

Categorie

  • UTILITY: aggiornamenti legati a qualcosa che il destinatario ha fatto o chiesto (appuntamento, ordine, fattura).
  • MARKETING: promozioni, offerte, newsletter. Vanno in pausa automatica se la qualità del numero scende a RED.
  • AUTHENTICATION: codici monouso. Testo fisso definito da Meta, con pulsante per copiare il codice.

Meta può riclassificare un template (per esempio da UTILITY a MARKETING) se il contenuto è promozionale: il prezzo segue la categoria finale. La riclassificazione arriva con l'evento template.status, anche se lo stato non cambia: confronta category con previous_category.

Regole che evitano il rifiuto

  • Nome in minuscolo con underscore (conferma_ordine), unico per lingua.
  • Variabili numerate in ordine da {{1}}, con un esempio per ciascuna in example.body_text.
  • Il corpo non può iniziare o finire con una variabile, né avere due variabili attaccate.
  • Niente contenuti vietati dalle policy di Meta (vedi la nostra policy d'uso).

Marketing e Marketing Messages API

Meta sposta i messaggi marketing sulla Marketing Messages API: sulla Cloud API restano supportati fino al 13 ottobre 2027 (comunicazione di Meta agli sviluppatori del 13 ottobre 2026). Utility, autenticazione e servizio non cambiano.

Non devi cambiare nulla: con lo stesso POST /v1/messages la piattaforma manda i template MARKETING sulla Marketing Messages API e tutto il resto sulla Cloud API, anche quando Meta riclassifica un template. Finché il business del cliente non ha accettato i termini della Marketing Messages API, Meta consegna i marketing tramite la Cloud API.

Lo stato dei termini è nel campo marketing_terms del cliente; il percorso effettivo di ogni messaggio è nel campo route (mm_api o cloud_api) del messaggio e dell'evento message.status. I termini li accetta un amministratore dell'account Meta del cliente in WhatsApp Manager: le istruzioni sono nel dettaglio cliente della dashboard.

Inviare

Il modo più semplice è variables (corpo) e header_variables (intestazione testo). Per un'immagine nell'intestazione usa header_image: { link: "https://…" }. Per i pulsanti quick reply passa button_payloads: un valore per pulsante, nell'ordine del template; quando il cliente preme un pulsante il valore torna nel webhook message.received come button_payload. Per tutto il resto usa components nel formato Cloud API (in alternativa ai campi semplici): trovi gli esempi in Esempi pronti.

Pulsanti quick reply nel template: al massimo 10, testo da 1 a 25 caratteri. Un'intestazione IMAGE richiede l'immagine di esempio caricata su Meta in example.header_handle.

Intestazione con immagine

Carica l'immagine di esempio con POST /v1/customers/{id}/uploads (file in multipart o link https) e metti il header_handle restituito in example.header_handle del componente HEADER. Solo JPEG o PNG fino a 5 MB; in multipart conviene restare sotto i 4 MB, oltre usa il link. Con chiave sandbox l'handle è finto e vale solo per i template sandbox.

# Immagine di esempio per un template con intestazione IMAGE (JPEG o PNG, massimo 5 MB)
curl -X POST https://api.depalmalabs.it/v1/customers/cus_xxxxxxxxxxxx/uploads \
  -H "Authorization: Bearer $DPL_API_KEY" \
  -F "file=@promo-estate.jpg;type=image/jpeg"

# oppure da un link https pubblico
curl -X POST https://api.depalmalabs.it/v1/customers/cus_xxxxxxxxxxxx/uploads \
  -H "Authorization: Bearer $DPL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"link": "https://tuo-gestionale.it/immagini/promo-estate.jpg"}'

# Risposta
{ "object": "upload", "header_handle": "4::aW1hZ2UvanBlZw==:ARb...", "file_type": "image/jpeg", "file_length": 182044 }

# Nel template: { "type": "HEADER", "format": "IMAGE", "example": { "header_handle": ["4::aW1hZ2UvanBlZw==:ARb..."] } }

Messaggi con pulsanti senza template

Dentro le 24 ore dall'ultimo messaggio del cliente puoi mandare type: "interactive" con interactive: { body, buttons: [{ id, title }] } (da 1 a 3 pulsanti, titolo massimo 20 caratteri, id diversi; header e footer facoltativi). Fuori dalla finestra Meta lo rifiuta: serve un template. L'id del pulsante premuto arriva in message.received come button_payload.

Elencare e cancellare

GET /v1/customers/{id}/templates restituisce stato e motivo dell'eventuale rifiuto. DELETE /v1/customers/{id}/templates?name=…&language=it lo rimuove anche da Meta.