Sign inGet started

Permintaan lokasi WhatsApp

Permintaan lokasi menampilkan satu tombol di bawah pesan WhatsApp yang meminta penerima membagikan lokasi mereka. Gunakan ini saat Anda membutuhkan posisi terkini, seperti titik penjemputan, bukan alamat tersimpan. Untuk meminta nomor telepon, gunakan permintaan info kontak.

Mengirim permintaan lokasi

Atur interactive.type ke location_request_message, dengan body_text dan tidak ada yang lain. WhatsApp merender tombol itu sendiri, jadi tidak ada yang perlu dilabeli:
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 wajib ada di setiap pesan layanan: nomor milik workspace Anda, bukan nomor yang dikelola Bird. Tipe ini tidak memiliki field tersendiri, dan skema melarang header, footer_text, serta semua field tipe lain (buttons, list, cta_url, cards), sehingga body_text adalah keseluruhan pesan, dibatasi 1.024 karakter.
in_reply_to_message_id tetap berfungsi pada tipe ini, untuk mengutip pesan sebelumnya dalam percakapan yang sama. Lihat mengutip pesan untuk mengorelasikan balasan di hub untuk cara resolusi bekerja dan apa yang bisa terlewat.

Membaca lokasi yang dibagikan

Ketukan tidak menghasilkan interactive_reply. Balasan tiba sebagai pesan inbound location biasa, dengan bentuk yang sama seperti kontak yang membagikan lokasi tanpa diminta, sehingga integrasi yang sudah membaca lokasi inbound tidak perlu cabang baru untuk tipe ini:
Contoh kode
{
  "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"
}
Tidak ada field location yang wajib diisi: latitude dan longitude biasanya keduanya ada, tetapi name tidak ada saat penerima membagikan pin polos, address hanya muncul saat name juga diisi, dan url hanya muncul pada lokasi bisnis yang kebetulan disertakan oleh klien penerima. Tulis kode secara defensif, jangan asumsikan alamat jalan selalu menyertai pin. Anda melihat balasan ini melalui daftar pesan atau GET /v1/whatsapp/messages/{id}; lihat membaca balasan di hub untuk jalur lengkapnya.

Mengorelasikan jawaban dengan pertanyaan

Meta menyetel context pada balasan tipe ini yang merujuk permintaan yang dijawab, sehingga pesan inbound membawa in_reply_to_message_id dan Anda tidak perlu skema korelasi sendiri:
Contoh kode
{
  "direction": "inbound",
  "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
  "location": { "latitude": 37.7793, "longitude": -122.4193 }
}
Lihat mengutip pesan untuk mengorelasikan balasan untuk cara resolusi bekerja dan seperti apa jika gagal.
Ini adalah perbedaan yang disengaja dengan permintaan info kontak: balasan tipe tersebut tidak membawa context sama sekali, sehingga in_reply_to_message_id-nya tidak pernah ter-resolve dan korelasi kembali ke from ditambah waktu. Balasan permintaan lokasi ter-resolve, sehingga in_reply_to_message_id adalah cara andal untuk menghubungkan lokasi yang dibagikan kembali ke permintaan yang memintanya.

Hal yang perlu diperhatikan

  • Jendela layanan pelanggan harus terbuka. Permintaan lokasi adalah pesan layanan, hanya dapat dikirim di dalam jendela yang terbuka; lihat jendela layanan pelanggan di hub. Pemeriksaan jendela bersifat fail-open, sehingga 202 bukan bukti bahwa jendela benar-benar terbuka saat pengiriman dilakukan.
  • from harus berupa nomor milik workspace Anda. Menghilangkannya, atau menyebut nomor yang bukan pengirim terhubung, akan ditolak sebelum pengiriman dibuat.
  • Balasan tidak dijamin. Penerima bisa menutup layar berbagi lokasi, mengabaikan pesan sepenuhnya, atau mengetik alamat sebagai teks bebas, yang tiba sebagai pesan teks inbound biasa tanpa location sama sekali. Meta tidak mendokumentasikan sinyal untuk berbagi yang ditolak atau ditutup, jadi perlakukan permintaan ini sebagai fire-and-forget dan atur timeout di sisi Anda sendiri daripada menunggu respons yang mungkin tidak pernah datang.
  • Pin yang dibagikan bisa hanya berisi koordinat. Klien penerima yang menentukan apakah nama dan alamat dilampirkan; pin polos tidak memiliki keduanya, jadi jangan asumsikan yang satu selalu menyertai yang lain.
  • Tidak ada header, tidak ada footer, dan tidak ada field tersendiri. Skema melarang header dan footer_text pada tipe ini, dan tidak ada field untuk melabeli tombol. Catatan kecil apa pun yang Anda butuhkan harus dimasukkan ke dalam body_text.
  • Balasan adalah pesan location, bukan interactive_reply. Integrasi yang hanya memantau interactive_reply untuk ketukan akan melewatkan tipe ini sepenuhnya; pantau location inbound sebagai gantinya.
Semua yang bisa dinyatakan skema di sini, body_text yang terlalu panjang, header, footer_text, atau salah satu dari buttons, list, cta_url, cards, adalah kegagalan validasi permintaan biasa tanpa kode katalog. Kutipan yang tidak ter-resolve menggagalkan permintaan sebelum apa pun dibuat atau dikenakan biaya: 404 E15071 saat id menyebut pesan yang tidak dimiliki workspace ini, 422 E15072 saat id menyebut pesan yang tidak bisa dikutip. Lihat errors di hub untuk tabel error interaktif lengkap dan Mengirim pesan WhatsApp untuk error yang bisa terjadi pada pengiriman WhatsApp apa pun.

Langkah selanjutnya