Sign inGet started

Permintaan info kontak WhatsApp

Permintaan info kontak menampilkan satu tombol di bawah pesan WhatsApp yang meminta penerima membagikan nomor telepon. Gunakan ini saat Anda membutuhkan nomor untuk menghubungi seseorang, misalnya untuk panggilan balik atau konfirmasi pemesanan, bukan alamat tersimpan. Untuk meminta lokasi, gunakan permintaan lokasi.

Mengirim permintaan info kontak

Atur interactive.type ke request_contact_info, 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: "request_contact_info",
    body_text:
      "To confirm your booking we need a number to reach you on. Tap below to share yours.",
  },
});
console.log(msg.id, msg.status);
from wajib ada di setiap pesan layanan: nomor yang dimiliki workspace Anda, bukan nomor yang dikelola Bird. Tipe ini tidak memiliki field khusus, 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. Meta tidak menyebutkan batas panjang body untuk tipe ini; Bird menerapkan batas 1.024 karakter yang berlaku untuk setiap tipe interaktif lain kecuali list menu.
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 kontak yang dibagikan

Ketukan tidak menghasilkan interactive_reply. Ketukan tiba sebagai pesan masuk biasa yang membawa array contact_cards:
Contoh kode
{
  "id": "wam_01kyb2m4xq7whs0d8n3prv6tez",
  "direction": "inbound",
  "from": { "phone_number": "+16505551234", "bsuid": "US.13491208655302741918" },
  "to": { "phone_number": "+13124495648" },
  "status": "received",
  "contact_cards": [
    {
      "origin": "contact_request",
      "phone_numbers": [{ "phone_number": "+14155550829", "type": "cell" }]
    }
  ],
  "created_at": "2026-08-26T10:00:00Z"
}
contact_cards adalah array, dan pesan contacts yang tidak membawa kartu terbaca sebagai [], bukan sebagai field yang tidak ada. Field yang sama membawa kartu yang Anda kirim, sehingga kartu yang menjawab permintaan ini dibedakan oleh origin, bukan oleh field tempat kartu itu tiba. Memeriksa origin wajib dilakukan sebelum memperlakukan kartu sebagai jawaban Anda. origin bernilai contact_request saat kartu menjawab permintaan ini, atau other saat kontak membagikan kartu tanpa diminta, yang mungkin menyebut pihak ketiga sepenuhnya dan bukan kontak itu sendiri. Ketukan hanya membawa phone_numbers[].{phone_number, type} dan tidak menyertakan vcard; objek kontak lengkap, dengan name, org, birthday, dan sisanya, hanya tiba di origin: "other". 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

Berbeda dari permintaan lokasi, Meta tidak menyertakan context pada balasan tipe ini, sehingga in_reply_to_message_id tidak terisi, bukan di-resolve. Korelasikan berdasarkan from ditambah kiriman terbaru Anda sendiri, atau terima bahwa Anda tidak bisa. Dua permintaan yang belum dijawab ke kontak yang sama tidak dapat dibedakan: tidak ada informasi pada balasan yang menyebutkan permintaan mana yang dijawab, sehingga workspace yang mengirim permintaan info kontak kedua sebelum yang pertama dijawab tidak dapat mengetahui kartu mana yang merespons permintaan mana.
Ini adalah perbedaan yang disengaja dengan permintaan lokasi: balasan tipe tersebut membawa context milik Meta sendiri, sehingga in_reply_to_message_id ter-resolve dan mekanisme mengutip pesan untuk mengorelasikan balasan di hub menghubungkan jawaban kembali secara otomatis. Balasan permintaan info kontak tidak memiliki mekanisme seperti itu.

Meminta melalui template

Pesan interaktif request_contact_info adalah padanan bebas format dari tombol template REQUEST_CONTACT_INFO, yang meminta kartu kontak yang sama tetapi dapat menjangkau penerima yang jendela layanan pelanggannya sudah tertutup. Gunakan pesan interaktif saat penerima baru saja mengirim pesan kepada Anda dan Anda ingin permintaan dirumuskan khusus untuk percakapan ini; gunakan tombol template saat jendela tertutup, atau saat permintaan disertakan dalam pesan yang sudah Anda kirim sebagai template. Lihat template WhatsApp untuk pengiriman dengan template.

Hal yang perlu diperhatikan

  • Jendela layanan pelanggan harus terbuka. Permintaan info kontak adalah pesan layanan, hanya dapat dikirim di dalam jendela yang terbuka; lihat jendela layanan pelanggan di hub. Pemeriksaan jendela bersifat gagal-terbuka, sehingga 202 bukan bukti bahwa jendela benar-benar terbuka saat pengiriman berlangsung.
  • from harus berupa nomor yang dimiliki workspace Anda, dan jendela yang harus terbuka terkait dengan nomor tersebut, bukan dengan workspace Anda secara keseluruhan.
  • Balasan tidak dapat dikaitkan dengan permintaan berdasarkan id. Tidak adanya context di sisi Meta berarti in_reply_to_message_id tidak terisi pada balasan; korelasikan berdasarkan from ditambah kiriman terbaru Anda sendiri.
  • Penolakan bersifat diam. WhatsApp menampilkan lembar berbagi kepada penerima, dan menutupnya tidak menghasilkan pesan maupun webhook sama sekali. Tidak adanya pesan contact_cards adalah satu-satunya sinyal, sehingga alur apa pun yang menunggu jawaban membutuhkan timeout sendiri, bukan event penolakan yang dipantau.
  • Tanpa header, tanpa footer, dan tanpa label tombol. Skema melarang header dan footer_text pada tipe ini, dan tidak ada field untuk melabeli tombol. Semua yang dibaca penerima harus ada di body_text.
  • Nomor yang dibagikan tidak dijamin sama dengan nomor yang digunakan kontak untuk chat. Meta memperingatkan bahwa ID pengguna dan nomor telepon tidak selalu cocok, jadi jangan asumsikan nomor yang dibagikan sama dengan from.phone_number. Nomor tersebut juga tidak dijamin dalam format E.164: Bird menormalisasinya jika dapat diuraikan dan meneruskannya apa adanya jika tidak.
  • Balasan adalah pesan contact_cards, bukan interactive_reply. Integrasi yang hanya memantau interactive_reply untuk ketukan akan melewatkan tipe ini sepenuhnya, begitu juga integrasi yang hanya memantau location masuk untuk tipe permintaan lainnya.
Semua yang dapat diekspresikan 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 dapat dikutip. Lihat error di hub untuk tabel error interaktif lengkap dan Mengirim pesan WhatsApp untuk error yang dapat terjadi pada pengiriman WhatsApp mana pun.

Langkah selanjutnya