WhatsApp-locaties ontvangen

Een pin die een contact deelt komt binnen als een inkomend bericht met location. Dezelfde arm beantwoordt een locatieverzoek dat je hebt verstuurd, het enige interactieve type waarvan het antwoord hier landt in plaats van op interactive_reply.

Wat een inkomende locatie bevat

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

Een kale pin op de kaart bevat alleen de twee coördinaten, dus behandel name, address en url als decoratie die je toont wanneer aanwezig, niet als velden om op te filteren. Lees de coördinaten als JSON-getallen en verwacht negatieve waarden op het zuidelijk en westelijk halfrond.

Een locatie die een locatieverzoek beantwoordt

Als de pin een locatieverzoek beantwoordt dat je hebt verstuurd, rapporteert WhatsApp de vraag als doel van het antwoord en in_reply_to_message_id noemt het bericht dat de knop bevatte. Dat is wat een antwoord aan een vraag koppelt, en het is het verschil met een contactgegevensverzoek, waarvan het antwoord zo'n link niet bevat.

Niets anders markeert de pin als een antwoord. Een contact dat spontaan een locatie deelt produceert dezelfde arm zonder in_reply_to_message_id, dus een integratie die op een antwoord wacht controleert dat veld in plaats van de arm. Het veld is geen garantie in de andere richting: WhatsApp markeert niet elk antwoord en de resolutie kan missen, dus een echt antwoord kan zonder dat veld binnenkomen. De hub's quoted replies beschrijft wanneer dat gebeurt en wat je doet als de classificatie moet kloppen.

De webhook-payload

whatsapp.received bevat de location-arm op de event-envelop:

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

Aandachtspunten

• Live locatiedeling wordt niet als content gemodelleerd. Wat binnenkomt is één locatie vastgelegd op één moment, dus een trackingweergave heeft niets om bij te werken. Bouw er geen op dit veld.
• Een integratie die alleen interactive_reply bewaakt mist dit. Het antwoord op een locatieverzoek komt hier binnen en het antwoord op een contactgegevensverzoek komt binnen op contact_cards, dus een handler die alleen taps leest mist beide.
• Coördinaten zijn wat het apparaat van het contact rapporteerde. Ze bevatten geen nauwkeurigheidsradius en geen hoogte, en een pin die het contact heeft versleept staat waar die is neergezet. Bevestig een adres in woorden als het correct moet zijn.

Vervolgstappen

• Hoe ontvangen werkt: de inkomende envelop, media ophalen en de whatsapp.received-webhook
• WhatsApp-locatieberichten: de verzendzijde van dezelfde arm
• WhatsApp-locatieverzoeken: de knop die om een pin vraagt
• WhatsApp webhooks: elk event waarop je je kunt abonneren