API Cloud

We are making changes to the WhatsApp Business Platform pricing model. See Pricing Updates on the WhatsApp Business Platform.

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.

EndpointAutenticazione

/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:

NomeDescrizione (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:


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 contacts

NameDescription

addresses

object

Optional.

Full contact address(es) formatted as an addresses object. The object can contain the following fields:

streetstring – Optional. Street number and name.

citystring – Optional. City name.

statestring – Optional. State abbreviation.

zipstring – Optional. ZIP code.

countrystring – Optional. Full country name.

country_codestring – Optional. Two-letter country abbreviation.

typestring – 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:

emailstring – Optional. Email address.

typestring – 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_namestring – Required. Full name, as it normally appears.

first_namestring – Optional*. First name.

last_namestring – Optional*. Last name.

middle_namestring – Optional*. Middle name.

suffixstring – Optional*. Name suffix.

prefixstring – 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:

companystring – Optional. Name of the contact's company.

departmentstring – Optional. Name of the contact's department.

titlestring – Optional. Contact's business title.

phones

object

Optional.

Contact phone number(s) formatted as a phone object. The object can contain the following fields:

phonestring – Optional. Automatically populated with the `wa_id` value as a formatted phone number.

typestring – Optional. Standard Values are CELL, MAIN, IPHONE, HOME, and WORK.

wa_idstring – Optional. WhatsApp ID.

urls

object

Optional.

Contact URL(s) formatted as a urls object. The object can contain the following fields:

urlstring – Optional. URL.

typestring – Optional. Standard values are HOME and WORK.

Oggetto interactive

NomeDescrizione

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:

textstringa – 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:

textstringa – 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

NomeDescrizione

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 il contenuto deve essere unico 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:

screenstringa – Obbligatorio. L'id della prima schermata del flusso.

dataoggetto – Facoltativo. I dati di input per la prima schermata del flusso. Deve essere un oggetto non vuoto.

Oggetto header

NomeDescrizione

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.

sub_text

stringa

Facoltativo.

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

NomeDescrizione

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

NameDescription

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.

NameDescription

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

NomeDescrizione

namespace

Obbligatorio.

Spazio dei nomi del modello.


A partire dalla v2.27.8, questo deve essere lo spazio dei nomi associato all'account WhatsApp Business che possiede il numero di telefono associato all'attuale client dell'API di WhatsApp Business; in caso contrario, l'invio del messaggio non va a buon fine.

name

Obbligatorio.

Nome del modello.

language

Obbligatorio.

Specifica la lingua in cui il modello può essere visualizzato. Con i modelli di messaggio con contenuti multimediali funziona solo il criterio di lingua deterministic. Consulta la sezione Lingua per maggiori informazioni.

components

Facoltativo.

Array contenente i parametri del messaggio.

I seguenti oggetti sono annidati dentro l'oggetto template:

Oggetto button parameter

NomeDescrizione (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

NomeDescrizione

type

Obbligatorio.

Descrive il tipo di component.
Valori:header, body, footer

parameters

Facoltativo.

Array contenente il contenuto del messaggio.

Oggetto currency

NomeDescrizione

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

NomeDescrizione

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

NomeDescrizione

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

NomeDescrizione

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

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

NomeDescrizione

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

Messaggi di testo

curl -X  POST \
'https://graph.facebook.com/v21.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/v21.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/v21.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 basati sulla posizione

curl -X  POST \
 'https://graph.facebook.com/v21.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/v21.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/v21.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/v21.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/v21.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/v21.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/v21.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/v21.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

curl -X  POST \
 'https://graph.facebook.com/v21.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/v21.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",
        }
      ]
    }