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 inexample.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.