Questo documento è stato aggiornato.
La traduzione in Italiano non è ancora completa.

Aggiornamento inglese: 2 feb

Piattaforma WhatsApp Business > API Cloud > Riferimento

Messaggi

Usa l'endpoint /PHONE_NUMBER_ID/messages per inviare ai tuoi clienti messaggi con testo, contenuti multimediali, contatti, posizione e interattivi, nonché modelli di messaggi. Scopri di più sui messaggi che puoi inviare.

Endpoint	Autenticazione
`/PHONE_NUMBER_ID/messages` (Consulta Acquisizione dell'ID del numero di telefono)	Developers can authenticate their API calls with the access token generated in the App Dashboard > WhatsApp > API Setup. Solution Partners must authenticate themselves with an access token with the `whatsapp_business_messaging` permission.

I messaggi sono identificati da un ID univoco (WAMID). Puoi monitorare lo stato del messaggio nei webhook attraverso il suo WAMID. Puoi anche contrassegnare un messaggio in arrivo come letto tramite l'endpoint messages. Questo WAMID può avere una lunghezza massima di 128 caratteri.

Con l'API Cloud, non esiste più un modo per controllare esplicitamente se un numero di telefono dispone di un ID WhatsApp. Per inviare a qualcuno un messaggio utilizzando l'API Cloud, è sufficiente inviarlo direttamente al numero di telefono del cliente, dopo che quest'ultimo avrà autorizzato la ricezione di messaggi. Per gli esempi, consulta Riferimento, Messaggi.

Oggetto message

Per inviare un messaggio, devi prima preparare un oggetto message con il contenuto che desideri inviare. Questi sono i parametri usati in un oggetto message:

Nome	Descrizione (clicca sulla freccia nella colonna di sinistra per le opzioni supportate).
`audio` oggetto	Obbligatorio quando `type=audio`. Un oggetto `media` contenente audio.
`biz_opaque_callback_data` stringa	Facoltativo. Una stringa arbitraria, utile per il monitoraggio. Per esempio, puoi passare l'ID del modello di messaggio in questo campo per monitorare il percorso del cliente a partire dal primo messaggio che invii. Puoi poi monitorare il ROI di diversi tipi di modelli di messaggi per determinare il più efficace. Qualsiasi app iscritta al campo del webhook `messages` sull'account WhatsApp Business può ottenere questa stringa, poiché è inclusa nell'oggetto `statuses` all'interno dei payload del webhook. L'API Cloud non elabora questo campo, lo restituisce semplicemente come parte dei webhook di messaggio inviato/recapitato/letto. Massimo 512 caratteri. Solo API Cloud.
`contacts` oggetto	Obbligatorio quando `type=contacts`. Un oggetto `contacts`.
`context` oggetto	Obbligatorio se si risponde a qualsiasi messaggio nella conversazione. Un oggetto contenente l'ID di un messaggio precedente a cui si sta rispondendo. Ad esempio: `{"message_id":"MESSAGE_ID"}` Solo API Cloud.
`document` oggetto	Obbligatorio quando `type=document`. Un oggetto `media` contenente un documento.
`hsm` oggetto	Contiene un oggetto `hsm`. Questa opzione è stata dichiarata obsoleta con la `v2.39` dell'API On-Premises. Al suo posto usa l'oggetto `template`. Solo API On-Premises.
`image` oggetto	Obbligatorio quando `type=image`. Un oggetto `media` contenente un'immagine.
`interactive` oggetto	Obbligatorio quando `type=interactive`. Un oggetto `interactive`. I component di ciascun oggetto `interactive` seguono generalmente un pattern costante: `header`, `body`, `footer` e `action`.
`location` oggetto	Obbligatorio quando `type=location`. Un oggetto `location`.
`messaging_product` stringa	Obbligatorio Servizio di messaggistica utilizzato per la richiesta. Utilizza `"whatsapp"`. Solo API Cloud.
`preview_url` booleano	Obbligatorio se `type=text`. Consente anteprime URL nei messaggi di testo - Consulta Invio di URL nei messaggi di testo. Questo campo è facoltativo se non includi un URL nel tuo messaggio. Valori:`false` (predefinito), `true`. Solo API On-Premises. Gli utenti dell'API Cloud possono utilizzare la stessa funzionalità con il campo `preview_url` all'interno di un oggetto text.
`recipient_type` stringa	Facoltativo. Attualmente, puoi solo inviare messaggi a persone singole. Impostalo come `individual`. Predefinito: `individual`
`status` stringa	Stato del messaggio. Puoi usare questo campo per contrassegnare un messaggio come `read`. Consulta le guide seguenti per informazioni: API Cloud: Contrassegno dei messaggi come letti API On-Premises: Contrassegno dei messaggi come letti
`sticker` oggetto	Obbligatorio quando `type=sticker`. Un oggetto `media` contenente un adesivo. API Cloud: sono supportati adesivi animati e statici di terze parti in uscita e tutti i tipi di adesivi in entrata. Un adesivo statico deve essere di 512x512 pixel e non può superare 100 KB. Un adesivo animato deve essere di 512x512 pixel e non può superare 500 KB. API On-Premises: sono supportati solo adesivi statici di terze parti in uscita e tutti i tipi di adesivi in entrata. Un adesivo statico deve essere di 512x512 pixel e non può superare 100 KB. Gli adesivi animati non sono supportati.
`template` oggetto	Obbligatorio quando `type=template`. Un oggetto `template`.
`text` oggetto	Obbligatorio per i messaggi di testo. Un oggetto `text`.
`to` stringa	Obbligatorio. ID di WhatsApp o numero di telefono del cliente a cui si desidera inviare un messaggio. Consulta Formati dei numero di telefono. Se necessario, gli utenti dell'API On-Premises possono ottenere questo numero chiamando l'endpoint `contacts`..
`type` stringa	Facoltativo. Il tipo di messaggio che desideri inviare. Se omesso, il valore predefinito è `text`.

I seguenti oggetti sono annidati all'interno dell'oggetto message:

Oggetto text
Oggetto media
Oggetto reaction
Oggetto template
Oggetto location
Oggetto contacts
Oggetto interactive

Oggetto contacts

Name	Description
`addresses` object	Optional. Full contact address(es) formatted as an `addresses` object. The object can contain the following fields: `street`string – Optional. Street number and name. `city`string – Optional. City name. `state`string – Optional. State abbreviation. `zip`string – Optional. ZIP code. `country`string – Optional. Full country name. `country_code`string – Optional. Two-letter country abbreviation. `type`string – Optional. Standard values are `HOME` and `WORK`.
`birthday`	Optional. `YYYY-MM-DD` formatted string.
`emails` object	Optional. Contact email address(es) formatted as an `emails` object. The object can contain the following fields: `email`string – Optional. Email address. `type`string – Optional. Standard values are `HOME` and `WORK`.
`name` object	Required. Full contact name formatted as a `name` object. The object can contain the following fields: `formatted_name`string – Required. Full name, as it normally appears. `first_name`string – *Optional.** First name. `last_name`string – *Optional.** Last name. `middle_name`string – *Optional.** Middle name. `suffix`string – *Optional.** Name suffix. `prefix`string – *Optional.** Name prefix. *At least one of the optional parameters needs to be included along with the `formatted_name` parameter.
`org` object	Optional. Contact organization information formatted as an `org` object. The object can contain the following fields: `company`string – Optional. Name of the contact's company. `department`string – Optional. Name of the contact's department. `title`string – Optional. Contact's business title.
`phones` object	Optional. Contact phone number(s) formatted as a `phone` object. The object can contain the following fields: `phone`string – Optional. Automatically populated with the `wa_id` value as a formatted phone number. `type`string – Optional. Standard Values are `CELL`, `MAIN`, `IPHONE`, `HOME`, and `WORK`. `wa_id`string – Optional. WhatsApp ID.
`urls` object	Optional. Contact URL(s) formatted as a `urls` object. The object can contain the following fields: `url`string – Optional. URL. `type`string – Optional. Standard values are `HOME` and `WORK`.

Oggetto interactive

Nome	Descrizione
`action` oggetto	Obbligatorio. Azione che si desidera venga eseguita dall'utente dopo la lettura del messaggio.
`body` oggetto	Facoltativo per il tipo `product`. Obbligatorio per altri tipi di messaggio. Un oggetto con il corpo del messaggio. L'oggetto `body` contiene il campo seguente: `text`stringa – Obbligatorio se è presente il corpo. Il contenuto del messaggio. Sono supportati emoji e markdown. Lunghezza massima: 1024 caratteri.
`footer` oggetto	Facoltativo. Un oggetto con il piè di pagina del messaggio. L'oggetto `footer` contiene il campo seguente: `text`stringa – Obbligatorio se è presente il piè di pagina. Il contenuto del piè di pagina. Sono supportati emoji, markdown e link. Lunghezza massima: 60 caratteri.
`header` oggetto	Obbligatorio per il tipo `product_list`. Facoltativo per altri tipi. Contenuto dell'intestazione visualizzato nella parte superiore di un messaggio. Non puoi impostare un'intestazione se il tuo oggetto interactive è di tipo `product`. Consulta l'oggetto `header` per maggiori informazioni.
`type` oggetto	Obbligatorio. Il tipo di messaggio interattivo che desideri inviare. Valori supportati: `button`: usalo per i pulsanti di risposta. `catalog_message`: usalo per i messaggi con catalogo. `list`: usalo per i messaggi con lista. `product`: usalo per i messaggi con un prodotto. `product_list`: usalo per i messaggi con più prodotti. `flow`: usalo per i messaggi con flussi.

I seguenti oggetti sono annidati all'interno dell'oggetto interactive:

Oggetto action
Oggetto body
Oggetto footer
Oggetto header
Oggetto section

Oggetto action

Nome	Descrizione
`button` stringa	Obbligatorio per i messaggi con elenco. Contenuto del pulsante. Non può essere una stringa vuota e deve essere unica all'interno del messaggio. Emoji supportate, markdown non supportato. Lunghezza massima: 20 caratteri.
`buttons` array di oggetti	Obbligatorio per i pulsanti di risposta. Un oggetto button può contenere i seguenti parametri: `type`: l'unico tipo supportato è `reply` (per il pulsante di risposta) `title`: titolo del pulsante. Non può essere una stringa vuota e deve essere unica all'interno del messaggio. Emoji supportate, markdown non supportato. Lunghezza massima: 20 caratteri. `id`: identificativo unico per il pulsante. Questo ID viene restituito nel webhook quando l'utente clicca sul pulsante. Lunghezza massima: 256 caratteri. Puoi avere fino a 3 pulsanti. Quando imposti l'ID, non devono esserci spazi iniziali o finali.
`catalog_id` stringa	Obbligatorio per i messaggi con uno o più prodotti. Identificativo unico del catalogo di Facebook collegato al tuo account WhatsApp Business. Questo ID può essere recuperato tramite il Gestore delle vendite di Meta.
`product_retailer_id` stringa	Obbligatorio per i messaggi con uno o più prodotti. Identificativo unico del prodotto in un catalogo. Per ottenere questo ID, accedi al Gestore delle vendite di Meta e seleziona il tuo account business di Meta. Vedrai una lista di shop collegati al tuo account. Clicca sullo shop che vuoi usare. Nella scheda a sinistra, clicca su Catalogo > Articoli e trova l'articolo che vuoi menzionare. L'ID è visualizzato sotto il nome dell'articolo.
`sections` array di oggetti	Obbligatorio per i messaggi con lista e i messaggi con più prodotti. Array di oggetti `section`. Minimo 1, massimo 10. Vedi l'oggetto `section`.
`mode` stringa	Opzionale per i messaggi con flussi. La modalità attuale del flusso, `draft` o `published`. Predefinito: `published`
`flow_message_version` stringa	Obbligatorio per i messaggi con flussi. Deve essere `3`.
`flow_token` stringa	Obbligatorio per i messaggi con flussi. Un token che viene generato dall'azienda per essere usato come identificativo.
`flow_id` stringa	Obbligatorio per i messaggi con flussi. Identificativo unico del flusso fornito da WhatsApp.
`flow_cta` stringa	Obbligatorio per i messaggi con flussi. Testo sul pulsante di CTA, ad es. "Iscriviti". Lunghezza massima: 20 caratteri (no emoji).
`flow_action` stringa	Opzionale per i messaggi con flussi. `navigate` o `data_exchange`. Usa `navigate` per predefinire la prima schermata come parte del messaggio. Usa `data_exchange` per casi d'uso avanzati in cui la prima schermata è fornita dal tuo endpoint. Impostazione predefinita: `navigate`
`flow_action_payload` oggetto	Opzionale per i messaggi con flussi. Obbligatorio solo se `flow_action` è `navigate`. L'oggetto può contenere i seguenti parametri: `screen`stringa – Obbligatorio. L'`id` della prima schermata del flusso. `data`oggetto – Facoltativo. I dati di input per la prima schermata del flusso. Deve essere un oggetto non vuoto.

Oggetto header

Nome	Descrizione
`document` oggetto	Obbligatorio se `type` è impostato su `document`. Contiene l'oggetto media di questo documento.
`image` oggetto	Obbligatorio se `type` è impostato su `image`. Contiene l'oggetto media per questa immagine.
`text` stringa	Obbligatorio se `type` è impostato su `text`. Testo per l'intestazione. La formattazione consente gli emoji, ma non il markdown. Lunghezza massima: 60 caratteri.
`type` stringa	Obbligatorio. Il tipo di intestazione che desideri utilizzare. Valori supportati: `text`: utilizzato per i messaggi con lista, i pulsanti di risposta e i messaggi con più prodotti. `video`: utilizzato per i pulsanti di risposta. `image`: utilizzato per i pulsanti di risposta. `document`: utilizzato per i pulsanti di risposta.
`video` oggetto	Obbligatorio se `type` è impostato su `video`. Contiene l'oggetto media per questo video.

Oggetto section

Nome Descrizione

Nome	Descrizione
`product_items` array di oggetti	Obbligatorio per messaggi con più prodotti. Array di oggetti `product`. Minimo 1 prodotto per sezione e massimo 30 prodotti in tutte le sezioni. Ogni oggetto `product` contiene il seguente campo: `product_retailer_id`stringa – Obbligatorio per messaggi con più prodotti. Identificativo unico del prodotto in un catalogo. Per ottenere questo ID, vai al Gestore delle vendite di Meta, seleziona il tuo account e lo shop che desideri usare. Quindi clicca su Catalogo > Articoli e trova l'articolo che vuoi menzionare. L'ID è visualizzato sotto il nome dell'articolo.
`rows` array di oggetti	Obbligatorio per i messaggi con elenco. Contiene una lista di righe. Nelle tue sezioni puoi avere un totale di 10 righe. Ogni riga deve avere un titolo (lunghezza massima: 24 caratteri) e un ID (lunghezza massima: 200 caratteri). Puoi aggiungere una descrizione (lunghezza massima: 72 caratteri), ma è facoltativa. Esempio: "rows": [ { "id":"unique-row-identifier-here", "title": "row-title-content-here", "description": "row-description-content-here", } ]
`title` stringa	Obbligatorio se il messaggio ha più di una sezione. Titolo della sezione. Lunghezza massima: 24 caratteri.

product_items

array di oggetti

Obbligatorio per messaggi con più prodotti.

Array di oggetti product. Minimo 1 prodotto per sezione e massimo 30 prodotti in tutte le sezioni.

Ogni oggetto product contiene il seguente campo:

product_retailer_idstringa – Obbligatorio per messaggi con più prodotti. Identificativo unico del prodotto in un catalogo. Per ottenere questo ID, vai al Gestore delle vendite di Meta, seleziona il tuo account e lo shop che desideri usare. Quindi clicca su Catalogo > Articoli e trova l'articolo che vuoi menzionare. L'ID è visualizzato sotto il nome dell'articolo.

rows

array di oggetti

Obbligatorio per i messaggi con elenco.

Contiene una lista di righe. Nelle tue sezioni puoi avere un totale di 10 righe.

Ogni riga deve avere un titolo (lunghezza massima: 24 caratteri) e un ID (lunghezza massima: 200 caratteri). Puoi aggiungere una descrizione (lunghezza massima: 72 caratteri), ma è facoltativa.

Esempio:

"rows": [
  {
   "id":"unique-row-identifier-here",
   "title": "row-title-content-here",
   "description": "row-description-content-here",           
   }
]

title

stringa

Obbligatorio se il messaggio ha più di una sezione.

Titolo della sezione.

Lunghezza massima: 24 caratteri.

Oggetto location

Name	Description
`latitude`	Required. Location latitude in decimal degrees.
`longitude`	Required. Location longitude in decimal degrees.
`name`	Required. Name of the location.
`address`	Required. Address of the location.

Oggetto media

Consulta Ottenere l'ID del contenuto multimediale per informazioni su come ottenere l'ID del tuo oggetto media. Per informazioni sui tipi di contenuti multimediali supportati per l'API Cloud, consulta Tipi di contenuti multimediali supportati.

Name	Description
`id` string	Required when `type` is `audio`, `document`, `image`, `sticker`, or `video` and you are not using a link. The media object ID. Do not use this field when message `type` is set to `text`.
`link` string	Required when `type` is `audio`, `document`, `image`, `sticker`, or `video` and you are not using an uploaded media ID (i.e. you are hosting the media asset on your public server). The protocol and URL of the media to be sent. Use only with HTTP/HTTPS URLs. Do not use this field when message `type` is set to `text`. Cloud API users only: See Media HTTP Caching if you would like us to cache the media asset for future messages. When we request the media asset from your server you must indicate the media's MIME type by including the `Content-Type` HTTP header. For example: `Content-Type: video/mp4`. See Supported Media Types for a list of supported media and their MIME types.
`caption` string	Optional. Media asset caption. Do not use with `audio` or `sticker` media. On-Premises API users: For v2.41.2 or newer, this field is is limited to 1024 characters. Captions are currently not supported for `document` media.
`filename` string	Optional. Describes the filename for the specific document. Use only with `document` media. The extension of the filename will specify what format the document is displayed as in WhatsApp.
`provider` string	Optional. On-Premises API only. This path is optionally used with a `link` when the HTTP/HTTPS link is not directly accessible and requires additional configurations like a bearer token. For information on configuring providers, see the Media Providers documentation.

Oggetto template

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.

Name	Description
`name`	Required. Name of the template.
`language` object	Required. Contains a `language` object. Specifies the language the template may be rendered in. The `language` object can contain the following fields: `policy`string – Required. The language policy the message should follow. The only supported option is `deterministic`. See Language Policy Options. `code`string – Required. The code of the language or locale to use. Accepts both `language` and `language_locale` formats (e.g., `en` and `en_US`). For all codes, see Supported Languages.
`components` array of objects	Optional. Array of `components` objects containing the parameters of the message.
`namespace`	Optional. Only used for On-Premises API. Namespace of the template.

I seguenti oggetti sono annidati dentro l'oggetto template:

Oggetto button
Oggetto components
Oggetto currency
Oggetto date time
Oggetto language
Oggetto parameter

Oggetto button parameter

Nome	Descrizione (clicca sulla freccia nella colonna di sinistra per le opzioni supportate).
`type` stringa	Obbligatorio. Indica il tipo di parametro per il pulsante.
Opzioni supportate	`"payload"` `"text"`
`payload`	Obbligatorio per pulsanti `quick_reply`. Payload definito dallo sviluppatore che viene restituito quando si clicca sul pulsante in aggiunta al testo visualizzato sul pulsante. Consulta Callback da un clic su un pulsante di risposta rapida per un esempio.
`text`	Obbligatorio per i pulsanti con URL. Suffisso fornito dallo sviluppatore che è aggiunto all'URL predefinito del prefisso nel modello.

Oggetto components

Name	Description (Click the arrow in the left column for supported options.)
`type` string	Required. Describes the `component` type. Example of a `components` object with an array of `parameters` object nested inside: "components": [{ "type": "body", "parameters": [{ "type": "text", "text": "name" }, { "type": "text", "text": "Hi there" }] }]
Supported Options	`header` `body` `button` For text-based templates, we only support the `type=body`.
`sub_type` string	Required when `type=button`. Not used for the other types. Type of button to create.
Supported Options	`quick_reply`: Refers to a previously created quick reply button that allows for the customer to return a predefined message. `url`: Refers to a previously created button that allows the customer to visit the URL generated by appending the `text` parameter to the predefined prefix URL in the template. `catalog`: Refers to a previously created catalog button that allows for the customer to return a full product catalog.
`parameters` array of objects	Required when `type=button`. Array of `parameter` objects with the content of the message. For components of type=button, see the `button` parameter object.
`index`	Required when `type=button`. Not used for the other types. Position index of the button. You can have up to 10 buttons using index values of 0 to 9.

Oggetto currency

Nome Descrizione

Nome	Descrizione
`fallback_value`	Obbligatorio. Testo predefinito se la localizzazione non va a buon fine.
`code`	Obbligatorio. Codice valuta come definito in `ISO 4217`.
`amount_1000`	Obbligatorio. Importo moltiplicato per 1000.

fallback_value

Obbligatorio.

Testo predefinito se la localizzazione non va a buon fine.

code

Obbligatorio.

Codice valuta come definito in ISO 4217.

amount_1000

Obbligatorio.

Importo moltiplicato per 1000.

Oggetto date_time

Nome Descrizione

Nome	Descrizione
`fallback_value`	Obbligatorio. Testo predefinito. Per l'API Cloud, usiamo sempre il valore di fallback e non cerchiamo di localizzare usando altri campi opzionali.

fallback_value

Obbligatorio.

Testo predefinito. Per l'API Cloud, usiamo sempre il valore di fallback e non cerchiamo di localizzare usando altri campi opzionali.

Oggetto parameter

Nome	Descrizione
`type` stringa	Obbligatorio. Descrive il tipo di parametro. Valori supportati: `currency` `date_time` `document` `image` `text` `video` Per i modelli basati su testo, gli unici tipi di parametri supportati sono `currency`, `date_time` e `text`.
`text` stringa	Obbligatorio quando `type=text`. Il testo del messaggio. Il limite di caratteri varia in base al seguente tipo di componente incluso. Per il tipo di componente `header`: 60 caratteri Per il tipo di componente `body`: 1024 caratteri se sono inclusi altri tipi di componenti 32 768 caratteri se `body` è l'unico tipo di componente incluso
`currency` oggetto	Obbligatorio quando `type=currency`. Un oggetto `currency`.
`date_time` oggetto	Obbligatorio quando `type=date_time`. Un oggetto `date_time`.
`image` oggetto	Obbligatorio quando `type=image`. Un oggetto `media` di tipo `image`. Sottotitoli non supportati quando usati in un modello multimediale.
`document` oggetto	Obbligatorio quando `type=document`. Un oggetto `media` di tipo `document`. Solo i documenti PDF sono supportati per i modelli di messaggi basati su contenuti multimediali. Sottotitoli non supportati quando usati in un modello multimediale.
`video` oggetto	Obbligatorio quando `type=video`. Un oggetto `media` di tipo `video`. Sottotitoli non supportati quando usati in un modello multimediale.

Oggetto text

Nome Descrizione

Nome	Descrizione
`body` stringa	Obbligatorio per i messaggi di testo. Il testo del messaggio che può contenere URL che iniziano con http:// o https:// e formattazione. Consulta le opzioni di formattazione disponibili qui. Se includi URL nel testo e vuoi includere una casella di anteprima nei messaggi di testo (`preview_url: true`), assicurati che l'URL inizi con `http://` o `https://`. Sono preferiti gli URL `https://`. Devi includere un nome host, poiché gli indirizzi IP non saranno abbinati. Lunghezza massima: 4096 caratteri
`preview_url` booleano	Opzionale. Solo API Cloud. Impostalo su `true` per far sì che le app WhatsApp Messenger e WhatsApp Business tentino di visualizzare un'anteprima del link di qualsiasi URL nella stringa di testo `body`. Gli URL devono iniziare con `http://` o `https://`. Se nella stringa di testo `body` ci sono più URL, sarà visualizzato solo il primo. Se `preview_url` viene omesso, o se non è in grado di recuperare un'anteprima, viene visualizzato un link cliccabile. Gli utenti dell'API On-Premises devono usare invece `preview_url` nel payload dei messaggi di primo livello. Consulta Parametri.

body

stringa

Obbligatorio per i messaggi di testo.

Il testo del messaggio che può contenere URL che iniziano con http:// o https:// e formattazione. Consulta le opzioni di formattazione disponibili qui.

Se includi URL nel testo e vuoi includere una casella di anteprima nei messaggi di testo (preview_url: true), assicurati che l'URL inizi con http:// o https://. Sono preferiti gli URL https://. Devi includere un nome host, poiché gli indirizzi IP non saranno abbinati.

Lunghezza massima: 4096 caratteri

preview_url

booleano

Opzionale. Solo API Cloud.

Impostalo su true per far sì che le app WhatsApp Messenger e WhatsApp Business tentino di visualizzare un'anteprima del link di qualsiasi URL nella stringa di testo body. Gli URL devono iniziare con http:// o https://. Se nella stringa di testo body ci sono più URL, sarà visualizzato solo il primo.

Se preview_url viene omesso, o se non è in grado di recuperare un'anteprima, viene visualizzato un link cliccabile.

Gli utenti dell'API On-Premises devono usare invece preview_url nel payload dei messaggi di primo livello. Consulta Parametri.

Oggetto reaction

Nome Descrizione

Nome	Descrizione
`message_id` stringa	Obbligatorio. L'ID del messaggio WhatsApp (wamid) su cui dovrebbe comparire la reazione. La reazione non sarà inviata nei casi seguenti: Il messaggio è più vecchio di 30 giorni Il messaggio è un messaggio con reazione Il messaggio è stato eliminato Se l'ID è di un messaggio che è stato eliminato, il messaggio non verrà consegnato.
`emoji` stringa	Obbligatorio. Emoji che deve comparire sul messaggio. Possono essere utilizzate tutte le emoji supportate dai dispositivi Android e iOS. Sono supportate le emoji visualizzate. Se si utilizzano valori emoji unicode, questi devono essere codificati Java o Javascript con il carattere di escape. In un messaggio con reazione è possibile inviare solo un'emoji. Usa una stringa vuota per rimuovere un'emoji inviata in precedenza.

message_id

stringa

Obbligatorio.

L'ID del messaggio WhatsApp (wamid) su cui dovrebbe comparire la reazione. La reazione non sarà inviata nei casi seguenti:

Il messaggio è più vecchio di 30 giorni
Il messaggio è un messaggio con reazione
Il messaggio è stato eliminato

Se l'ID è di un messaggio che è stato eliminato, il messaggio non verrà consegnato.

emoji

stringa

Obbligatorio.

Emoji che deve comparire sul messaggio.

Possono essere utilizzate tutte le emoji supportate dai dispositivi Android e iOS.
Sono supportate le emoji visualizzate.
Se si utilizzano valori emoji unicode, questi devono essere codificati Java o Javascript con il carattere di escape.
In un messaggio con reazione è possibile inviare solo un'emoji.
Usa una stringa vuota per rimuovere un'emoji inviata in precedenza.

Panoramica

Guide

Consulta le seguenti guide per informazioni complete su come usare l'endpoint /messages per inviare messaggi:

Esempi

SMS

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": "text",
      "text": { // the text object
        "preview_url": false,
        "body": "MESSAGE_CONTENT"
        }
    }'

