Sign inGet started

WhatsApp-locatieverzoeken

Een locatieverzoek plaatst één knop onder een WhatsApp-bericht die de ontvanger vraagt om te delen waar ze zijn. Gebruik het wanneer je een actuele positie nodig hebt, zoals een ophaallocatie, in plaats van een opgeslagen adres. Gebruik voor een telefoonnummer contactgegevensverzoeken.

Een locatieverzoek versturen

Stel interactive.type in op location_request_message, met een body_text en verder niets. WhatsApp rendert de knop zelf, dus er is niets om een label aan te geven:
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 is verplicht bij elk servicebericht: een nummer dat je werkruimte bezit, niet een door Bird beheerd nummer. Dit type benoemt geen eigen veld, en het schema verbiedt een header, een footer_text en elk veld van andere types (buttons, list, cta_url, cards) expliciet, dus body_text is het volledige bericht, met een maximum van 1024 tekens.
in_reply_to_message_id werkt ook bij dit type, om een eerder bericht in hetzelfde gesprek te quoten. Zie in de hub een bericht quoten om een antwoord te correleren voor hoe resolutie werkt en wat het kan missen.

De gedeelde locatie uitlezen

Een tik produceert geen interactive_reply. Het komt binnen als een gewoon inkomend location-bericht, dezelfde structuur die een contact dat spontaan zijn locatie deelt zou opleveren, dus een integratie die al inkomende locaties leest heeft geen nieuwe tak nodig voor dit type:
Codevoorbeeld
{
  "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"
}
Geen van de velden van location is verplicht: latitude en longitude zijn meestal allebei aanwezig, maar name ontbreekt als de ontvanger een kale pin heeft gedeeld, address verschijnt alleen als name ook is ingesteld, en url verschijnt alleen bij bedrijfslocaties die de client van de ontvanger toevallig meestuurt. Programmeer defensief in plaats van aan te nemen dat er een adres bij de pin zit. Je ziet dit antwoord via de berichtenlijst of GET /v1/whatsapp/messages/{id}; zie in de hub een antwoord lezen voor dat pad in zijn geheel.

Het antwoord koppelen aan de vraag

Meta stelt een context in op het antwoord van dit type die verwijst naar het verzoek dat het beantwoordt, dus het inkomende bericht bevat in_reply_to_message_id en je hebt geen eigen correlatiemechanisme nodig:
Codevoorbeeld
{
  "direction": "inbound",
  "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
  "location": { "latitude": 37.7793, "longitude": -122.4193 }
}
Zie een bericht quoten om een antwoord te correleren voor hoe die resolutie werkt en hoe een misser eruitziet.
Dit is het bewuste contrast met contactgegevensverzoeken: het antwoord van dat type bevat helemaal geen context, dus de in_reply_to_message_id ervan wordt nooit opgelost en correlatie valt terug op from plus timing. Het antwoord op een locatieverzoek wordt wél opgelost, dus in_reply_to_message_id is de betrouwbare manier om de gedeelde locatie te koppelen aan het verzoek dat erom vroeg.

Aandachtspunten

  • Het klantenservicevenster moet open zijn. Een locatieverzoek is een servicebericht en kan alleen binnen een open venster worden afgeleverd; zie in de hub klantenservicevenster. De venstercontrole faalt open, dus een 202 is geen bewijs dat het venster daadwerkelijk open was toen het bericht werd verzonden.
  • from moet een nummer zijn dat je werkruimte bezit. Als je het weglaat of een nummer opgeeft dat geen verbonden afzender is, wordt het verzoek afgewezen voordat de verzending wordt aangemaakt.
  • Een antwoord is niet gegarandeerd. De ontvanger kan het locatiedelingsscherm wegklikken, het bericht helemaal negeren, of een adres als vrije tekst intypen, wat binnenkomt als een gewoon inkomend tekstbericht zonder location. Meta documenteert geen signaal voor een geweigerde of weggeklikte deling, dus behandel het verzoek als fire-and-forget en stel zelf een time-out in in plaats van te wachten op een antwoord dat misschien nooit komt.
  • Een gedeelde pin kan alleen coördinaten bevatten. De client van de ontvanger bepaalt of er een naam en adres worden meegegeven; een kale pin heeft geen van beide, dus ga er niet vanuit dat het een bij het ander hoort.
  • Geen header, geen footer en geen eigen veld. Het schema verbiedt een header en footer_text bij dit type expliciet, en er is geen veld om de knop mee te labelen. Eventuele kleine lettertjes moeten in body_text staan.
  • Het antwoord is een location-bericht, geen interactive_reply. Een integratie die alleen interactive_reply controleert op een tik mist dit type volledig; controleer in plaats daarvan inkomende location.
Alles wat het schema hier kan uitdrukken, een te lange body_text, een header, een footer_text, of een van buttons, list, cta_url, cards, is een gewone request-validatiefout zonder cataloguscode. Een quote die niet wordt opgelost laat het verzoek falen voordat er iets wordt aangemaakt of in rekening gebracht: 404 E15071 als het id geen bericht benoemt dat deze werkruimte bevat, 422 E15072 als het een bericht benoemt dat niet gequoot kan worden. Zie in de hub fouten voor de volledige interactieve foutentabel en WhatsApp-berichten versturen voor de fouten die elke WhatsApp-verzending kan tegenkomen.

Volgende stappen