Sign inGet started

Demandes de localisation WhatsApp

Une demande de localisation place un bouton sous un message WhatsApp qui invite le destinataire à partager sa position. Utilisez-la quand vous avez besoin d'une position actuelle, comme un point de prise en charge, plutôt que d'une adresse enregistrée. Pour demander un numéro de téléphone, utilisez les demandes d'informations de contact.

Envoyer une demande de localisation

Définissez interactive.type sur location_request_message, avec un body_text et rien d'autre. WhatsApp génère le bouton lui-même, il n'y a donc rien pour le libeller :
const msg = await bird.whatsapp.send({
  to: "+16505551234",
  from: "+13124495648",
  interactive: {
    type: "location_request_message",
    body_text:
      "Let's start with your pickup. Share your current location, or type an address instead.",
  },
});
console.log(msg.id, msg.status);
from est obligatoire sur chaque message de service : un numéro appartenant à votre espace de travail, pas un numéro géré par Bird. Ce type ne déclare aucun champ propre, et le schéma interdit un header, un footer_text, ainsi que tous les champs des autres types (buttons, list, cta_url, cards), donc body_text constitue l'intégralité du message, limité à 1024 caractères.
in_reply_to_message_id fonctionne toujours avec ce type, pour citer un message précédent dans la même conversation. Consultez dans le hub citer un message pour corréler une réponse pour comprendre comment la résolution fonctionne et ce qu'elle peut manquer.

Lire la position partagée

Un appui ne produit pas de interactive_reply. Il arrive sous forme de message location entrant ordinaire, avec la même structure que celle produite par un contact partageant sa position spontanément, donc une intégration qui lit déjà les positions entrantes n'a pas besoin d'une nouvelle branche pour ce type :
Exemple de code
{
  "id": "wam_01kyb2m4xq7whs0d8n3prv6tez",
  "direction": "inbound",
  "from": { "phone_number": "+16505551234" },
  "to": { "phone_number": "+13124495648" },
  "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:04:11Z"
}
Aucun des champs de location n'est obligatoire : latitude et longitude sont généralement tous deux présents, mais name est absent quand le destinataire a partagé un simple repère, address n'apparaît que quand name est également défini, et url n'apparaît que sur les adresses professionnelles que le client du destinataire a choisi de fournir. Codez de manière défensive plutôt que de supposer qu'une adresse postale accompagne le repère. Vous voyez cette réponse via la liste des messages ou GET /v1/whatsapp/messages/{id} ; consultez dans le hub lire une réponse pour le parcours complet.

Corréler la réponse avec la demande

Meta définit un context sur la réponse de ce type en nommant la demande à laquelle elle répond, de sorte que le message entrant porte in_reply_to_message_id et vous n'avez besoin d'aucun schéma de corrélation de votre côté :
Exemple de code
{
  "direction": "inbound",
  "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
  "location": { "latitude": 37.7793, "longitude": -122.4193 }
}
Consultez citer un message pour corréler une réponse pour comprendre comment cette résolution fonctionne et à quoi ressemble un échec.
C'est le contraste délibéré avec les demandes d'informations de contact : la réponse de ce type ne porte aucun context, donc son in_reply_to_message_id ne résout jamais et la corrélation se rabat sur from plus le timing. La réponse d'une demande de localisation résout bien, donc in_reply_to_message_id est le moyen fiable de relier la position partagée à la demande qui l'a sollicitée.

Points à surveiller

  • La fenêtre de service client doit être ouverte. Une demande de localisation est un message de service, livrable uniquement dans une fenêtre ouverte ; consultez dans le hub la fenêtre de service client. La vérification de la fenêtre échoue en mode ouvert, donc un 202 ne prouve pas que la fenêtre était réellement ouverte au moment de l'envoi.
  • from doit être un numéro appartenant à votre espace de travail. L'omettre, ou nommer un numéro qui n'est pas un expéditeur connecté, est rejeté avant la création de l'envoi.
  • Aucune réponse n'est garantie. Le destinataire peut fermer l'écran de partage de position, ignorer le message entièrement, ou taper une adresse en texte libre, qui arrive alors comme un message texte entrant ordinaire sans aucun location. Meta ne documente aucun signal pour un partage refusé ou fermé, donc traitez la demande comme envoyée sans attente et gérez un délai d'expiration de votre côté plutôt que d'attendre une réponse qui pourrait ne jamais arriver.
  • Un repère partagé peut ne contenir que des coordonnées. Le client du destinataire décide s'il joint un nom et une adresse ; un simple repère ne contient ni l'un ni l'autre, donc ne présumez pas que l'un accompagne l'autre.
  • Pas d'en-tête, pas de pied de page, et aucun champ propre. Le schéma interdit un header et un footer_text sur ce type, et il n'y a aucun champ pour libeller le bouton. Toute mention légale nécessaire doit figurer dans body_text.
  • La réponse est un message location, pas un interactive_reply. Une intégration qui ne surveille que interactive_reply pour détecter un appui manquera entièrement ce type ; surveillez plutôt les location entrants.
Tout ce que le schéma peut exprimer ici, un body_text trop long, un header, un footer_text, ou l'un quelconque de buttons, list, cta_url, cards, est un simple échec de validation de requête sans code catalogue. Une citation qui ne résout pas fait échouer la requête avant que quoi que ce soit ne soit créé ou facturé : 404 E15071 quand l'identifiant ne désigne aucun message détenu par cet espace de travail, 422 E15072 quand il en désigne un qui ne peut pas être cité. Consultez dans le hub les erreurs pour le tableau interactif complet des erreurs et Envoyer des messages WhatsApp pour les erreurs que tout envoi WhatsApp peut rencontrer.

Étapes suivantes