Ricevere posizioni WhatsApp

Un segnaposto condiviso da un contatto arriva come messaggio in ingresso con location. Lo stesso ramo risponde a una richiesta di posizione inviata, che è l'unico tipo interattivo la cui risposta arriva qui anziché su interactive_reply.

Cosa contiene una posizione in ingresso

Esempio di codice

{
  "id": "wam_01kyf8u2shzx0v6m9q3bag8tje",
  "direction": "inbound",
  "from": { "phone_number": "+14155550100" },
  "to": { "phone_number": "+13124495569" },
  "status": "received",
  "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
  "location": {
    "latitude": 37.7793,
    "longitude": -122.4193,
    "name": "Embarcadero Plaza",
    "address": "1 Market St, San Francisco, CA 94105"
  },
  "created_at": "2026-08-25T09:23:14Z"
}

Campo	Cosa contiene
latitude	Latitudine in gradi decimali
longitude	Longitudine in gradi decimali
name	Il nome del luogo; assente quando il contatto ha condiviso un segnaposto semplice
address	L'indirizzo stradale, che WhatsApp invia solo insieme a un name
url	Un link al luogo, presente soprattutto per le sedi di attività, quando il client del mittente lo ha fornito

Un segnaposto semplice posizionato sulla mappa contiene solo le due coordinate, quindi tratta name, address e url come informazioni aggiuntive da mostrare quando presenti, non come campi su cui basare la logica. Leggi le coordinate come numeri JSON e aspettati valori negativi negli emisferi sud e ovest.

Una posizione che risponde a una richiesta di posizione

Quando il segnaposto risponde a una richiesta di posizione che hai inviato, WhatsApp riporta la richiesta come target della risposta e in_reply_to_message_id indica il messaggio che conteneva il pulsante. È questo che lega una risposta a una domanda, ed è la differenza rispetto a una richiesta di informazioni di contatto, la cui risposta non contiene un collegamento simile.

Nient'altro contrassegna il segnaposto come risposta. Un contatto che condivide la propria posizione spontaneamente produce lo stesso ramo senza in_reply_to_message_id, quindi un'integrazione in ascolto di una risposta controlla quel campo anziché il ramo. Il campo non è una garanzia nella direzione opposta: WhatsApp non contrassegna ogni risposta e la risoluzione può fallire, quindi una risposta autentica può arrivare senza di esso. La pagina sulle risposte citate dell'hub spiega quando ciò accade e come comportarsi quando la classificazione deve reggere.

Il payload del webhook

whatsapp.received contiene il ramo location nell'envelope dell'evento:

Esempio di codice

{
  "type": "whatsapp.received",
  "timestamp": "2026-08-25T09:23:14.507Z",
  "data": {
    "whatsapp_id": "wam_01kyf8u2shzx0v6m9q3bag8tje",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
    "direction": "inbound",
    "from": { "phone_number": "+14155550100" },
    "to": { "phone_number": "+13124495569" },
    "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
    "location": {
      "latitude": 37.7793,
      "longitude": -122.4193,
      "name": "Embarcadero Plaza",
      "address": "1 Market St, San Francisco, CA 94105"
    },
    "tags": null,
    "metadata": null
  }
}

Aspetti da tenere d'occhio

La condivisione della posizione in tempo reale non è modellata come contenuto. Quello che arriva è una singola posizione fissata in un istante, quindi una vista di tracciamento non ha nulla da aggiornare. Non costruirne una su questo campo.
Un'integrazione che osserva solo interactive_reply perde questo evento. La risposta a una richiesta di posizione arriva qui, e la risposta a una richiesta di informazioni di contatto arriva su contact_cards, quindi un handler che legge solo i tap li perde entrambi.
Le coordinate sono quelle riportate dal dispositivo del contatto. Non includono raggio di precisione né altitudine, e un segnaposto trascinato dal contatto si trova dove l'ha trascinato. Conferma l'indirizzo a parole quando deve essere corretto.

Passaggi successivi

Come funziona la ricezione: l'envelope in ingresso, il recupero dei media e il webhook whatsapp.received
Messaggi di posizione WhatsApp: il lato di invio dello stesso ramo
Richieste di posizione WhatsApp: il pulsante che chiede un segnaposto
Eventi WhatsApp: l'elenco completo degli eventi, tramite API o webhook

Risorse correlate

Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.

Guarda la guidaConnecting WhatsApp to Bird: from buying a number to a live channel Comprendi il concettoWhat is the 24-hour customer service window on WhatsApp?Usa lo strumentoWhatsApp message builder Esplora la funzionalitàWhatsApp

Prova l'esercitazione e ottieni un brief di implementazione