Sign inGet started

Pesan interaktif WhatsApp

Pesan interaktif adalah teks isi ditambah sesuatu yang bisa diketuk penerima: tombol WhatsApp, menu, tautan, kartu, atau permintaan lokasi atau detail kontak mereka. Jika jawaban template berarti Anda harus mengurai teks bebas, menu WhatsApp atau sekumpulan tombol WhatsApp memberikan penerima pilihan tetap dan mengembalikan nilai yang Anda tentukan. Halaman ini membahas kesamaan keenam jenis tersebut; halaman masing-masing jenis membahas bentuk wire dan batasannya sendiri.

Keenam jenis

JenisBird interactive.typeHeaderFooterMaks body
Tombol balasbuttonteks, gambar, video, dokumenya1024
Menu daftarlistteks sajaya4096
Tombol tautancta_urlteks, gambar, video, dokumenya1024
Carousel mediacarouseltidak ada pada pesan; gambar atau video per kartutidak1024 pesan, 160 per kartu
Permintaan lokasilocation_request_messagetidak adatidak1024
Permintaan info kontakrequest_contact_infotidak adatidak1024
Semua jenis bersifat free-form: hanya dapat dikirim di dalam jendela layanan pelanggan yang terbuka, dan tidak pernah ditinjau oleh Meta seperti halnya template.
Pesan interaktif adalah konten free-form, sehingga aturan jendela layanan pelanggan berlaku: lihat jendela layanan pelanggan untuk penjelasan dan respons yang dikembalikan saat jendela tertutup.
Setiap pengiriman interaktif juga memerlukan from, nomor yang dimiliki workspace Anda. Nomor terkelola Bird tidak mendukungnya, jadi pengiriman interaktif memerlukan nomor Anda sendiri yang sudah terhubung terlebih dahulu.

Arm konten interaktif

interactive adalah salah satu field konten yang saling eksklusif pada POST /v1/whatsapp/messages, di samping template, text, image, dan lainnya: tepat satu yang boleh ada pada sebuah pengiriman. Di dalam interactive, type menentukan varian mana dari keenam jenis yang digunakan, dan field milik varian tersebut membawa sisanya (buttons, list, cta_url, atau cards). Skema melarang field varian lainnya, sehingga mencampurkan dua varian pada satu pengiriman gagal validasi sebelum mencapai handler.
Untuk envelope permintaan, model respons 202, dan cara coba lagi yang aman, lihat Mengirim pesan WhatsApp alih-alih mengulangnya di halaman ini.
Berikut contoh pesan interaktif minimal: dua tombol WhatsApp pada pengiriman reply-buttons, satu bahasa pada satu waktu.
const msg = await bird.whatsapp.send({
  to: "+15551234567",
  from: "+13124495648",
  interactive: {
    type: "button",
    body_text: "Your gardening workshop is scheduled for 9am tomorrow.",
    buttons: [
      { type: "quick_reply", quick_reply: { slug: "change-booking", text: "Change" } },
      { type: "quick_reply", quick_reply: { slug: "cancel-booking", text: "Cancel" } },
    ],
  },
});
console.log(msg.id, msg.status);

Tombol

Empat dari enam jenis menempatkan tombol, dan semuanya menggunakan bentuk yang sama: objek terdiskriminasi yang type-nya adalah quick_reply atau cta_url, masing-masing membawa field bersarang dengan nama yang sama. Tombol quick_reply membawa slug dan text; tombol cta_url membawa text dan url. Jenis mana yang menerima bentuk tombol mana:
  • Tombol balas hanya mengirim tombol quick_reply, 1 sampai 3 buah.
  • Tombol tautan mengirim tepat satu tombol cta_url.
  • Carousel media menempatkan tombol di setiap kartu: satu tombol cta_url, atau hingga tiga tombol quick_reply, dan setiap kartu dalam carousel harus sama.
  • Menu daftar menggunakan baris di dalam seksi, bukan objek tombol ini, yang dibahas di halaman tersendiri.
slug pada tombol quick_reply adalah handle Anda sendiri untuk tombol tersebut. Nilai ini tidak pernah ditampilkan kepada penerima, hanya label text-nya yang terlihat, dan slug dikembalikan apa adanya pada balasan. Perjalanan bolak-balik inilah yang membuat balasan dapat dikorelasikan dengan tombol yang menghasilkannya, sehingga cukup dijelaskan sekali di sini, bukan di setiap halaman turunan.

