Kapan REST API tepat dipakai, cara kerja kunci API, streaming, webhook, batas laju, dan daftar periksa keamanan sebelum integrasi Anda tayang.
Fitur bawaan sering sudah cukup untuk menaruh agen AI di WhatsApp atau chat situs web. Namun ada saatnya Anda ingin agen tampil di aplikasi sendiri, mengirim data ke sistem pesanan, atau memicu alur kerja internal. Di titik itu REST API menjadi alat yang tepat. Artikel ini membahas kapan API layak dipakai, komponen yang tersedia, batas laju yang perlu dihormati, pola desain yang aman, serta cara menguji sebelum tayang.
Kapan API tepat dipakai (dan kapan tidak)
Pertanyaan pertama bukan "bagaimana memakai API", melainkan "apakah saya memang memerlukannya". Banyak kebutuhan sudah terlayani oleh jalur bawaan, dan jalur bawaan lebih murah dirawat.
API masuk akal jika:
- Anda punya aplikasi sendiri (aplikasi seluler, portal pelanggan, dasbor internal) dan ingin agen tampil di dalamnya dengan antarmuka buatan Anda.
- Anda perlu menyambungkan percakapan ke sistem yang tidak tersedia sebagai konektor, misalnya ERP lokal atau aplikasi kasir buatan sendiri.
- Anda ingin menerima kejadian dari AI SNS CHAT secara otomatis, lalu memprosesnya di sistem Anda.
API sebaiknya tidak dipilih jika:
- Anda hanya ingin agen menjawab di WhatsApp, Messenger, Instagram, Telegram, atau widget situs web. Semua itu sudah tersedia di menu Channels tanpa satu baris kode.
- Anda hanya perlu mengumpulkan data calon pelanggan. Aksi "Collect leads" dan formulir kustom sudah melakukannya, dan hasilnya otomatis menjadi kontak.
- Tim Anda tidak punya orang yang bisa merawat kode. Integrasi custom perlu dipantau, diperbarui, dan diamankan.
Komponen dasarnya
Ada tiga komponen yang perlu Anda pahami sebelum mulai.
Kunci API
Kunci dibuat di Workspace settings → API keys. Kunci hanya ditampilkan sekali saat dibuat, jadi simpan langsung di tempat aman seperti pengelola rahasia atau variabel lingkungan server. Kunci bisa dicabut kapan saja. Fitur ini tersedia mulai paket Hobby, sedangkan paket Free tidak mencakupnya.
API REST berformat JSON
Permintaan dan respons memakai JSON, sehingga mudah dipanggil dari bahasa pemrograman apa pun. Untuk daftar lengkap endpoint dan parameter, rujuk dokumentasi referensi API yang menyertai akun Anda. Artikel ini sengaja tidak mengulang detail teknis itu agar tidak usang bila ada pembaruan.
Streaming dan webhook
Bila Anda menambahkan stream=1, jawaban dikirim bertahap lewat SSE (Server-Sent Events). Pengguna melihat kata demi kata muncul, seperti di aplikasi chat modern, tanpa menunggu jawaban utuh. Untuk arah sebaliknya, AI SNS CHAT mengirim webhook bertanda tangan HMAC dan menyimpan log pengiriman, sehingga Anda bisa memeriksa mana yang sampai dan mana yang gagal.
Hormati batas laju yang dipublikasikan
Batas laju yang dipublikasikan saat ini:
| Jalur | Batas |
|---|---|
| Autentikasi | 20 permintaan per 5 menit per IP |
| Chat publik | 30 permintaan per menit per IP |
| Polling | 120 permintaan per menit |
Perhatikan kata "per IP". Bila semua permintaan lewat server backend Anda, bagi AI SNS CHAT semuanya tampak datang dari satu alamat. Sebagai contoh hipotetis, sebuah toko online yang mengarahkan seluruh pengunjung lewat satu server bisa mencapai 30 permintaan chat per menit saat kampanye gajian, padahal tiap pengunjung hanya mengirim satu pesan. Rancang aplikasi dengan asumsi ini.
Beberapa kebiasaan yang membantu:
- Utamakan streaming dan webhook ketimbang polling. Polling yang terlalu rapat menghabiskan jatah tanpa menambah nilai.
- Terapkan antrean di sisi Anda, dan beri jeda yang bertambah (exponential backoff) bila permintaan ditolak.
- Jangan mencoba login berulang dalam gelombang. Batas autentikasi lebih ketat karena memang ditujukan menahan penyalahgunaan.
- Tampilkan pesan yang sopan kepada pelanggan saat sistem sibuk, misalnya "Mohon tunggu sebentar", bukan layar kosong.
Pola desain yang berhasil
- 01Pelanggan (WhatsApp, situs, aplikasi)
- 02Backend Anda (kunci API tersimpan aman)
- 03AI SNS CHAT (agen menjawab, streaming SSE)
- 04Webhook bertanda tangan kembali ke sistem Anda
1. Selalu lewat backend
Jangan menaruh kunci API di aplikasi seluler atau kode JavaScript yang dilihat pengunjung. Siapa pun bisa mengekstraknya. Letakkan kunci di server Anda, dan biarkan aplikasi klien hanya berbicara dengan server itu.
2. Webhook sebagai pemicu, bukan sumber kebenaran tunggal
Anggap webhook sebagai pemberitahuan "ada yang berubah". Simpan data pentingnya, tetapi siapkan cara untuk menyinkronkan ulang bila ada pengiriman yang terlewat. Log pengiriman membantu Anda mengetahui kapan itu terjadi.
3. Buat penanganan webhook idempoten
Webhook yang sama bisa saja diterima dua kali, misalnya saat Anda membalas lambat lalu pengirim mencoba lagi. Pastikan memproses kejadian yang sama dua kali tidak membuat pesanan ganda atau tiket ganda. Simpan pengenal kejadian yang sudah diproses.
4. Balas cepat, kerjakan belakangan
Terima webhook, validasi, masukkan ke antrean, lalu segera balas sukses. Pekerjaan berat dikerjakan oleh pekerja terpisah. Pola ini menjaga Anda tetap sehat saat lonjakan trafik.
5. Gabungkan dengan serah-terima manusia
Serah-terima dari agen ke staf bisa dikirim sebagai peringatan ke webhook, selain ke Slack, Teams, LINE WORKS, WhatsApp, atau email. Contoh hipotetis: klinik gigi dengan beberapa cabang menerima peringatan itu di sistem antrean internalnya, lalu staf yang bertugas diberi tahu. Pembagian giliran sendiri diatur di Helpdesk → Scheduling.
Daftar periksa keamanan sebelum tayang
Sebelum membuka integrasi ke pelanggan sungguhan, periksa hal berikut:
- Kunci hanya di server. Tidak ada di repositori kode, tangkapan layar, atau pesan obrolan tim.
- Satu kunci per keperluan. Bila satu kunci bocor, Anda cukup mencabutnya tanpa mengganggu integrasi lain.
- Verifikasi tanda tangan HMAC pada setiap webhook. Hitung tanda tangan dari isi mentah permintaan memakai rahasia bersama, lalu bandingkan dengan yang dikirim. Tolak yang tidak cocok.
- Gunakan HTTPS untuk alamat penerima webhook.
- Jangan mencatat rahasia di log aplikasi Anda. Sisi AI SNS CHAT menyamarkan rahasia dari lognya, dan sebaiknya Anda melakukan hal yang sama.
- Batasi akses manusia. Beri anggota tim peran yang sesuai (Owner, Co-owner, Member, Support, Viewer), dan aktifkan autentikasi dua faktor (TOTP).
- Pantau Workspace settings → Activity. Pemilik dan admin dapat melihat siapa membuat, mengubah, atau menghapus sesuatu.
- Aktifkan filter perlindungan pesan per agen (prompt injection dan penyalahgunaan), terutama bila agen terbuka untuk umum.
Praktik keamanan platform dirancang dengan mengacu pada GDPR dan APPI. Ringkasannya ada di halaman keamanan, termasuk keterangan tentang sertifikasi yang tidak dimiliki. Bila bisnis Anda punya kewajiban pelindungan data pribadi, tinjau juga alur data di sisi aplikasi Anda sendiri.
Pengujian dan peluncuran bertahap
Integrasi yang baik diluncurkan pelan-pelan.
- Gunakan agen terpisah untuk uji coba. Fitur Duplicate menyalin persona, model, dan data pelatihan (tanpa percakapan), jadi Anda punya salinan aman untuk bereksperimen.
- Uji alur dulu di Playground. Pastikan jawaban agen sudah sesuai sebelum menyambungkannya ke kode Anda.
- Simulasikan kegagalan. Matikan server penerima webhook sebentar, lalu lihat log pengiriman dan pastikan mekanisme sinkronisasi ulang Anda bekerja.
- Uji beban ringan terhadap batas laju. Pastikan antrean dan backoff berjalan sebelum kampanye besar.
- Luncurkan ke sebagian kecil pengguna dulu. Misalnya hanya satu halaman produk atau satu kelompok pelanggan setia.
- Pantau Activity → Chat logs. Gunakan penilaian jempol atas dan bawah untuk melihat kualitas jawaban, dan perbaiki jawaban yang kurang tepat agar agen belajar darinya.
Sebagai gambaran hipotetis, sebuah bimbingan belajar daring bisa memulai dari satu kelas percobaan berisi puluhan siswa. Setelah seminggu tanpa kendala, barulah integrasi dibuka untuk seluruh kelas.
Bila ada perubahan agen yang berakibat buruk, titik pemulihan (restore point, hingga 40 per agen) memungkinkan Anda kembali ke versi sebelumnya.
Menerapkannya di AI SNS CHAT
Berikut langkah praktisnya.
- Pastikan paket Anda Hobby atau lebih tinggi. Kunci API dan integrasi memerlukannya. Rincian paket ada di halaman harga.
- Siapkan agen dan sumber pengetahuannya. Isi melalui menu Data sources (berkas, teks, situs web, tanya-jawab, dan lainnya), lalu uji di Playground.
- Buat kunci API di Workspace settings → API keys. Salin langsung karena kunci hanya tampil sekali, lalu simpan di pengelola rahasia server Anda.
- Bangun backend perantara. Backend memanggil API, memakai
stream=1bila Anda ingin jawaban tampil bertahap, dan meneruskan hasilnya ke aplikasi Anda. - Daftarkan penerima webhook, lalu verifikasi tanda tangan HMAC pada setiap permintaan masuk. Gunakan log pengiriman untuk menelusuri kegagalan.
- Sambungkan serah-terima. Atur giliran di Helpdesk → Scheduling (memerlukan paket Standard atau lebih tinggi) dan pilih tujuan peringatan, termasuk webhook.
- Pantau hasilnya di Activity → Chat logs dan halaman Usage. Satu balasan memakai satu kredit, sehingga lonjakan trafik terlihat jelas di sana.
Perlu diingat bahwa Anda tidak memerlukan API untuk kanal yang sudah tersedia. WhatsApp, Messenger, Instagram, Telegram, dan widget situs web dipasang dari menu Channels. Daftar koneksi yang sudah tersedia bisa dilihat di halaman koneksi, dan gambaran fitur lainnya di halaman fitur. Bila Anda ingin menjajalnya dulu, daftar akun dan kenali agen di Playground sebelum merencanakan integrasi.
Bila Anda bingung harus mengatur apa, Synthia, manajer armada agen berbasis AI di dasbor, dapat memandu Anda ke layar yang tepat dan menyorot kontrol yang perlu diklik.
Kesimpulan
REST API memberi Anda keleluasaan, tetapi juga tanggung jawab tambahan. Pilih jalur bawaan selama cukup, dan gunakan API untuk celah yang tidak terjangkau. Simpan kunci di server, hormati batas laju, verifikasi setiap webhook, dan luncurkan bertahap sambil memantau log. Dengan disiplin itu, integrasi kustom Anda bisa tumbuh tanpa mengorbankan keamanan maupun kenyamanan pelanggan.
Pertanyaan umum
Paket apa yang diperlukan untuk memakai REST API?
Kunci API tersedia mulai paket Hobby. Paket Free tidak mencakupnya. Kunci dibuat di Workspace settings → API keys, hanya tampil sekali, dan bisa dicabut kapan saja.
Apakah saya bisa menampilkan jawaban secara streaming di antarmuka sendiri?
Bisa. API mendukung streaming SSE dengan parameter stream=1, sehingga jawaban muncul bertahap di aplikasi Anda. Tetap panggil API dari backend agar kunci tidak terbuka di sisi klien.
Bagaimana saya tahu webhook benar-benar berasal dari AI SNS CHAT?
Webhook ditandatangani dengan HMAC. Hitung tanda tangan dari isi mentah permintaan memakai rahasia bersama, bandingkan dengan yang dikirim, dan tolak bila tidak cocok. Log pengiriman membantu Anda menelusuri kiriman yang gagal.
Apa saja batas lajunya?
Batas yang dipublikasikan: autentikasi 20 permintaan per 5 menit per IP, chat publik 30 permintaan per menit per IP, dan polling 120 permintaan per menit. Karena batasnya per IP, perhatikan bahwa lalu lintas lewat satu server backend tampak berasal dari satu alamat.
Apakah saya perlu API untuk memasang agen di WhatsApp atau Messenger?
Tidak. WhatsApp, Messenger, Instagram, Telegram, dan kanal lain tersedia langsung di menu Channels tanpa kode. API hanya diperlukan untuk kebutuhan khusus, seperti menampilkan agen di aplikasi sendiri atau mengolah kejadian di sistem internal.