Messaggi con reazione

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": "reaction",
  "reaction": {
    "message_id": "wamid.HBgLM...",
    "emoji": "\uD83D\uDE00"
  }
}'

Messaggi con contenuto multimediale

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": "image",
  "image": {
    "id" : "MEDIA-OBJECT-ID"
  }
}'

Messaggi contenenti la posizione

curl -X  POST \
 'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/messages' \
 -H 'Authorization: ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "to": "PHONE_NUMBER",
  "type": "location",
  "location": {
    "longitude": LONG_NUMBER,
    "latitude": LAT_NUMBER,
    "name": LOCATION_NAME,
    "address": LOCATION_ADDRESS
  }
}'

Messaggi contenenti un contatto

curl -X  POST \
 'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/messages' \
 -H 'Authorization: ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "to": "PHONE_NUMBER",
  "type": "contacts",
  "contacts": [{
      "addresses": [{
          "street": "STREET",
          "city": "CITY",
          "state": "STATE",
          "zip": "ZIP",
          "country": "COUNTRY",
          "country_code": "COUNTRY_CODE",
          "type": "HOME"
        },
        {
          "street": "STREET",
          "city": "CITY",
          "state": "STATE",
          "zip": "ZIP",
          "country": "COUNTRY",
          "country_code": "COUNTRY_CODE",
          "type": "WORK"
        }],
      "birthday": "YEAR_MONTH_DAY",
      "emails": [{
          "email": "EMAIL",
          "type": "WORK"
        },
        {
          "email": "EMAIL",
          "type": "HOME"
        }],
      "name": {
        "formatted_name": "NAME",
        "first_name": "FIRST_NAME",
        "last_name": "LAST_NAME",
        "middle_name": "MIDDLE_NAME",
        "suffix": "SUFFIX",
        "prefix": "PREFIX"
      },
      "org": {
        "company": "COMPANY",
        "department": "DEPARTMENT",
        "title": "TITLE"
      },
      "phones": [{
          "phone": "PHONE_NUMBER",
          "type": "HOME"
        },
        {
          "phone": "PHONE_NUMBER",
          "type": "WORK",
          "wa_id": "PHONE_OR_WA_ID"
        }],
      "urls": [{
          "url": "URL",
          "type": "WORK"
        },
        {
          "url": "URL",
          "type": "HOME"
        }]
    }]
}'

