Sign inGet Started

Aturan kata kunci WhatsApp

Bird menyediakan katalog kata kunci, sehingga penerima yang membalas STOP ke salah satu nomor Anda yang dapat menerima pesan masuk langsung berhenti berlangganan tanpa pengaturan apa pun dari Anda. START membatalkannya. Aturan Anda sendiri menggantikan aturan bawaan Bird untuk cakupan yang diaturnya.

Halaman ini menjelaskan apa yang dikenali Bird, cara pesan masuk dicocokkan, serta cara mengubah kata-kata balasan atau menambahkan kata kunci. Padanannya di dasbor adalah halaman Keywords.

Daftar aturan kata kunci, dengan aturan workspace di atas aturan bawaan yang digantikannya

Kata yang dikenali Bird secara bawaan

Sembilan kata mencatat penghentian langganan:

stop, stop all, stopall, unsubscribe, cancel, end, quit, revoke, optout

Dua kata membatalkannya: start dan unstop.

Pencocokan dilakukan pada seluruh pesan, bukan pada sebagian teksnya. Karena cancel dan end adalah kata kunci, perbedaan ini penting: "cancel my 3pm delivery" adalah pesan biasa, bukan penarikan persetujuan. Huruf besar-kecil, aksen, spasi berulang, dan tanda baca di akhir diabaikan, sehingga Stop! dan STOP sama-sama cocok. Tanda baca di depan atau di dalam kata tidak diabaikan, sehingga #stop tidak cocok.

Kapan kata kunci tidak dicocokkan

Kata kunci di dalam pesan grup dilewati, sehingga peserta tidak dapat berhenti berlangganan dengan membalas di sana. Hormati permintaan berhenti berlangganan yang dinyatakan anggota grup dalam logika pengiriman Anda sendiri.

Kapan preferensi dicatat

Klasifikasi berjalan bersamaan dengan peristiwa whatsapp.received, bukan sebelumnya. Karena itu, integrasi yang memantau peristiwa tersebut dapat melihat STOP tiba sebelum preferensi yang dicatatnya ada. Jika handler Anda menanggapi pesan masuk dengan mengirim sesuatu, baca ulang catatan penerima alih-alih mengandalkan urutan peristiwa.

Melihat aturan yang berlaku

GET /v1/whatsapp/keyword-rules menjelaskan cara balasan ke nomor Anda ditangani. Tanpa filter, endpoint ini mengembalikan satu baris per cakupan: aturan Anda jika Anda memilikinya, dan aturan Bird jika tidak. Aturan Anda tanpa waba menggantikan aturan Bird untuk operasi dan negara yang sama. Persempit hasilnya dengan country, waba, operation, atau scope:

  • scope=system mengembalikan katalog Bird, termasuk aturan default yang digantikan oleh aturan Anda.
  • scope=workspace mengembalikan aturan Anda sendiri.
const rules = await bird.whatsapp.keywordRules.list({ operation: "opt_out" });
for (const rule of rules.data ?? []) {
  console.log(rule.scope, rule.effective_keywords);
}

Aturan dikembalikan mulai dari yang paling spesifik, yaitu urutan pencocokan pesan masuk terhadap aturan tersebut. Setiap aturan memuat effective_keywords: kumpulan kata kunci Bird untuk operasi dan negara tersebut, dikurangi yang Anda hapus, ditambah yang Anda tambahkan.

Untuk aturan Anda sendiri tanpa country, effective_keywords menampilkan kumpulan kata kunci global Bird, karena aturan tersebut tidak memiliki negara dan negara pengirim baru diketahui saat pesan tiba. Aturan itu mencocokkan pesan dengan kumpulan kata kunci Bird untuk negara pengirim, yang bisa lebih besar. Tetapkan country pada aturan Anda untuk melihat persis kata kunci yang berlaku bagi pengirim tersebut.

country adalah negara pengirim, yang ditentukan dari nomor telepon pengirim sendiri, bukan dari nomor yang mereka kirimi pesan. Ini adalah sinyal negara yang dikirim WhatsApp. Pengirim yang diidentifikasi dengan ID pengguna berbasis bisnis tidak membawa negara, sehingga pesannya melewati aturan berbasis negara dan dicocokkan dengan aturan global.

Mengubah balasan

Balasan default Bird sudah benar tetapi bersifat umum. Untuk membalas atas nama Anda sendiri, buat aturan:

const rule = await bird.whatsapp.keywordRules.create({
  operation: "opt_out",
  country: "US", // the SENDER's country, from their own number
  reply: "You're off the list. ACME Courier won't message you again.",
});
// effective_keywords is Bird's set plus any of your own.
console.log(rule.id, rule.effective_keywords);

Aturan Anda menggantikan balasan Bird untuk cakupan tersebut dan tetap mempertahankan kata kunci Bird. keywords Anda bersifat tambahan, bukan pengganti, sehingga kata kunci yang ditambahkan Bird kemudian langsung mulai dicocokkan tanpa perubahan apa pun dari Anda.

