I prezzi basati sulle conversazioni sono cambiati. Consulta Prezzi per capire come funziona il nostro nuovo modello di prezzi basati sulle conversazioni.
Inoltre, è cambiata la visibilità di metric_types a partire dal 1 luglio 2023. Per maggiori dettagli consulta la tabella Dati statistici sulle conversazioni.
Modelli di messaggi
I modelli di messaggi di WhatsApp sono formati di messaggi specifici usati dalle aziende per inviare notifiche o messaggi di assistenza clienti alle persone che hanno attivato la ricezione di notifiche. I messaggi possono includere promemoria per appuntamenti, informazioni di spedizione, risoluzioni di problemi o aggiornamenti sui pagamenti.
Prima di inviare un modello di messaggio, devi crearne uno. Per maggiori informazioni, consulta Creazione di modelli di messaggi per l'account WhatsApp Business. Se il tuo account non è ancora verificato, puoi usare uno dei nostri modelli preapprovati.
Attualmente puoi inviare i tipi di modello seguenti:
Tutte le chiamate API menzionate in questa guida devono essere autenticate con un token d'accesso. Gli sviluppatori possono autenticare le proprie chiamate API con il token d'accesso generato in Dashboard gestione app > WhatsApp > scheda Configurazione API. I Solution Partner devono autenticarsi con un token d'accesso con l'autorizzazione whatsapp_business_messaging.
Distribuzione
I modelli di marketing appena creati o non in pausa sono soggetti alla distribuzione dei modelli. Consulta Distribuzione dei modelli.
Modelli di messaggi basati su testo
Per inviare un modello di messaggio basato su testo, effettua una chiamata POST a /PHONE_NUMBER_ID/messages e allega un oggetto message con type=template. Quindi, aggiungi un oggetto template.
Esempio di richiesta:
curl -X POST \
'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/messages' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "PHONE_NUMBER",
"type": "template",
"template": {
"name": "TEMPLATE_NAME",
"language": {
"code": "LANGUAGE_AND_LOCALE_CODE"
},
"components": [
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "text-string"
},
{
"type": "currency",
"currency": {
"fallback_value": "VALUE",
"code": "USD",
"amount_1000": NUMBER
}
},
{
"type": "date_time",
"date_time": {
"fallback_value": "DATE"
}
}
]
}
]
}
}'
Una risposta positiva include un oggetto con un identificativo preceduto da wamid. Usa l'ID riportato dopo wamid per monitorare lo stato del messaggio.
{
"messaging_product": "whatsapp",
"contacts": [{
"input": "PHONE_NUMBER",
"wa_id": "WHATSAPP_ID",
}]
"messages": [{
"id": "wamid.ID",
}]
}
Modelli di messaggi basati su contenuto multimediale
Per inviare un modello di messaggio basato su contenuto multimediale, effettua una chiamata POST a /PHONE_NUMBER_ID/messages e allega un oggetto message con type=template. Quindi, aggiungi un oggetto template. Supporta la memorizzazione nella cache HTTP di contenuti multimediali.
Usa l'endpoint WhatsApp Business Phone Number > Messages POST per inviare un messaggio basato su contenuto multimediale. Imposta la proprietà type su template e usa la proprietà template per definire il tuo oggetto template e il relativo oggetto media.
Al momento della definizione dell'oggetto media, puoi caricare la tua risorsa multimediale sui nostri server e utilizzare il relativo ID del contenuto multimediale (usando la proprietà id) oppure ospitare la risorsa sul tuo server e utilizzare il relativo URL (usando la proprietà link). Se usi link, la tua risorsa deve trovarsi su un server accessibile pubblicamente; in caso contrario, il messaggio non verrà inviato.
Per ridurre la probabilità di errori ed evitare richieste non necessarie al tuo server pubblico, ti consigliamo di caricare le tue risorse multimediali e di usare i loro ID quando invii messaggi.
Le risorse multimediali possono anche essere memorizzate nella cache. Consulta Memorizzazione nella cache di HTTP di contenuti multimediali.
Esempio di richiesta:
curl -X POST \
'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/messages' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "PHONE_NUMBER",
"type": "template",
"template": {
"name": "TEMPLATE_NAME",
"language": {
"code": "LANGUAGE_AND_LOCALE_CODE"
},
"components": [
{
"type": "header",
"parameters": [
{
"type": "image",
"image": {
"link": "https://URL"
}
}
]
},
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "TEXT-STRING"
},
{
"type": "currency",
"currency": {
"fallback_value": "VALUE",
"code": "USD",
"amount_1000": NUMBER
}
},
{
"type": "date_time",
"date_time": {
"fallback_value": "MONTH DAY, YEAR"
}
}
]
}
]
}
}'
Una risposta positiva include un oggetto con un identificativo preceduto da wamid. Usa l'ID riportato dopo wamid per monitorare lo stato del messaggio.
{
"messaging_product": "whatsapp",
"contacts": [{
"input": "PHONE_NUMBER",
"wa_id": "WHATSAPP_ID",
}]
"messages": [{
"id": "wamid.ID",
}]
}
Modelli di messaggi interattivi
I modelli di messaggi interattivi ampliano il contenuto che puoi inviare ai destinatari oltre al modello di messaggio standard e ai tipi di modelli di messaggi multimediali, consentendo di includere pulsanti interattivi utilizzando l'oggetto components. Esistono due tipi di pulsanti predefiniti:
- Call to action: consente al cliente di chiamare un numero di telefono e visitare un sito web.
- Risposta rapida: consente al cliente di rispondere con un semplice messaggio di testo.
Questi pulsanti possono essere aggiunti ai messaggi di testo o ai messaggi con contenuto multimediale. Dopo aver creato e approvato i modelli di messaggi interattivi, puoi utilizzarli nei messaggi di notifica e in quelli dell'assistenza clienti.
Per inviare un modello di messaggio interattivo, effettua una chiamata POST a /PHONE_NUMBER_ID/messages e allega un oggetto message con type=template. Quindi aggiungi un oggetto template con il button scelto.
Esempio di richiesta:
curl -X POST \
'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/messages' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "PHONE_NUMBER",
"type": "template",
"template": {
"name": "TEMPLATE_NAME",
"language": {
"code": "LANGUAGE_AND_LOCALE_CODE"
},
"components": [
{
"type": "header",
"parameters": [
{
"type": "image",
"image": {
"link": "http(s)://URL"
}
}
]
},
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "TEXT_STRING"
},
{
"type": "currency",
"currency": {
"fallback_value": "VALUE",
"code": "USD",
"amount_1000": NUMBER
}
},
{
"type": "date_time",
"date_time": {
"fallback_value": "MONTH DAY, YEAR"
}
}
]
},
{
"type": "button",
"sub_type": "quick_reply",
"index": "0",
"parameters": [
{
"type": "payload",
"payload": "PAYLOAD"
}
]
},
{
"type": "button",
"sub_type": "quick_reply",
"index": "1",
"parameters": [
{
"type": "payload",
"payload": "PAYLOAD"
}
]
}
]
}
}'
Una risposta positiva include un oggetto con un identificativo preceduto da wamid. Usa l'ID riportato dopo wamid per monitorare lo stato del messaggio.
{
"messaging_product": "whatsapp",
"contacts": [{
"input": "PHONE_NUMBER",
"wa_id": "WHATSAPP_ID",
}]
"messages": [{
"id": "wamid.ID",
}]
}
Modelli di messaggi basati sulla posizione
Per inviare un modello che utilizzi un'intestazione della posizione, la tua richiesta deve includere un oggetto location header.
Sintassi
{
"type": "header",
"parameters": [
{
"type": "location",
"location": {
"latitude": "<LATITUDE>",
"longitude": "<LONGITUDE>",
"name": "<NAME>",
"address": "<ADDRESS>"
}
}
]
}Proprietà
| Segnaposto | Descrizione | Valore di esempio |
|---|---|---|
| Indirizzo che verrà visualizzato dopo il valore |
|
| Latitudine della posizione. |
|
| Longitudine della posizione. |
|
| Il testo che verrà visualizzato subito al di sotto della mappa generica nella parte superiore del messaggio. |
|
Esempio di richiesta
Questa è una richiesta di esempio per inviare un modello esistente che utilizzi i seguenti componenti:
- Un'intestazione della posizione
- Un corpo di testo con una variabile
- Un piè di pagina
- Un pulsante di risposta rapida
curl -L 'https://graph.facebook.com/v16.0/106540352242922/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "12245554792",
"type": "template",
"template": {
"name": "order_delivery_update",
"language": {
"code": "en_US"
},
"components": [
{
"type": "header",
"parameters": [
{
"type": "location",
"location": {
"latitude": "37.483307",
"longitude": "122.148981",
"name": "Pablo Morales",
"address": "1 Hacker Way, Menlo Park, CA 94025"
}
}
]
},
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "Pablo"
},
{
"type": "text",
"text": "566701"
}
]
}
]
}
}'Modelli di autenticazione
Il tentativo di inviare modelli di autenticazione precedenti (modelli senza pulsanti per password monouso) restituirà il codice di errore 100 se i valori variabili superano 15 caratteri o contengono link o emoji oppure se il componente body del modello contiene un link. Crea e usa invece un modello di autenticazione che abbia un pulsante per password monouso.
Consulta Modelli di autenticazione e Invio di modelli di autenticazione.
Sequenza di consegna di più messaggi
Quando invii una serie di messaggi, non è garantito che l'ordine in cui questi vengono consegnati corrisponda all'ordine delle tue richieste API. Per verificare la sequenza di consegna dei messaggi, conferma la ricezione di uno stato delivered in un webhook dei messaggi prima di inviare il messaggio successivo della sequenza.
Limiti di messaggi per modelli di marketing per utente
A partire dal 6 febbraio 2024, i limiti di messaggi per modelli di marketing per utente si applicano ai modelli di messaggi inviati a un numero ridotto di utenti di WhatsApp in India, ma si applicheranno a tutti gli utenti di WhatsApp con un numero di telefono indiano entro il 13 febbraio 2024.
Stiamo implementando nuovi approcci, a partire dai consumatori in India, per creare esperienze utente di alta qualità e massimizzare le interazioni registrate con i messaggi di marketing. Ciò può includere la limitazione del numero di messaggi per modelli di marketing che una persona riceve da un'azienda in un determinato arco di tempo, a partire da un numero ridotto di conversazioni che hanno meno probabilità di essere lette. Tieni presente che il limite è determinato sulla base del numero di messaggi per modelli di marketing che la persona ha già ricevuto da qualsiasi azienda e non è correlato alla tua azienda in modo specifico.
Il limite si applica solo ai modelli di messaggi di marketing che normalmente aprirebbero una nuova conversazione di marketing. Se è già aperta una conversazione di marketing tra te e un utente di WhatsApp, i messaggi di marketing inviati all'utente non saranno interessati.
Se un messaggio di marketing non viene consegnato a un determinato utente a causa del limite, l'API Cloud restituirà il codice di errore 131026 e l'API On-Premises restituirà il codice di errore 1026. Considera, però, che questi codici di errore coprono un'ampia gamma di problemi che possono comportare la mancata consegna di un messaggio e, per motivi di privacy, non divulgheremo se il messaggio non è stato consegnato a causa del limite. Fai riferimento al documento Risoluzione dei problemi dell'API Cloud e alla FAQ "Perché la mia percentuale di consegna non è del 100%?" per una descrizione dei motivi di mancata consegna e di indicazioni su cosa fare per determinarne la causa scatenante.
Se ricevi uno di questi codici di errore e sospetti che sia dovuto al limite, evita di reinviare immediatamente il messaggio perché riceveresti solo un altro errore. Invece, prova ad aumentare gradualmente gli incrementi di tempo fino alla consegna del messaggio poiché il limite potrebbe applicarsi a diversi intervalli temporali.
Continueremo a perfezionare il nostro approccio grazie anche alla tua collaborazione nel rendere WhatsApp la migliore esperienza possibile per la tua azienda e i tuoi clienti.
Risoluzione dei problemi
Se stai riscontrando problemi con la consegna dei messaggi, consulta Messaggio non consegnato.