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

{
  "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"
}

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:

{
  "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
• WhatsApp webhooks: tutti gli eventi a cui puoi iscriverti