Messaggi interattivi

Messaggi per un singolo prodotto

curl -X  POST \
 'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
   "messaging_product": "whatsapp",
   "recipient_type": "individual",
   "to": "PHONE_NUMBER",
   "type": "interactive",
   "interactive": {
     "type": "product",
     "body": {
       "text": "optional body text"
     },
     "footer": {
       "text": "optional footer text"
     },
     "action": {
       "catalog_id": "CATALOG_ID",
       "product_retailer_id": "ID_TEST_ITEM_1"
     }
   }
 }'

Messaggi per più prodotti

curl -X  POST \
 'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
 "messaging_product": "whatsapp",
   "recipient_type": "individual",
   "to": "PHONE_NUMBER",
   "type": "interactive",
   "interactive": {
     "type": "product_list",
     "header":{
       "type": "text",
       "text": "header-content"
     },
     "body": {
       "text": "body-content"
     },
     "footer": {
       "text": "footer-content"
     },
     "action": {
       "catalog_id": "CATALOG_ID",
       "sections": [
         {
           "title": "section-title",
           "product_items": [
             { "product_retailer_id": "product-SKU-in-catalog" },
             { "product_retailer_id": "product-SKU-in-catalog" },
             ...
           ]
         },
         {
           "title": "section-title",
           "product_items": [
             { "product_retailer_id": "product-SKU-in-catalog" },
             { "product_retailer_id": "product-SKU-in-catalog" },
             ...
           ]
         }
       ]
     }
   }
 }

