API Tools

Pengenalan

API Tools memungkinkan bot Anda berinteraksi dengan sistem eksternal melalui panggilan API. Alih-alih hanya merespons berdasarkan pengetahuan yang sudah ditentukan atau alur percakapan, bot Anda dapat mengambil, mengirim, atau memperbarui data real-time dari platform lain.

Ini memungkinkan bot Anda melampaui sekadar menjawab pertanyaan. Bot dapat melakukan tindakan dan memberikan respons dinamis berdasarkan data langsung.

Kasus Penggunaan Umum

API Tools dapat digunakan dalam berbagai skenario, seperti:

• Mengambil data pelanggan dari CRM atau database
• Memeriksa status pesanan atau transaksi
• Membuat atau memperbarui tiket di sistem eksternal
• Mengirim data ke platform pihak ketiga (misalnya, formulir, sistem pembayaran)

Cara Mengakses API Tools

Anda dapat mengakses API Tools dari area konfigurasi bot.

Buka:
Bots → Pilih bot Anda → Tools → API Tools

Dari tab ini, Anda dapat membuat, mengelola, dan mengonfigurasi integrasi API yang akan digunakan bot selama percakapan.

---

Penjelasan Form API Tools

Berikut adalah penjelasan setiap kolom untuk mengonfigurasi API Tool dan cara menggunakannya secara efektif.

Name

Kolom ini mendefinisikan nama API Tool Anda.

Gunakan nama yang jelas dan deskriptif agar mudah diidentifikasi tujuannya nanti, terutama jika Anda memiliki beberapa API Tools yang dikonfigurasi.

Contoh:
Get product price

Method

Ini menentukan metode HTTP yang digunakan untuk permintaan API.

Pilih metode berdasarkan kebutuhan endpoint API:

• GET → Mengambil data (misalnya, mengambil detail produk)
• POST → Mengirim atau membuat data (misalnya, mengirimkan formulir)
• PUT/PATCH → Memperbarui data yang sudah ada
• DELETE → Menghapus data

Pastikan metode yang dipilih sesuai dengan API yang diintegrasikan.

When should the API call be triggered?

Ini adalah salah satu kolom terpenting.

Definisikan kondisi atau skenario kapan bot harus memicu panggilan API ini. Bot akan menggunakan instruksi ini untuk memutuskan kapan harus mengeksekusi API secara otomatis selama percakapan.

Jadilah spesifik dan sertakan contoh intent pengguna.

Contoh yang baik:
Picu ketika pengguna menanyakan harga produk atau mengatakan sesuatu seperti "Saya ingin melihat harga"

Tips:

• Deskripsikan intent, bukan hanya frasa yang tepat
• Sertakan variasi cara pengguna mungkin bertanya
• Hindari terlalu samar (misalnya, "ketika pengguna menanyakan sesuatu")

Endpoint

Ini adalah URL API tempat permintaan akan dikirim.

