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

Exemple de code

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

Champ	Ce qu'il porte
latitude	Latitude en degrés décimaux
longitude	Longitude en degrés décimaux
name	Le nom du lieu ; absent quand le contact a partagé un simple point
address	L'adresse postale, que WhatsApp envoie uniquement avec un name
url	Un lien vers le lieu, principalement pour un emplacement professionnel, quand le client de l'expéditeur en a fourni un

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 :

Exemple de code

{
  "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
Événements WhatsApp : la liste complète des événements, via API ou les webhooks

Ressources associées

Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.

Regarder le guideConnecting WhatsApp to Bird: from buying a number to a live channel Comprendre le conceptWhat is the 24-hour customer service window on WhatsApp?Utiliser l'outilWhatsApp message builder Explorer la fonctionnalitéWhatsApp

Essayez la pratique et obtenez un guide d'implémentation