Dokumentacja
Sign inGet started
Rozpocznij
Przewodniki
Referencja API
SDK
CLI
Baza wiedzy
Changelog

Odbieranie lokalizacji WhatsApp

Pinezka udostępniona przez kontakt przychodzi jako wiadomość przychodząca z gałęzią location. Ta sama gałąź przynosi odpowiedź na wysłane przez Ciebie żądanie lokalizacji, czyli jedyny typ interaktywny, którego odpowiedź trafia tutaj, a nie do interactive_reply.

Co zawiera przychodząca lokalizacja

Przykład kodu
{
  "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"
}
PoleCo zawiera
latitudeSzerokość geograficzna w stopniach dziesiętnych
longitudeDługość geograficzna w stopniach dziesiętnych
nameNazwa miejsca; brak, gdy kontakt udostępnił samą pinezkę
addressAdres ulicy, który WhatsApp wysyła tylko razem z name
urlLink do miejsca, głównie przy lokalizacji firmowej, gdy klient nadawcy go dostarczył
Sama pinezka postawiona na mapie zawiera tylko dwie współrzędne, więc traktuj name, address i url jako dekorację wyświetlaną, gdy jest obecna, a nie jako pola, na których opierasz logikę. Odczytuj współrzędne jako liczby JSON i spodziewaj się wartości ujemnych na półkuli południowej i zachodniej.

Lokalizacja będąca odpowiedzią na żądanie lokalizacji

Gdy pinezka jest odpowiedzią na wysłane przez Ciebie żądanie lokalizacji, WhatsApp wskazuje zapytanie jako cel odpowiedzi, a in_reply_to_message_id podaje wiadomość, w której znajdował się przycisk. To wiąże odpowiedź z pytaniem i odróżnia ją od żądania danych kontaktowych, którego odpowiedź nie zawiera takiego powiązania.
Nic innego nie oznacza pinezki jako odpowiedzi. Kontakt, który udostępnia lokalizację spontanicznie, generuje tę samą gałąź bez in_reply_to_message_id, więc integracja czekająca na odpowiedź sprawdza to pole, a nie gałąź. Pole nie daje gwarancji w drugą stronę: WhatsApp nie oznacza każdej odpowiedzi i rozpoznanie może nie zadziałać, więc prawdziwa odpowiedź może przyjść bez niego. Sekcja cytowane odpowiedzi w hubie opisuje, kiedy tak się dzieje i co robić, gdy klasyfikacja musi być pewna.

Payload webhooka

whatsapp.received zawiera gałąź location w kopercie zdarzenia:
Przykład kodu
{
  "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
  }
}

Na co uważać

  • Udostępnianie lokalizacji na żywo nie jest modelowane jako treść. Przychodzi jedna lokalizacja ustalona w jednym momencie, więc widok śledzenia nie ma czego aktualizować. Nie buduj go na tym polu.
  • Integracja obserwująca tylko interactive_reply tego nie zobaczy. Odpowiedź na żądanie lokalizacji trafia tutaj, a odpowiedź na żądanie danych kontaktowych trafia do contact_cards, więc handler odczytujący wyłącznie tapnięcia pominie obie.
  • Współrzędne pochodzą z urządzenia kontaktu. Nie zawierają promienia dokładności ani wysokości, a pinezka przeciągnięta przez kontakt jest tam, gdzie ją przeciągnął. Potwierdź adres słownie, gdy musi być poprawny.

Następne kroki

Powiązane zasoby

Kontynuuj z dokumentacją, przewodnikami i przykładami dotyczącymi tego tematu. Zasoby są w języku angielskim.

Obejrzyj przewodnikConnecting WhatsApp to Bird: from buying a number to a live channelZrozum koncepcjęWhat is the 24-hour customer service window on WhatsApp?Użyj narzędziaWhatsApp message builderPoznaj możliwościWhatsApp
Wypróbuj ćwiczenie i uzyskaj brief wdrożeniowy