Berikan endpoint yang lengkap dan valid, termasuk protokol (https://).

Contoh:
https://api.example.com/products/price

Pastikan:

• Endpoint dapat diakses
• Sesuai dengan metode HTTP yang dipilih
• Parameter query yang diperlukan sudah disertakan (jika berlaku)

Response Format

Kolom ini mendefinisikan cara bot menyajikan respons API kepada pengguna.

Anda memandu bot tentang cara menyusun output agar lebih mudah dibaca dan ramah pengguna.

Contoh:

• Sajikan data sebagai bullet points
• Format respons sebagai tabel
• Rangkum informasi utama dalam kalimat singkat
• Tampilkan instruksi langkah demi langkah jika diperlukan

Contoh instruksi:
Sajikan nama produk, harga, dan ketersediaan sebagai bullet points

Require Confirmation

Opsi ini menentukan apakah bot perlu konfirmasi pengguna sebelum mengeksekusi panggilan API.

• On → Bot akan meminta pengguna untuk konfirmasi sebelum mengirim permintaan API
• Off → Panggilan API akan dieksekusi segera tanpa konfirmasi

Ini berguna untuk tindakan yang mungkin memiliki konsekuensi, seperti mengirimkan data atau memicu transaksi.

Confirmation Expiry (Hours)

Kolom ini mendefinisikan berapa lama konfirmasi tetap berlaku setelah pengguna menyetujuinya.

Jika panggilan API tidak dieksekusi dalam waktu ini, konfirmasi akan kedaluwarsa dan bot mungkin perlu meminta konfirmasi lagi.

Contoh:
Jika diatur ke 1, konfirmasi berlaku selama 1 jam.

Escalate to Human Assistance

Aktifkan opsi ini untuk mentransfer percakapan ke agen manusia ketika panggilan API mengembalikan kode status respons tertentu.

• On → Bot akan mengekskalasi percakapan ketika respons API sesuai dengan kondisi yang ditentukan
• Off → Bot tidak akan mengekskalasi, terlepas dari respons API

Ini berguna ketika API mengembalikan error atau respons tak terduga yang tidak dapat ditangani bot dengan benar.

Contoh skenario:

• API mengembalikan 5XX (error server) → masalah sistem, memerlukan penanganan manusia
• API mengembalikan 401/403 (tidak terotorisasi) → memerlukan verifikasi manual
• API mengembalikan 400 (bad request) → input mungkin perlu klarifikasi

Eskalasi hanya akan dipicu jika kode status respons sesuai dengan kondisi yang ditentukan di kolom Escalation Conditions.

Headers

Bagian ini memungkinkan Anda menambahkan custom HTTP headers ke permintaan API Anda.

Headers digunakan untuk meneruskan informasi tambahan yang diperlukan oleh API, seperti kredensial autentikasi, tipe konten, atau konfigurasi lainnya.

Setiap header terdiri dari:

• Key → Nama header
• Value → Nilai yang terkait dengan header

Contoh umum:

• Authorization: Bearer <token> → Digunakan untuk autentikasi API
• Content-Type: application/json → Menentukan format request body
• Accept: application/json → Mendefinisikan format respons yang diharapkan

Klik + Add Header untuk menyertakan beberapa headers jika diperlukan API Anda.

Tips:

• Pastikan format header sesuai dengan dokumentasi API
• Periksa ulang typo, karena header yang salah dapat menyebabkan panggilan API gagal
• Jaga keamanan informasi sensitif (seperti token)

Chatbot Input

Bagian ini memungkinkan Anda mendefinisikan data yang perlu dikumpulkan atau diekstrak chatbot dari percakapan sebelum melakukan panggilan API.

Chatbot akan secara otomatis mengumpulkan informasi ini dari percakapan atau meminta pengguna jika informasi tersebut tidak tersedia.

Key

Ini adalah nama variabel yang akan digunakan dalam permintaan API.

Gunakan nama yang jelas dan deskriptif yang mewakili data yang dikumpulkan.

Contoh:
member_id, product_name, order_id

Type

Ini mendefinisikan tipe data input. Pilih tipe berdasarkan format yang diperlukan API Anda.

Tipe yang tersedia:

• String → Input berbasis teks (misalnya, nama, produk, ID)
• Number → Nilai numerik (misalnya, kuantitas, harga)
• Boolean → Nilai true/false (misalnya, is_member, is_active)
• Array → Daftar nilai (misalnya, beberapa ID produk atau pilihan)

Memilih tipe yang tepat memastikan data terstruktur dengan benar saat dikirim ke API.

Description

Berikan penjelasan yang jelas tentang untuk apa input ini digunakan.

Ini membantu chatbot memahami:

• Informasi apa yang harus diekstrak dari percakapan
• Kapan harus meminta input tersebut dari pengguna

Contoh:
member_id untuk mengakses detail akun atau memverifikasi status keanggotaan

Selectable Choices (Opsional)

Definisikan daftar nilai yang sudah ditentukan sebelumnya yang dapat dipilih chatbot.

• Nilai harus dipisahkan dengan koma
• Chatbot hanya dapat memilih satu nilai dari daftar
• Opsi ini hanya berlaku untuk tipe String

Contoh:
merah, biru, hijau

Gunakan ini ketika input harus dibatasi pada opsi tertentu.

Mandatory Input

Aktifkan opsi ini jika input diperlukan sebelum panggilan API dapat dilanjutkan.

• Aktif → Chatbot akan meminta pengguna untuk informasi ini jika tidak tersedia
• Nonaktif → Chatbot akan melanjutkan meskipun input tidak diberikan

Additional Payload

Kolom ini memungkinkan Anda menyertakan data tambahan dalam permintaan API yang tidak perlu dikumpulkan dari percakapan chatbot.

Biasanya digunakan untuk nilai statis atau yang sudah ditentukan sebelumnya yang diperlukan API.

Key

Ini adalah nama parameter yang akan dikirim dalam permintaan API.

Gunakan key yang tepat seperti yang diharapkan oleh API.

Contoh:
source, channel, api_key

Value

Ini adalah nilai yang ditetapkan pada key.

Anda dapat mendefinisikan nilai tetap yang akan selalu disertakan dalam permintaan API.

Contoh:
web, chatbot, 12345

---

Langkah Terakhir

Setelah melengkapi semua kolom dan konfigurasi yang diperlukan, klik Save & Activate untuk mengaktifkan API Tool.

Setelah diaktifkan, chatbot Anda akan dapat memicu panggilan API berdasarkan kondisi yang Anda definisikan dan menggunakan respons untuk membantu pengguna selama percakapan.

---

Praktik Terbaik

Untuk memastikan performa dan keandalan optimal:

• Uji API Tool Anda untuk memastikan berfungsi sesuai harapan
• Verifikasi bahwa semua kolom dan input yang diperlukan sudah dikonfigurasi dengan benar
• Pastikan endpoint API Anda dapat diakses dan responsif
• Gunakan kondisi pemicu yang jelas untuk menghindari panggilan API yang tidak disengaja
• Pantau respons untuk memastikan terformat dengan benar untuk chatbot