Membaca balasan

Menekan tombol atau memilih baris menu mengirim pesan masuk tersendiri yang membawa objek interactive_reply. interactive_reply.type bernilai button atau list; apa pun nilainya, objek bersarangnya membawa slug dan text yang Anda deklarasikan, yaitu label yang diketuk dan benar-benar dilihat penerima. Dua jenis permintaan, permintaan lokasi dan permintaan info kontak, menjawab secara berbeda: balasan permintaan lokasi adalah pesan masuk lokasi biasa, dan balasan permintaan info kontak adalah kartu kontak masuk, bukan interactive_reply sama sekali.
Balasan sampai kepada Anda melalui daftar pesan dan GET /v1/whatsapp/messages/{id}, sama seperti pesan masuk WhatsApp lainnya. Untuk menindaklanjuti balasan saat tiba alih-alih polling, berlangganan webhook whatsapp.received: payload-nya membawa interactive_reply, sehingga sudah menyebutkan tombol atau baris yang diketuk. Menerima balasan interaktif membahas bentuk baca dari sebuah ketukan, payload webhook, dan ketukan yang tiba di arm lain.

Mengutip pesan untuk mengorelasikan balasan

in_reply_to_message_id pada pengiriman mengutip pesan sebelumnya dari percakapan yang sama, dan setiap pesan, terkirim maupun diterima, mengembalikannya saat dibaca. Ini adalah satu field untuk kedua arah.
Korelasi yang diberikan field ini bersifat asimetris. Ketukan pada tombol WhatsApp atau baris menu membawa context milik Meta sendiri, sehingga in_reply_to_message_id merujuk ke pesan yang menawarkannya. Kartu kontak bersama tidak membawa context sama sekali, sehingga tidak merujuk ke apa pun: Anda mengorelasikan balasan permintaan info kontak berdasarkan from dan waktu, bukan field ini.
Resolusi melewati message-context store, dan jika gagal ditemukan, field tersebut dihilangkan alih-alih dilaporkan. Di wire, ini tidak dapat dibedakan dari balasan yang tidak menjawab apa pun. Integrasi yang memerlukan korelasi andal sebaiknya tidak bergantung pada field ini saja: sertakan metadata Anda sendiri pada pengiriman dan cocokkan berdasarkan nilai tersebut.
Jendela waktu sebuah pesan masih dapat dikutip dibatasi hingga 15 hari; setelah itu pengiriman gagal dengan 404 E15071, karena Bird tidak lagi menyimpan provider id yang dibutuhkan kutipan. Mengirim pesan WhatsApp membahas field sisi pengiriman: panjangnya, resolusinya, dan bentuk permintaannya.

Error

Tiga kode error khusus untuk konten interaktif. Masing-masing hanya terpicu pada jenis yang memiliki field yang diperiksa, sehingga kolom keempat menyebutkan jenis mana yang benar-benar dapat memicu masing-masing error.
KodeStatusPenyebabBerlaku untuk
E15055 WhatsAppInteractiveLimitExceeded422Pesan melebihi batas untuk jenisnya; saat ini, lebih dari 10 baris di seluruh seksi daftar.Menu daftar saja
E15056 WhatsAppInteractiveDuplicateLabel422Dua tombol atau baris dalam pesan yang sama memiliki label yang sama.Semua jenis dengan tombol atau baris berlabel: tombol balas, menu daftar, carousel media
E15059 WhatsAppInteractiveCarouselButtonsMismatch422Kartu-kartu dalam carousel tidak semuanya membawa tombol yang sama.Carousel media saja
Setiap pengiriman interaktif juga dapat memicu error yang berlaku untuk pengiriman WhatsApp apa pun: jendela layanan pelanggan tertutup, pengirim tidak ada atau tidak valid, penerima tidak valid, atau konten ambigu. Error tersebut berlaku untuk semua jenis konten WhatsApp, bukan khusus pesan interaktif; lihat Mengirim pesan WhatsApp untuk daftarnya alih-alih menyalinnya di sini.

Langkah selanjutnya