Recevoir des localisations WhatsApp

Un point qu'un contact partage arrive sous forme de message entrant portant location. La même branche répond à une demande de localisation que vous avez envoyée, le seul type interactif dont la réponse arrive ici plutôt que sur interactive_reply.

Ce que porte une localisation entrante

{
  "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 simple point posé sur la carte porte les deux coordonnées et rien d'autre : traitez name, address et url comme des informations décoratives que vous affichez quand elles sont présentes, pas comme des champs sur lesquels indexer. Lisez les coordonnées comme des nombres JSON, et attendez-vous à des valeurs négatives dans les hémisphères sud et ouest.

Une localisation qui répond à une demande de localisation

Quand le point répond à une demande de localisation que vous avez envoyée, WhatsApp signale la demande comme cible de la réponse et in_reply_to_message_id nomme le message qui portait le bouton. C'est ce qui relie une réponse à une question, et c'est la distinction avec une demande d'informations de contact, dont la réponse ne porte pas un tel lien.

Rien d'autre ne marque le point comme une réponse. Un contact qui partage sa localisation spontanément produit la même branche sans in_reply_to_message_id : une intégration qui surveille les réponses vérifie donc ce champ plutôt que la branche. Le champ n'est pas une garantie dans l'autre sens : WhatsApp ne marque pas chaque réponse, et la résolution peut échouer, de sorte qu'une réponse authentique peut arriver sans lui. La section réponses citées du hub explique quand cela se produit et comment procéder quand la classification doit tenir.

Le payload du webhook

whatsapp.received porte la branche location sur l'enveloppe de l'événement :

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

Points d'attention

• Le partage de localisation en temps réel n'est pas modélisé comme du contenu. Ce qui arrive est une localisation fixée à un instant donné : une vue de suivi n'a rien à mettre à jour. Ne construisez pas de suivi sur ce champ.
• Une intégration qui surveille uniquement interactive_reply passe à côté. La réponse à une demande de localisation arrive ici, et la réponse à une demande d'informations de contact arrive sur contact_cards : un gestionnaire qui ne lit que les taps perd les deux.
• Les coordonnées sont celles signalées par l'appareil du contact. Elles ne comportent ni rayon de précision ni altitude, et un point que le contact a déplacé se trouve là où il l'a déplacé. Confirmez une adresse en mots quand elle doit être exacte.

Étapes suivantes

• Fonctionnement de la réception : l'enveloppe entrante, la récupération des médias et le webhook whatsapp.received
• Messages de localisation WhatsApp : le côté envoi de la même branche
• Demandes de localisation WhatsApp : le bouton qui demande un point
• WhatsApp webhooks : tous les événements auxquels vous pouvez vous abonner