API On-Premises della piattaforma WhatsApp Business

Notifiche dei messaggi ricevuti

Quando ricevi un messaggio in arrivo, viene inviata una notifica all'URL del webhook che hai definito nelle impostazioni dell'app. Questo documento descrive i messaggi in arrivo che puoi ricevere e ne fornisce degli esempi.

Oggetti delle notifiche

Le notifiche dei messaggi ricevuti possono contenere i seguenti oggetti:

Quando ricevi un messaggio con contenuti multimediali, il client dell'API di WhatsApp Business scarica tali contenuti. Al termine del download dei contenuti multimediali, viene inviata una notifica al tuo webhook. Questa notifica contiene informazioni che identificano l'oggetto multimediale e consentono di trovare e recuperare tale oggetto. Utilizza l'endpoint Media con il relativo id per recuperare i contenuti.

Esempi di messaggi ricevuti

Messaggio di testo

{
  "contacts": [{
    "profile": {
      "name": "Kerry Fisher"
      },
    "wa_id": "16315551234"
  }],
  "messages":[{
    "from": "16315551234",
    "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
    "timestamp": "1518694235",
    "text": {
      "body": "Hello this is an answer"
    },
    "type": "text"
  }]
}

Messaggio di posizione statica

{
  "contacts": [{
    "profile": {
        "name": "Kerry Fisher"
    },
    "wa_id": "16315551234"
  }],
 "messages":[{
   "from":"16315551234",
   "id":"ABGGFlA5FpafAgo6tHcNmNjXmuSf",
   "location":{
      "address":"Main Street Beach, Santa Cruz, CA",
      "latitude":38.9806263495,
      "longitude":-131.9428612257,
      "name":"Main Street Beach",
      "url":"https://foursquare.com/v/4d7031d35b5df7744"},
   "timestamp":"1521497875",
   "type":"location"
 }]
}

Messaggio contenente contatti

{
  "contacts": [{
    "profile": {
      "name": "Kerry Fisher"
    },
    "wa_id": "16315551234"
  }],
  "messages": [{
    "contacts": [{
      "addresses": [{
        "city": "Menlo Park",
        "country": "United States",
        "country_code": "us",
        "state": "CA",
        "street": "1 Hacker Way",
        "type": "WORK",
        "zip": "94025"
      }],
      "birthday": "2012-08-18",
      "emails": [{
        "email": "kfish@fb.com",
        "type": "WORK"
      }],
      "ims": [{
        "service": "AIM",
        "user_id": "kfish"
      }],
      "name": {
        "first_name": "Kerry",
        "formatted_name": "Kerry Fisher",
        "last_name": "Fisher"
      },
      "org": {
        "company": "Meta",
 	"department": "WhatsApp"
      },
      "phones": [{
        "phone": "+1 (940) 555-1234",
        "type": "CELL"
        },
        {
          "phone": "+1 (650) 555-1234",
          "type": "WORK",
          "wa_id": "16505551234"
      }],
      "urls": [{
        "url": "https://www.facebook.com",
        "type": "WORK"
      }]
    }],
    "from": "16505551234",
    "id": "ABGGFlA4dSRvAgo6C4Z53hMh1ugR",
    "timestamp": "1537248012",
    "type": "contacts"
  }]
}

L'impostazione contact_image è vuota se il client del consumatore utilizza un iPhone.

Messaggi con contenuto multimediale

Messaggio contenente un'immagine:

{
	"messages": [{
		"from": "16315551234",
		"id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
		"image": {
			"file": "/usr/local/wamedia/shared/b1cf38-8734-4ad3-b4a1-ef0c10d0d683",
			"id": "b1c68f38-8734-4ad3-b4a1-ef0c10d683",
			"mime_type": "image/jpeg",
			"sha256": "29ed500fa64eb55fc19dc4124acb300e5dcc54a0f822a301ae99944db",
			"caption": "Check out my new phone!",
			"status": "downloaded"
		},
		"timestamp": "1521497954",
		"type": "image"
	}]
}

A partire dalla versione 2.49.1, i webhook dei messaggi con contenuto multimediale contengono lo stato e l'ID del contenuto multimediale ricevuto.

Stati di download

StatoDescrizione

downloaded

Il contenuto multimediale è stato scaricato correttamente.

retriable

Il contenuto multimediale non è stato scaricato, ma il download può essere riprovato usando l'endpoint retry.

undownloaded

Il contenuto multimediale potrebbe non essere stato scaricato.

Il campo caption è facoltativo per i messaggi con contenuto multimediale. È incluso solo se l'utente ha impostato una didascalia.

Messaggio contenente un documento:

{
  "messages": [{
    "from": "16315551234",
    "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
    "timestamp": "1522189546",
    "type": "document",
    "document": {
      "caption": "80skaraokesonglistartist",
			"file": "/usr/local/wamedia/shared/fc233119-733f-49c-bcbd-b2f68f798e33",
			"id": "fc233119-733f-49c-bcbd-b2f68f798e33",
			"mime_type": "application/pdf",
			"sha256": "3b11fa6ef2bde1dd14726e09d3edaf782120919d06f6484f32d5d5caa4b8e",
			"status": "downloaded"
		}
	}]
}

Messaggio vocale:

{
    "messages":[{
        "from": "16315551234",
        "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
        "timestamp": "1521827831",
        "type": "voice",
        "voice": {
            "file": "/usr/local/wamedia/shared/463e/b7ec/ff4e4d9bb1101879cbd411b2",
            "id": "463eb7ec-ff4e-4d9b-b110-1879cbd411b2",
            "mime_type": "audio/ogg; codecs=opus",
            "sha256": "fa9e1807d936b7cebe63654ea3a7912b1fa9479220258d823590521ef53b0710",
            "status": "downloaded"
        }
  }]
}

Messaggio contenente un adesivo:

{
  "messages":[{
        "from": "16315551234",
        "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
        "timestamp": "1521827831",
        "type": "sticker",
        "sticker": {
            "id": "b1c68f38-8734-4ad3-b4a1-ef0c10d683",
            "metadata": {
                "sticker-pack-id": "463eb7ec-ff4e-4d9b-b110-1879cbd411b2",
                "sticker-pack-name" : "Happy New Year",
                "sticker-pack-publisher" : "Kerry Fisher",
                "emojis": ["🐥", "😃"],
                "ios-app-store-link" : "https://apps.apple.com/app/id3133333",
                "android-app-store-link" : "https://play.google.com/store/apps/details?id=com.example",
                "is-first-party-sticker" : 0 | 1 # integer 
            },
            "mime_type": "image/webp",
            "sha256": "fa9e1807d936b7cebe63654ea3a7912b1fa9479220258d823590521ef53b0710"
        }  
    }]
}

Messaggio generato da inserzioni che rimandano a WhatsApp

{
   "messages":[{
      "from":"12345678",
      "id":"ABGGFlA5FpafAgo6tHcNmNjXmuSf",
      "image":{
         "id":"b1c68f38-8734-4ad3-b4a1-ef0c10d683",
         "mime_type":"image/jpeg",
         "sha256":"29ed500fa64eb55fc19dc4124acb300e5dcca0f822a301ae99944db"
         "caption": "Check out my product!",
      },
      "timestamp":"1521497954",
      "type":"image",
      "referral" : {
        "headline": "Our new product",
        "body" : "This is a great product",
        "source_type": "<SOURCE_TYPE>",
        "source_id": "<SOURCE_ID>",
        "source_url": "<SOURCE_URL>", //for the moment, this will always be a Facebook owned domain
        "video": {
          "id": "e144be57-12b1-4035-a520-703fcc87ef45",
        "ctwa_clid": "<CTWA_CLID>",
      }     
    }
  }]
}

Ottieni maggiori informazioni sulla proprietà referral.

Esempio: messaggi non supportati

È possibile ricevere una notifica di callback unknown. Di seguito è riportato un esempio di un tipo di messaggio non supportato ricevuto da un cliente.

{
  "contacts": [{
		"profile": {
			"name": "Kerry Fisher"
		},
		"wa_id": "16315551234"
	}],
  "messages": [{
		"errors": [{
			"code": 501,
			"details": "Message type is not currently supported",
			"title": "Unknown message type"
		}],
		"from": "16315551234",
		"id": "ABGGFRBzFymPAgo6N9KKs7HsN6eB",
		"timestamp": "1531933468",
		"type": "unknown"
	}]
}

Messaggi inoltrati

Puoi vedere se un messaggio che hai ricevuto è stato inoltrato o se viene inoltrato di frequente. Questa è una notifica per un messaggio inoltrato:

{
  "contacts": [{
    "profile": {
      "name": "Kerry Fisher"
    },
    "wa_id": "16315551234"
  }],
  "messages": [{
    "context": {
      "forwarded": true
    },
    "from": "16315558011",
    "id": "ABGGFmkiWVVPAgo-sOGh7pv13wVJ",
    "text": {
      "body": "Party at Dotty's tonight!"
    },
    "timestamp": "1593068329",
    "type": "text"
  }]
}

Questa è una notifica per un messaggio inoltrato di frequente:

{
  "contacts": [{
    "profile": {
      "name": "Kerry Fisher"
    },
    "wa_id": "16315551234"
  }],
  "messages": [{
    "context": {
      "frequently_forwarded": true
    },
    "from": "16315558011",
    "id": "ABGGFmkiWVVPAgo-sBTHfS3swNIl",
    "timestamp": "1593068225",
    "type": "video",
    "video": {
      "id": "e144be57-12b1-4035-a520-703fcc87ef45",
    "mime_type": "video/mp4",
    "sha256": "02c4e68a4f0d6af5ec6ef02120e20d15f520a4dd473b535abec1aab175c4e8b9"
    }
  }]
}