Messaggi per il catalogo

curl -X  POST \
 'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE_NUMBER",
  "type": "interactive",
  "interactive" : {
    "type" : "catalog_message",
    "body" : {
      "text": "Thanks for your order! Tell us what address you’d like this order delivered to."
    },
    "action": {
      "name": "catalog_message",
      "parameters": { 
        "thumbnail_product_retailer_id": "<Product-retailer-id>"
      }
    }
  }
}'

Messaggi con flussi

curl -X  POST \
 'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE_NUMBER",
  "type": "interactive",
  "interactive" : {
    "type": "flow",
    "header": {
      "type": "text",
      "text": "Flow message header"
    },
    "body": {
      "text": "Flow message body"
    },
    "footer": {
      "text": "Flow message footer"
    },
    "action": {
      "name": "flow",
      "parameters": {
        "flow_message_version": "3",
        "flow_token": "AQAAAAACS5FpgQ_cAAAAAD0QI3s",
        "flow_id": "<FLOW_ID>",
        "flow_cta": "Book!",
        "flow_action": "navigate",
        "flow_action_payload": {
          "screen": "<SCREEN_ID>",
          "data": {
            "user_name": "name",
            "user_age": 25
          }
        }
      }
    }
  }
}'

Messaggi con lista

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": "interactive",
  "interactive": {
    "type": "list",
    "header": {
      "type": "text",
      "text": "HEADER_TEXT"
    },
    "body": {
      "text": "BODY_TEXT"
    },
    "footer": {
      "text": "FOOTER_TEXT"
    },
    "action": {
      "button": "BUTTON_TEXT",
      "sections": [
        {
          "title": "SECTION_1_TITLE",
          "rows": [
            {
              "id": "SECTION_1_ROW_1_ID",
              "title": "SECTION_1_ROW_1_TITLE",
              "description": "SECTION_1_ROW_1_DESCRIPTION"
            },
            {
              "id": "SECTION_1_ROW_2_ID",
              "title": "SECTION_1_ROW_2_TITLE",
              "description": "SECTION_1_ROW_2_DESCRIPTION"
            }
          ]
        },
        {
          "title": "SECTION_2_TITLE",
          "rows": [
            {
              "id": "SECTION_2_ROW_1_ID",
              "title": "SECTION_2_ROW_1_TITLE",
              "description": "SECTION_2_ROW_1_DESCRIPTION"
            },
            {
              "id": "SECTION_2_ROW_2_ID",
              "title": "SECTION_2_ROW_2_TITLE",
              "description": "SECTION_2_ROW_2_DESCRIPTION"
            }
          ]
        }
      ]
    }
  }
}'