Untuk tidak mengirim balasan apa pun sambil tetap mencatat opt-out, hilangkan reply saat Anda membuat aturan. Untuk membungkam aturan yang sudah ada, atur reply ke null dalam body JSON pada pembaruan di bawah; flag CLI tidak dapat membawa null.

Dialog aturan kata kunci yang mencantumkan kata kunci Bird, kata kunci yang ditambahkan, kata kunci yang dihapus, dan balasan

Menambahkan kata kunci Anda sendiri

// Omitting keywords leaves the set alone; an empty array clears your additions
// back to Bird's. reply: null switches the auto-reply off and still records
// the opt-out.
const rule = await bird.whatsapp.keywordRules.update("wkr_01m2kj8x4te9p0rr7e5w2n1abc", {
  keywords: ["no more texts", "remove me"],
});
console.log(rule.effective_keywords);

Jika keywords dihilangkan, tambahan Anda tidak berubah. Jika Anda mengirim array kosong, tambahan tersebut dihapus sehingga yang berlaku kembali hanya set Bird.

Menghapus kata kunci Bird

Beberapa percakapan memerlukan cancel atau stop sebagai kata biasa, misalnya alur bot yang menggunakan cancel untuk membatalkan langkah ini. Cantumkan kata-kata tersebut di excluded_keywords pada aturan Anda:

Contoh kode
curl -X POST https://us1.platform.bird.com/v1/whatsapp/keyword-rules \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"operation":"opt_out","waba":"102290129340398","excluded_keywords":["cancel","end"]}'

Setelah itu, pesan yang isinya persis salah satu kata tersebut tidak membuat siapa pun berhenti berlangganan dan tidak mendapat balasan bagi orang-orang yang dicakup aturan. Pesan tetap sampai kepada Anda seperti biasa, dan aturan milik Bird juga tidak memprosesnya. Kecualikan semua kata kunci Bird untuk menonaktifkannya. Kata kunci yang ditambahkan Bird kemudian tetap dicocokkan, kecuali aturan Anda sudah mengecualikannya. Jika kata kunci dihapus, Anda sendiri bertanggung jawab menghormati permintaan berhenti berlangganan yang disampaikan melalui kata kunci tersebut. Tombol berhenti berlangganan milik Meta pada template pemasaran tetap berfungsi.

Pada pembaruan, excluded_keywords menggantikan set yang dihapus, array kosong berarti tidak ada yang dihapus, dan jika dihilangkan, set tidak berubah. Sebuah kata kunci tidak dapat sekaligus ditambahkan dan dikecualikan. Setiap kata kunci yang dikecualikan harus merupakan salah satu kata kunci Bird untuk operasi aturan tersebut. Untuk aturan yang memiliki country, kata kunci itu harus merupakan salah satu kata kunci Bird untuk negara tersebut, atau kata kunci global Bird jika Bird tidak memiliki kata kunci untuk negara itu. Bird menolak kata lain dengan 422, karena jika tidak, kata tersebut akan ikut dihapus apabila Bird menambahkannya kemudian.

Cakupan aturan dan duplikat

Aturan dapat dipersempit ke satu Business Account WhatsApp dengan waba, ke satu negara pengirim dengan country, ke keduanya, atau tidak keduanya. Anda memiliki satu aturan untuk setiap kombinasi operasi, negara, dan akun. Penulisan kedua untuk kombinasi yang sama menghasilkan kesalahan duplikat.

Bird menolak aturan yang mengikat stop ke opt_in, baik kata tersebut berasal dari katalog Bird maupun dari aturan Anda yang lain, sehingga kata opt-out tidak dapat dijadikan pemberi persetujuan.

Menghapus aturan

Jika Anda menghapus aturan, cakupannya diserahkan ke aturan berikutnya dalam urutan pencocokan, dan aturan itu belum tentu milik Anda. Urutannya:

  1. Aturan Anda untuk satu akun dan negara.
  2. Aturan Anda untuk akun tersebut.
  3. Aturan Anda untuk negara tersebut.
  4. Aturan Bird untuk negara pengirim.
  5. Aturan global Anda.
  6. Aturan global Bird.

Karena itu, jika Anda menghapus aturan untuk suatu negara, cakupannya diserahkan ke aturan Bird untuk negara tersebut, bukan ke aturan global Anda sendiri:

// The next rule in the ladder answers the scope, which is another rule of yours if you hold a less specific one.
await bird.whatsapp.keywordRules.delete("wkr_01m2kj8x4te9p0rr7e5w2n1abc");

Menghapus aturan mengembalikan teks balasan dan kumpulan kata kunci ke aturan mana pun yang berada berikutnya dalam urutan tersebut. Jika aturan itu adalah aturan Anda yang mengecualikan stop, STOP juga tidak berpengaruh di sana.

Langkah berikutnya

  • Preferensi: catatan yang dibuat oleh kata kunci, dan catatan mana yang dapat Anda batalkan.
  • Supresi: alamat yang diblokir langsung oleh workspace Anda.