Notifica di sicurezza abilitata

Se il parametro show_security_notifications è impostato su true nelle impostazioni dell'app, tutte le notifiche dei messaggi in arrivo includeranno le seguenti informazioni sull'identità dell'utente contenute all'interno dell'oggetto identity:

{
  "contacts": [{
		"profile": {
			"name": "Kerry Fisher"
		},
		"wa_id": "16315551234"
	}],
   "messages": [{
        "from": "16315553601",
        "id": "ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh",
        "identity": {
            "acknowledged": true,
            "created_timestamp": 1602532300000,
            "hash": "Sjvjlx8G6Z0="
        },
        "text": {
            "body": "Hi from new number 3601"
        },
        "timestamp": "1602532300",
        "type": "text"
    }]
}

Messaggio da un clic sul pulsante di risposta rapida

Quando il cliente clicca su un pulsante di risposta rapida, viene inviata una risposta. Di seguito è riportato un esempio del formato di callback. Nota: un cliente può non cliccare su un pulsante e rispondere al messaggio interattivo o inviarti semplicemente un messaggio. Assicurati di essere in grado di supportare anche questo tipo di scenario. Consulta la documentazione sui Webhooks per maggiori informazioni. 
{
    "contacts": [
        {
            "profile": {
                "name": "Kerry Fisher"
            },
            "wa_id": "16505551234"
        }
    ],
    "messages": [
        {
            "button": {
                "payload": "No-Button-Payload",
                "text": "No"
            },
            "context": {
                "from": "16315558007",
                "id": "gBGGFmkiWVVPAgkgQkwi7IORac0"
            },
            "from": "16505551234",
            "id": "ABGGFmkiWVVPAgo-sKD87hgxPHdF",
            "timestamp": "1591210827",
            "type": "button"
        }
    ]
    # If there are any errors, an errors field (array) will be present        
    "errors": [ { ... } ]
}

Risposte in arrivo ai messaggi inviati

Gli utenti possono rispondere a un messaggio specifico su WhatsApp. Affinché l'azienda comprenda il contesto della risposta a un messaggio, includiamo l'oggetto context. L'oggetto context fornisce l'id del messaggio a cui il cliente ha risposto, l'ID WhatsApp del mittente del messaggio originale e gli ID di eventuali prodotti a cui potrebbe far riferimento il cliente.

Maggiori informazioni sono riportate in Come rispondere ai messaggi.

Esempio: il cliente ha risposto al tuo messaggio

Di seguito è riportato un esempio di messaggio in arrivo in risposta a un tuo messaggio inviato. Consulta la sezione relativa all'oggetto context di seguito per maggiori informazioni.

{
  "contacts": [ {
    "profile": {
        "name": "Kerry Fisher"
    },
    "wa_id": "16315551234"
  } ],
   "messages":[{
      "context":{
         "from":"16315558011",
         "id":"ABGGFlA5FpafAgo6tHcNmNjXmuSf"
         },
      "from":"16315551234",
      "id":"gBGGFlA5FpafAgkOuJbRq54qwbM",
      "text":{"body":"Yes, count me in!"},
      "timestamp":"1521499915",
      "type":"text"
  }]
}

Il campo text è facoltativo per i messaggi con contenuto multimediale. Se presente, il valore text corrisponde alla didascalia del contenuto multimediale inviato o al corpo della risposta, se la risposta è un messaggio di testo.

Esempio: il cliente ha risposto a un messaggio con lista