Pulsante di risposta

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": "interactive",
  "interactive": {
    "type": "button",
    "body": {
      "text": "BUTTON_TEXT"
    },
    "action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "id": "UNIQUE_BUTTON_ID_1",
            "title": "BUTTON_TITLE_1"
          }
        },
        {
          "type": "reply",
          "reply": {
            "id": "UNIQUE_BUTTON_ID_2",
            "title": "BUTTON_TITLE_2"
          }
        }
      ]
    }
  }
}'

Modelli di messaggi

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.

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"
          }
        ]
      }
    ]
  }
}'

Rispondere al messaggio

curl -X POST \
 'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "context": {
     "message_id": "MESSAGE_ID"
  },
  "to": "PHONE_NUMBER",
  "type": "text",
  "text": {
    "preview_url": false,
    "body": "your-text-message-content"
  }
}’

Risposta riuscita

    {
      "messaging_product": "whatsapp",
      "contacts": [
        {
          "input": "16505555555",
          "wa_id": "16505555555"
        }
      ],
      "messages": [
        {
          "id": "wamid.HBgLMTY1MDUwNzY1MjAVAgARGBI5QTNDQTVCM0Q0Q0Q2RTY3RTcA"
        }
      ]
    }

Applies to businesses in Brazil, Colombia, and Singapore, starting September 12, 2023. Applies to all businesses starting October 12, 2023.

Messages will have one of the following statuses which will be returned in each of the messages objects

"message_status":"accepted" : means the message was sent to the intended recipient
"message_status":"held_for_quality_assessment": means the message send was delayed until quality can be validated and it will either be sent or dropped at this point


      {
      "messaging_product": "whatsapp",
      "contacts": [
        {
          "input": "16505555555",
          "wa_id": "16505555555"
        }
      ],
      "messages": [
        {
          "id": "wamid.HBgLMTY1MDUwNzY1MjAVAgARGBI5QTNDQTVCM0Q0Q0Q2RTY3RTcA",
          "message_status": "accepted",
        }
      ]
    }

Piattaforma WhatsApp Business | API Cloud | API Business Management