Tindakan: jawaban dari sistem Anda sendiri

Tindakan memungkinkan bot Anda mencari sesuatu di sistem Anda sendiri di tengah obrolan — di mana pesanan berada, kapan akan dikirim, apakah reservasi sudah dikonfirmasi. Pelanggan bertanya, bot mengumpulkan apa yang dibutuhkan, memanggil API Anda, dan menjawab dari hasil yang diterima, dalam bahasa pelanggan.

Berfungsi di mana pun bot Anda berjalan: widget situs web, tautan bot dan kode QR Anda, serta aplikasi Android, iOS, React Native, Flutter, dan Ionic. Tidak ada yang diinstal atau diperbarui — panggilan dilakukan dari server kami, sehingga kredensial API Anda tidak pernah sampai ke browser atau ponsel.

Sebelum memulai: siapa pun dapat mengobrol dengan bot Anda

Bot Anda adalah obrolan publik. Jika nomor pesanan saja cukup untuk melihat pesanan, siapa pun dapat mengetik nomor hingga ada yang cocok.

Bot membantu dengan tiga cara, tetapi tidak satu pun menggantikan pemeriksaan itu: bot hanya mengirim nilai yang benar-benar diketik pelanggan, membatasi jumlah pencarian dari satu obrolan atau satu alamat, dan Anda dapat memilih kolom respons mana yang boleh dilihatnya.

Menyiapkannya

Buka Tindakan di dasbor dan pilih Tindakan baru. Pemilik dan admin dapat melihat layar ini.

• Nama — untuk Anda sendiri, misalnya "Status pesanan".
• Kapan bot harus menggunakannya? — satu kalimat, seperti yang akan Anda sampaikan kepada rekan kerja baru: "Pelanggan menanyakan di mana pesanannya atau kapan akan tiba."
• Alamat API Anda — GET atau POST, dan alamat https://. Tulis {{order_id}} di tempat nilai akan diisi.
• Yang diminta bot dari pelanggan — hingga enam nilai. Masing-masing memiliki label dengan kata-kata Anda sendiri ("Nomor pesanan"), nama yang digunakan API Anda (order_id), dan jenis: teks apa pun, angka, alamat email, atau nomor telepon.
• Header — kunci API atau token Anda. Disimpan terenkripsi dan tidak pernah ditampilkan lagi.
• Hanya bagikan kolom ini ke bot — opsional. Sebutkan bagian respons yang boleh digunakan bot, misalnya status, eta, items[].name. Bagian lainnya dibuang sebelum AI melihatnya.

Tekan Uji, ketik nilai contoh, dan Anda akan melihat permintaan yang dikirim serta persis apa yang akan diterima bot. Lalu coba sungguhan di layar Uji: "Di mana pesanan saya 48213? Email saya asha@example.com".

Yang diterima API Anda

Dengan GET, nilai yang Anda tempatkan di alamat akan diisi dan sisanya ditambahkan ke query string:

GET https://api.yourshop.com/orders/48213?email=asha%40example.com

Dengan POST, nilai-nilainya menjadi body JSON:

POST https://api.yourshop.com/lookup
Content-Type: application/json

{"order_id":"48213","email":"asha@example.com"}

Setiap permintaan juga membawa header Anda sendiri beserta header berikut:

Yang perlu dikirim balik

Balas dalam 8 detik dengan JSON, atau satu baris singkat teks biasa.

• 200 beserta datanya — bot menjawab dari data itu. Buat tetap ringkas dan gunakan nama kolom yang jelas: {"status":"shipped","eta":"2 October"} lebih baik daripada kode internal.
• 404 jika tidak ada yang cocok — bot memberi tahu pelanggan dan meminta mereka memeriksa apa yang diketik.
• Respons lain, atau tidak ada balasan tepat waktu — bot meminta maaf, menawarkan detail kontak Anda, dan obrolan ditandai untuk Anda. Alasannya ditampilkan di layar Tindakan.

Pengalihan (redirect) tidak diikuti, dan respons di atas 256 KB tidak dibaca.

Periksa tanda tangan

Permintaan ditandatangani dengan cara Standard Webhooks, sehingga Anda dapat menggunakan pustaka yang sudah ada. Rahasia penandatanganan Anda ada di layar Tindakan.

Secara manual: gabungkan id, stempel waktu, dan body persis apa adanya dengan tanda titik, tandatangani hasilnya dengan HMAC-SHA256 menggunakan rahasia (bagian setelah whsec_, yang sudah di-decode dari base64), lalu bandingkan.

const crypto = require('crypto');

function isFromKeyda(req, rawBody, secret) {
  const id = req.headers['webhook-id'];
  const ts = req.headers['webhook-timestamp'];
  const given = String(req.headers['webhook-signature'] || '').replace(/^v1,/, '');
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // older than 5 minutes
  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
  const want = crypto.createHmac('sha256', key).update(`${id}.${ts}.${rawBody}`).digest('base64');
  return given.length === want.length
    && crypto.timingSafeEqual(Buffer.from(given), Buffer.from(want));
}

Untuk permintaan GET, body-nya kosong, sehingga teks yang ditandatangani diakhiri dengan tanda titik. Gunakan POST jika Anda ingin nilai-nilainya sendiri tercakup dalam tanda tangan.

Cara bot menggunakannya

• Bot menanyakan apa pun yang masih kurang, satu pertanyaan singkat setiap kali, dan mengingat apa yang dikatakan pelanggan sebelumnya dalam obrolan.
• Bot tidak pernah menebak nilai. Jika pelanggan tidak mengetiknya, bot akan bertanya.
• Satu pencarian per pesan. Jawaban tersimpan Anda tetap diprioritaskan, sehingga pertanyaan yang sudah Anda jawab sendiri tidak pernah memanggil API Anda.
• Jawaban dari pencarian tidak pernah digunakan ulang untuk pelanggan lain.
• Satu pencarian dihitung sebagai satu jawaban, sama seperti balasan lain yang ditulis AI.

Di Obrolan, jawaban yang berasal dari pencarian ditandai di bawahnya: tindakan mana yang dijalankan dan bagaimana hasilnya. Nilai yang diketik pelanggan hanya tersimpan di transkrip, tidak di tempat lain.

Batasan

Tindakan hanya membaca informasi. Jangan arahkan tindakan ke alamat yang mengubah sesuatu — membatalkan pesanan atau mengeluarkan pengembalian dana memerlukan langkah konfirmasi yang belum dimiliki bot.