Sign inGet started

Żądania lokalizacji WhatsApp

Żądanie lokalizacji umieszcza pod wiadomością WhatsApp jeden przycisk z prośbą o udostępnienie aktualnego położenia odbiorcy. Użyj go, gdy potrzebujesz bieżącej pozycji, na przykład punktu odbioru, a nie zapisanego adresu. Jeśli zamiast tego potrzebujesz numeru telefonu, użyj żądań informacji kontaktowych.

Wyślij żądanie lokalizacji

Ustaw interactive.type na location_request_message z body_text i niczym więcej. WhatsApp sam renderuje przycisk, więc nie ma czym go opisać:
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 jest wymagane w każdej wiadomości serwisowej: numer należący do Twojego obszaru roboczego, a nie zarządzany przez Bird. Ten typ nie definiuje własnego pola, a schemat wprost zabrania header, footer_text i każdego pola innego typu (buttons, list, cta_url, cards), więc body_text to cała wiadomość, ograniczona do 1024 znaków.
in_reply_to_message_id działa również z tym typem i pozwala cytować wcześniejszą wiadomość z tej samej konwersacji. Sprawdź w hubie cytowanie wiadomości w celu korelacji odpowiedzi, aby dowiedzieć się, jak działa rozwiązywanie i co może pominąć.

Odczytywanie udostępnionej lokalizacji

Dotknięcie nie generuje interactive_reply. Przychodzi jako zwykła wiadomość przychodząca location, o takim samym kształcie jak lokalizacja udostępniona przez kontakt z własnej inicjatywy, więc integracja, która już odczytuje przychodzące lokalizacje, nie potrzebuje nowej gałęzi dla tego typu:
Przykład kodu
{
  "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"
}
Żadne z pól location nie jest wymagane: latitude i longitude zwykle są obecne, ale name jest nieobecne, gdy odbiorca udostępnił zwykłą pinezkę, address pojawia się tylko wtedy, gdy name też jest ustawione, a url pojawia się tylko w lokalizacjach firmowych, które klient odbiorcy dostarczył. Pisz kod defensywnie zamiast zakładać, że adres przychodzi razem z pinezką. Tę odpowiedź widzisz na liście wiadomości lub przez GET /v1/whatsapp/messages/{id}; szczegóły znajdziesz w hubie w sekcji odczytywanie odpowiedzi.

Korelowanie odpowiedzi z pytaniem

Meta ustawia context w odpowiedzi tego typu, wskazując żądanie, na które odpowiada, więc wiadomość przychodząca zawiera in_reply_to_message_id i nie potrzebujesz własnego mechanizmu korelacji:
Przykład kodu
{
  "direction": "inbound",
  "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
  "location": { "latitude": 37.7793, "longitude": -122.4193 }
}
Sprawdź cytowanie wiadomości w celu korelacji odpowiedzi, aby dowiedzieć się, jak działa rozwiązywanie i jak wygląda brak trafienia.
To celowy kontrast z żądaniami informacji kontaktowych: odpowiedź tego typu nie zawiera w ogóle context, więc jego in_reply_to_message_id nigdy się nie rozwiązuje i korelacja opiera się na from plus czasie. Odpowiedź żądania lokalizacji rozwiązuje się prawidłowo, więc in_reply_to_message_id to niezawodny sposób na powiązanie udostępnionej lokalizacji z żądaniem, które o nią poprosiło.

Na co uważać

  • Okno obsługi klienta musi być otwarte. Żądanie lokalizacji to wiadomość serwisowa, dostarczalna tylko w otwartym oknie; sprawdź w hubie okno obsługi klienta. Sprawdzenie okna kończy się pozytywnie w razie wątpliwości, więc 202 nie jest dowodem, że okno faktycznie było otwarte w momencie wysyłki.
  • from musi być numerem należącym do Twojego obszaru roboczego. Pominięcie go lub podanie numeru, który nie jest podłączonym nadawcą, jest odrzucane jeszcze przed utworzeniem wysyłki.
  • Odpowiedź nie jest gwarantowana. Odbiorca może zamknąć ekran udostępniania lokalizacji, całkowicie zignorować wiadomość albo wpisać adres jako zwykły tekst, który przychodzi jako zwykła przychodząca wiadomość tekstowa bez location. Meta nie dokumentuje żadnego sygnału o odrzuceniu lub zamknięciu udostępniania, więc traktuj żądanie jako wystrzel i zapomnij i sam ustaw limit czasu po swojej stronie, zamiast czekać na odpowiedź, która może nigdy nie nadejść.
  • Udostępniona pinezka może zawierać wyłącznie współrzędne. Klient odbiorcy decyduje, czy dołączyć nazwę i adres; zwykła pinezka nie zawiera żadnego z nich, więc nie zakładaj, że jedno przychodzi razem z drugim.
  • Bez nagłówka, bez stopki i bez własnego pola. Schemat wprost zabrania header i footer_text w tym typie i nie ma pola do opisania przycisku. Wszelkie dodatkowe informacje, których potrzebujesz, muszą znaleźć się wewnątrz body_text.
  • Odpowiedź to wiadomość location, a nie interactive_reply. Integracja, która obserwuje tylko interactive_reply w oczekiwaniu na dotknięcie, całkowicie pominie ten typ; obserwuj przychodzące location.
Wszystko, co schemat może tu wyrazić: zbyt długi body_text, header, footer_text lub dowolne z buttons, list, cta_url, cards, to zwykły błąd walidacji żądania bez kodu katalogowego. Cytat, który się nie rozwiązuje, powoduje odrzucenie żądania zanim cokolwiek zostanie utworzone lub naliczone: 404 E15071, gdy id wskazuje wiadomość nieistniejącą w tym obszarze roboczym, 422 E15072, gdy wskazuje wiadomość, której nie można cytować. Sprawdź w hubie błędy, aby zobaczyć pełną interaktywną tabelę błędów, oraz Wysyłanie wiadomości WhatsApp, aby poznać błędy, na które może natrafić każda wysyłka WhatsApp.

Następne kroki