{
   "messages": [ {
      "context": {
        "from": "sender_wa_id_of_context_message",
        "group_id": "group_id_of_context_message",
        "id": "message_id_of_context_message",
        "mentions": [ "wa_id1", "wa_id2" ]
      },
      "from": "sender_wa_id",
      "group_id": "group_id",
      "id": "message_id",
      "timestamp": "message_timestamp",
      "type": "interactive",
      "interactive": {
          "type": "list_reply",
          "list_reply": {
            "title": "row-title-content-here",
            "id": "unique-row-identifier-here",
            "description": "row-description-content-here"
          }
      }
   }

Esempio: il cliente ha risposto a un messaggio con pulsante di risposta

{
  "messages": [ 
    {
      "context": {
        "from": "sender_wa_id_of_context_message",
        "group_id": "group_id_of_context_message",
        "id": "message_id_of_context_message",
        "mentions": [ "wa_id1", "wa_id2" ]
      },
      "from": "sender_wa_id",
      "group_id": "group_id",
      "id": "message_id",
      "timestamp": "message_timestamp",
      "type": "interactive",
      "interactive": {
        "type": "button_reply",
        "button_reply": {
          "id": "unique-button-identifier",
          "title": "button-text"
        }
      } # end interactive node
    } # end message item
  ] # end messages array
}

Esempio: il cliente chiede informazioni su un prodotto specifico

{
  "contacts": [
    {
      "profile": {
        "name": "customer-name"
      },
      "wa_id": "customer-whatsapp-ID"
    }
  ],
  "messages": [
    {
      "from": "customer-whatsapp-ID",
      "id": "message-ID",
      "text": {
        "body": "Can I get this in another color?"
      },
      "context": {
        "referred_product": {
          "catalog_id": "catalog-ID",
          "product_retailer_id": "product-ID"
        }
      },
      "timestamp": "message-received-timestamp",
      "type": "text"
    }
  ]
}

Esempio: il cliente ha effettuato un ordine dopo aver ricevuto un messaggio con uno o più prodotti

{
   "messages": [ {
      "from": "customer-whatsapp-id",
      "group_id": "group-id",
      "id": "message-ID",
      "timestamp": "message-timestamp",
      "type": "order"
      "order": {
         "catalog_id": "catalog_id",
         "product_items": [
            {
            "product_retailer_id":"product-ID",
            "quantity":"number-of-items",
            "item_price":"unitary-price-of-item",
            "currency":"price-currency"
            },
                 ...
         ],
         "text":"text-message-sent-along-with-the-order"
      }
   }
}

Messaggi di sistema in arrivo

I messaggi di sistema vengono generati dal sistema quando si verificano alcuni eventi.

Esempio: un utente ha cambiato il suo numero

Se il parametro notify_user_change_number è impostato su true nelle impostazioni dell'app, riceverai dei messaggi di sistema in arrivo quando un utente cambia il suo numero di telefono.

{
    "messages": [
        {
            "from": "16315558889",
            "id": "ABGGFjFVWIifAzNzeXMtMTYzMTU1NTg4ODlAcy53aGF0c2FwcC5uZXQtMTU3NDA4MDEwMjIxMy1jaGFuZ2U",
            "system": {
                "body": "‎User A changed from ‎+1 (631) 555-8889 to ‎+1 (631) 555-8890‎",
                "new_wa_id": "16315558890",
                "type": "user_changed_number"
            },
            "timestamp": "1574080102",
            "type": "system"
        }
    ]
}

Esempio: un utente è potenzialmente cambiato

Se il parametro show_security_notifications è impostato su true nelle impostazioni dell'app riceverai dei messaggi di sistema in arrivo quando un utente (nella conversazione con te) è potenzialmente cambiato su WhatsApp.

Fino a quando questa notifica non viene confermata mediante l'endpoint identity, tutti i messaggi in uscita per questo utente verranno bloccati. I messaggi in arrivo continueranno a essere ricevuti come previsto.

{
    "messages": [
        {
            "from": "16315553601",
            "id": "ABGGFjFVU2AfAzVzeXMtMTYzMTU1NTM2MDFAcy53aGF0c2FwcC5uZXQtMTYwMjUzNTM1NjMzMi1pZGVudGl0eQ",
            "system": {
  		"body": "Test security code change",
                "identity": "Rc/eg9Rl0JA=",
                "type": "user_identity_changed",
                "user": "16315553601"
            },
            "timestamp": "1602535356",
            "type": "system"
        }
    ]
}

Tipi di messaggio di sistema

Tipo di messaggio di sistemaDescrizione

user_changed_number

Numero di telefono dell'utente cambiato

user_identity_changed

Utente potenzialmente cambiato su WhatsApp

Menzionare gli utenti nei messaggi

Quando invii un messaggio che menziona direttamente un particolare ID WhatsApp e qualcuno risponde a quel messaggio, vedrai l'ID menzionato nell'oggetto context e nell'array mentions. Dato che può essere menzionato più di un numero di telefono, il campo mentions corrisponde a un array di numeri di telefono, anche se viene menzionato un solo numero di telefono.

Esempio: risposta del cliente al messaggio

Di seguito è riportato un esempio di risposta di un cliente a un messaggio che contiene delle menzioni. L'oggetto context contiene i numeri menzionati nel messaggio originale. La risposta nell'oggetto text menziona nuovamente gli stessi numeri.

{   
  "messages": [{
    "context": {
      "from": "16315555544",
      "id": "gBGGFlA5FpafAgkOuJbRq54qwbM",
      "mentions": [
        "16315551000",
        "16315551099"
      ]
    },
    "from": "16315551234 ",
    "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
    "timestamp": "1504902988",
    "text": {
      "body": "@16315551000 and @16315551099 are mentioned"
    },
    "type": "text"
  }]
}