Chat SDK: Satu Bot untuk Slack, Teams, WhatsApp, dan Telegram

Chat SDK adalah library TypeScript open source dari Vercel untuk menulis logika bot sekali lalu menjalankannya di Slack, Microsoft Teams, Google Chat, Discord, Telegram, WhatsApp, dan platform lain. Artikel ini membahas cara kerjanya, cara menghubungkannya dengan model AI, perbedaan perilaku di tiap platform, dan kesalahan yang sering muncul di production.

Dipublikasikan 11 menit baca
Gelembung chat berwarna ungu dan biru dengan latar buram

Perusahaan yang ingin punya asisten untuk karyawan biasanya butuh bot di Slack atau Microsoft Teams. Perusahaan yang sama sering juga ingin bot untuk pelanggan di WhatsApp atau Telegram. Masing-masing platform punya format webhook sendiri, cara menampilkan tombol sendiri, aturan berbeda soal mengedit pesan, dan batasan sendiri soal siapa boleh mengirim pesan ke siapa. Dulu, mendukung dua atau tiga platform berarti memelihara dua atau tiga codebase. Chat SDK, yang dirilis Vercel sebagai paket npm bernama chat, mencoba menyatukan perbedaan itu di balik satu antarmuka. Artikel ini membahas apa yang sebenarnya dikerjakan library ini, bagaimana posisinya di samping model AI, dan detail apa saja yang tetap berbeda antarplatform, karena sebagian di antaranya baru terasa setelah pengguna sungguhan mulai memakai bot.

Chat SDK yang Mana?

Nama ini pernah dipakai untuk dua hal berbeda, jadi hasil pencarian sering membingungkan. Sampai awal 2026, Chat SDK di chat-sdk.dev merujuk ke template chatbot Next.js milik Vercel, yaitu aplikasi web siap pakai yang tampilannya mirip ChatGPT. Pada Februari 2026 Vercel merilis library baru dengan nama yang sama sebagai public beta, dan template tadi dipindah ke situs tersendiri. Kalau sebuah tutorial menggambarkan Chat SDK sebagai aplikasi chat berbasis web dengan daftar percakapan di samping, yang dimaksud adalah template. Artikel ini membahas library-nya.

Perlu jelas juga apa yang tidak dikerjakan library ini. Chat SDK tidak memanggil model bahasa. Itu tugas AI SDK, TanStack AI, atau client resmi dari penyedia model. Chat SDK mengurus sisi platform chat: menerima pesan, mencatat percakapan, dan mengirim balasan dalam format yang dimengerti tiap platform. Keduanya memang dirancang untuk dipakai bersama, tetapi menyelesaikan masalah yang berbeda.

Cara Kerjanya

Ada tiga bagian. Instance Chat bertugas sebagai koordinator: menyimpan handler dan meneruskan event yang masuk ke handler yang tepat. Adapter mengerjakan urusan khusus platform, satu paket untuk satu platform, misalnya @chat-adapter/slack atau @chat-adapter/whatsapp. State adapter menyimpan langganan thread, lock, dan cache, biasanya di Redis atau PostgreSQL.

Saat webhook masuk, adapter memeriksa tanda tangan request, mengubah payload platform menjadi pesan dengan format seragam, lalu meneruskannya ke instance Chat. Handler membalas lewat thread.post() dengan isi berupa teks biasa, markdown, kartu, atau stream. Adapter kemudian mengubah balasan itu ke format asli platform: Block Kit di Slack, Adaptive Cards di Teams, kartu Google Chat, inline keyboard di Telegram, dan seterusnya.

Handler-nya mengikuti alur percakapan. onNewMention berjalan saat bot di-mention di thread yang belum diikutinya. Jika handler memanggil thread.subscribe(), pesan berikutnya di thread itu masuk ke onSubscribedMessage. onDirectMessage menangani chat pribadi, onNewMessage menerima regular expression untuk pemicu berbasis kata kunci, dan ada handler terpisah untuk reaksi, klik tombol (onAction), slash command, serta form modal.

Platform yang Didukung

Adapter dibagi ke dalam tiga tingkat. Adapter official dipelihara Vercel dan diterbitkan di bawah scope @chat-adapter. Adapter vendor-official dipelihara langsung oleh perusahaan pemilik platform. Adapter community dibuat developer lain dan diterbitkan dengan nama mereka sendiri.

TingkatContoh (per versi 4.45, November 2026)
Official (Vercel)Slack, Microsoft Teams, Google Chat, Discord, Telegram, WhatsApp Business Cloud, Messenger, Instagram, GitHub, GitLab, Linear, Notion, Gmail, Twilio, X, Twitch, dan adapter Web untuk situs Anda sendiri
Vendor-officialResend untuk email, Lark/Feishu, Liveblocks, Novu, Beeper Matrix, dan beberapa penyedia iMessage serta SMS
CommunityLINE, Mattermost, Rocket.Chat, Webex, Zoom Team Chat, Signal, serta adapter WhatsApp tidak resmi berbasis Baileys
StateMemory untuk development, Redis, ioredis (untuk Cluster atau Sentinel), dan PostgreSQL, ditambah MySQL dan Cloudflare Durable Objects dari komunitas

Vercel juga menerbitkan @chat-adapter/catalog, paket kecil yang mendaftar semua adapter beserta kemampuannya dan environment variable yang dibutuhkan. Ini cara paling akurat untuk mengecek fitur sebuah adapter, karena daftarnya cepat berubah. Paket utamanya bergerak dari 4.0.0 di Januari 2026 ke 4.45.0 di November, dengan rilis minor baru setiap satu atau dua minggu.

Kode Sama, Hasil Berbeda

Menulis handler sekali tidak berarti semua platform akan menampilkan hal yang sama. Setiap adapter bekerja sebatas yang diizinkan platformnya, dan perbedaannya cukup besar sampai memengaruhi cara merancang percakapan.

PlatformTampilan balasan yang di-streamYang perlu diingat
SlackStreaming native: teks muncul bertahap selama model menulisAdapter paling lengkap, mendukung modal, slash command, pesan ephemeral, serta event edit dan hapus pesan
Microsoft TeamsNative di pesan langsung, satu pesan final di group chatModal bisa dipakai, slash command tidak, dan membaca riwayat butuh izin Microsoft Graph
Google ChatBot mengirim pesan dulu, lalu mengeditnya saat teks bertambahTidak ada modal; membaca riwayat dan membuka DM butuh pengaturan delegasi Workspace tambahan
DiscordKirim dulu, lalu diedit setiap potongan teks masukSlash command dan tombol datang lewat webhook, tetapi pesan biasa hanya datang lewat Gateway WebSocket
TelegramKirim lalu edit, kira-kira satu edit per detik, dengan opsi draft preview di chat pribadiMendukung slash command dan tombol inline keyboard; percakapan dikunci per chat secara default
WhatsAppDitampung dulu: seluruh jawaban dikirim sebagai satu pesan di akhirMaksimal tiga tombol balasan dengan label 20 karakter, pesan tidak bisa diedit atau dihapus, dan ada jendela 24 jam
WebStreaming native lewat server-sent events ke useChatMemungkinkan bot yang sama melayani widget chat di situs sendiri lewat paket AI SDK UI

Dalam praktiknya, pendekatan paling aman adalah merancang percakapan untuk channel yang paling terbatas, lalu menambahkan fitur ekstra di platform yang mendukungnya. Kartu dengan tiga tombol berjalan di Slack, Teams, Telegram, dan WhatsApp. Kartu dengan lima tombol dan dropdown akan tampil rapi di Slack, tetapi di WhatsApp diam-diam berubah menjadi teks biasa.

Membuat Bot Pertama

  1. 1Mulai dari scaffolder: npm create chat-sdk@latest my-bot. CLI ini menanyakan adapter yang dibutuhkan, lalu membuat aplikasi Next.js kecil yang isinya hanya route webhook: src/lib/bot.ts untuk bot, app/api/webhooks/[platform]/route.ts untuk event yang masuk, dan .env.example berisi variabel yang perlu diisi. Versi tanpa prompt: npm create chat-sdk@latest -- my-bot --adapter slack redis -y.
  2. 2Kalau ingin menambahkannya ke proyek yang sudah ada, pasang paket inti dan adapter yang dibutuhkan: npm i chat @chat-adapter/slack @chat-adapter/state-redis. Paket-paket ini membutuhkan Node.js 20 atau lebih baru.
  3. 3Buat bot dengan new Chat({ userName: 'mybot', adapters: { slack: createSlackAdapter() }, state: createRedisState() }). Factory tersebut membaca kredensial dari environment variable seperti SLACK_BOT_TOKEN, SLACK_SIGNING_SECRET, dan REDIS_URL, jadi opsi hanya perlu diisi kalau ingin menimpa nilainya.
  4. 4Daftarkan handler, misalnya bot.onNewMention(async (thread) => { await thread.subscribe(); await thread.post('Halo, saya ikut memantau thread ini.') }). Menambahkan Teams atau Google Chat nanti cukup dengan menambah adapter di objek yang sama; handler-nya tidak berubah.
  5. 5Buka endpoint webhook. Setiap adapter punya handler di bot.webhooks.slack, bot.webhooks.teams, dan seterusnya. Di route Next.js, kembalikan bot.webhooks.slack(request, { waitUntil: (task) => after(() => task) }) supaya function tetap hidup sampai handler selesai.
  6. 6Arahkan platform ke URL tersebut: event subscription di pengaturan aplikasi Slack, messaging endpoint di Azure Bot Service untuk Teams, atau callback URL di aplikasi Meta untuk WhatsApp.

Menghubungkan dengan Model AI

thread.post() menerima async iterable berisi string, jadi keluaran model bisa langsung dialirkan ke chat. Dengan AI SDK, yang tercatat sebagai peer dependency opsional untuk versi 6 dan 7, stream dari agent bisa langsung dikirim: await thread.post(result.fullStream). Stream dari TanStack AI juga dikenali otomatis.

Pakai fullStream, bukan textStream, kalau agent memanggil tool. textStream menggabungkan teks dari setiap langkah tanpa pemisah, sehingga balasan bisa muncul seperti "halo.ada yang bisa dibantu?". fullStream membawa batas antarlangkah, dan Chat SDK memakainya untuk menyisipkan jeda paragraf. Sebaiknya teruskan juga thread.signal ke pemanggilan model. Di Slack, saat pengguna menekan tombol stop, signal ini dibatalkan dan proses generate ikut berhenti, alih-alih terus berjalan dan menghabiskan token untuk jawaban yang tidak akan dibaca.

Untuk percakapan bolak-balik, toAiMessages() mengubah pesan di thread menjadi format role dan content yang dibutuhkan model. Kalau orang yang sama bicara dengan bot di lebih dari satu platform, History API (bot.history.user) bisa menyimpan satu transkrip per pengguna, dengan kunci dari identity resolver yang Anda tulis sendiri. API ini juga punya fungsi hapus untuk permintaan "hapus data saya", yang relevan dengan kewajiban di UU Pelindungan Data Pribadi.

Ada dua detail kecil yang membuat balasan streaming terlihat lebih rapi. Markdown yang belum lengkap, misalnya ** pembuka yang pasangannya belum datang, diperbaiki di setiap pembaruan sementara sehingga format tidak sempat terlihat rusak. Tabel dari keluaran model ditahan sampai baris pemisahnya datang, jadi pengguna tidak melihat deretan karakter pipa mentah.

Masalah yang Biasa Muncul di Production

  • Memakai state memory di luar development. Adapter memory menyimpan langganan dan lock di dalam satu proses. Di serverless, atau kalau servernya lebih dari satu, instance tidak saling berbagi data itu, dan restart membuat semua thread yang diikuti terlupa. Pakai Redis, ioredis, atau PostgreSQL sebelum go-live.
  • Pesan hilang karena pengaturan concurrency bawaan. Strategi default-nya drop: kalau pesan baru datang saat handler untuk thread itu masih berjalan, pesan baru dibuang dengan LockError. Di WhatsApp dan Telegram, orang sering mengetik "halo", lalu "mau tanya", lalu pertanyaan sebenarnya, dengan jarak satu detik. Ubah concurrency ke debounce, yang secara default menunggu 1,5 detik lalu hanya memproses pesan terakhir, atau burst, yang menunggu dengan cara serupa tetapi tetap memberikan pesan-pesan sebelumnya ke handler lewat context.skipped. Pilih queue kalau setiap pesan harus diproses.
  • Respons webhook yang lambat. Slack mengharuskan webhook dibalas dalam tiga detik, sedangkan jawaban AI butuh waktu lebih lama. Karena itu pekerjaan harus berlanjut setelah respons terkirim, dan untuk itulah waitUntil dipakai. Di platform serverless, tanpa waitUntil function bisa dihentikan di tengah balasan.
  • Mengira event yang gagal pasti dikirim ulang. Chat SDK melakukan deduplikasi webhook selama sepuluh menit secara default, jadi kalau handler gagal lalu platform mengirim ulang event yang sama, kiriman kedua bisa dilewati. Mengembalikan status 500 tidak menjamin ada percobaan ulang. Untuk aksi yang tidak boleh hilang, seperti membuat pesanan, catat pekerjaannya di penyimpanan yang tahan gangguan sebelum membalas.
  • Discord di serverless. Slash command dan klik tombol datang lewat webhook, tetapi pesan biasa dan reaksi hanya datang lewat Gateway WebSocket. Scaffolder menambahkan cron job yang menjaga koneksi itu setiap sembilan menit, dan fitur ini butuh paket Vercel berbayar. Adapter Matrix dan Lark membutuhkan proses yang berjalan terus dan sama sekali tidak tersedia di scaffolder.
  • Mengharapkan fitur yang sama di semua platform. Modal hanya ada di Slack dan Teams. Event edit dan hapus pesan saat ini hanya dikirim oleh adapter Slack. Mendaftarkan handler-nya di platform lain tidak menimbulkan error, tetapi handler itu tidak akan pernah dipanggil.
  • Bergantung pada bagian internal adapter. Adapter official bisa di-subclass, tetapi member protected yang di-override dinyatakan belum stabil dan bisa berubah di rilis minor. Kunci versinya kalau memakai cara ini, dan baca changelog sebelum upgrade.

Catatan untuk Bot WhatsApp

Adapter WhatsApp resmi memakai WhatsApp Business Cloud API dari Meta, dengan kredensial dari aplikasi Meta: access token, app secret, phone number ID, dan verify token yang Anda tentukan sendiri untuk proses verifikasi webhook. Untuk production, gunakan System User token permanen, bukan token sementara yang muncul di halaman setup.

Aturan WhatsApp tetap berlaku. Di luar jendela layanan pelanggan 24 jam, bisnis hanya boleh mengirim template message yang sudah disetujui, dan adapter mengirimnya lewat sendTemplate. Pesan tidak bisa diedit, sehingga jawaban AI yang di-stream dikumpulkan dulu lalu dikirim sekaligus. Panggil thread.startTyping() supaya indikator mengetik muncul hingga 25 detik dan pengguna tahu pesannya sedang diproses. Balasan panjang dipecah otomatis setiap 4.096 karakter.

Adapter community berbasis Baileys terhubung lewat protokol WhatsApp Web, bukan API resmi. Cocok untuk eksperimen, tetapi WhatsApp tidak mengizinkan otomasi semacam itu untuk keperluan bisnis, dan nomornya bisa diblokir. Untuk layanan yang diandalkan pelanggan, tetap gunakan Cloud API.

Persetujuan dan Alur Kerja yang Panjang

Permintaan yang sering muncul untuk bot internal adalah langkah persetujuan oleh orang tertentu: refund, deployment, atau pembelian. requestApproval dari chat/workflow mengirim kartu dengan tombol Approve dan Deny, lalu menahan workflow Workflow SDK sampai ada yang menekan tombol. Waktu tunggunya bisa beberapa menit sampai beberapa hari, dan tetap aman walaupun ada deploy di tengah jalan. Opsi approvers membatasi siapa yang boleh memutuskan. Isi opsi ini untuk keputusan yang berdampak nyata, karena secara default siapa pun yang bisa melihat kartu bisa menekan tombolnya. Setelah ada keputusan, kartu diedit untuk menampilkan siapa yang memutuskan, sehingga ada jejak audit sederhana di thread.

Menjalankannya di Luar Vercel

Chat SDK berlisensi MIT dan bisa berjalan di host Node.js mana pun. Handler webhook bisa ditempatkan di Next.js, Hono, Nuxt, SvelteKit, Express, atau framework serupa. Di VPS biasa dengan proses Node.js yang berjalan terus dan satu instance Redis, sebagian besar masalah serverless di atas tidak muncul, dan koneksi Gateway Discord bisa dibiarkan terbuka. Vercel Connect, yang mengelola kredensial platform untuk beberapa adapter, sifatnya opsional.

Library-nya sendiri gratis. Biaya berjalan datang dari tempat lain: penyedia model, hosting Redis atau PostgreSQL, dan platform yang menarik biaya untuk API-nya. WhatsApp yang paling jelas, karena Meta mengenakan biaya untuk pesan bisnis. Semua ini sebaiknya masuk ke perhitungan sejak awal.

Kapan Chat SDK Kurang Cocok

  • Anda hanya menyasar satu platform dan tim sudah nyaman dengan SDK bawaannya, misalnya Bolt untuk Slack atau grammY untuk Telegram. Lapisan tambahan ini tidak banyak memberi manfaat.
  • Bot hanya mengirim notifikasi, seperti status pesanan atau peringatan sistem, tanpa pernah bercakap-cakap. Panggilan API langsung lebih sederhana.
  • Anda butuh fitur platform yang belum didukung adapter. Cek halaman adapter terlebih dahulu; status partial biasanya berarti ada solusi sementara yang belum tentu cocok dengan kebutuhan Anda.
  • Tim tidak bekerja dengan TypeScript. Bot tetap bisa dijalankan sebagai layanan kecil terpisah di depan backend PHP atau Go, tetapi harus ada yang bertanggung jawab memeliharanya.

Cara Kami Mendekati Proyek Seperti Ini

  1. 1Tentukan channel berdasarkan siapa penggunanya. Karyawan biasanya ada di Slack, Teams, atau Google Chat. Pelanggan di Indonesia sebagian besar ada di WhatsApp, dengan Telegram untuk sebagian komunitas. Mulailah dengan paling banyak satu channel internal dan satu channel eksternal.
  2. 2Rancang percakapan untuk channel yang paling terbatas, lalu tambahkan kartu yang lebih kaya di platform yang mendukungnya.
  3. 3Pilih state backend dan strategi concurrency untuk tiap channel sebelum deploy pertama, bukan setelah pengguna mengeluh pesannya tidak dibalas.
  4. 4Simpan logika bisnis, seperti mencari data pesanan atau membuat tiket, di layanan Anda sendiri. Handler bot cukup memanggil layanan tersebut, bukan menyimpan aturannya.
  5. 5Tulis test dengan @chat-adapter/tests, yang menyediakan factory dan matcher untuk Vitest, lalu tambahkan logging terstruktur. Chat SDK sudah mencatat event seperti message-dropped dan message-queued, dan itu tempat pertama yang perlu dicek saat ada yang bilang bot tidak membalas.
  6. 6Sepakati data percakapan apa yang disimpan, berapa lama, dan bagaimana pengguna bisa meminta datanya dihapus.

Poin penting

  • Chat SDK (paket npm chat) adalah library TypeScript open source dari Vercel untuk menjalankan satu bot di Slack, Teams, Google Chat, Discord, Telegram, WhatsApp, dan platform lain.
  • Library ini hanya mengurus sisi platform chat; pasangkan dengan AI SDK atau TanStack AI untuk modelnya, lalu kirim fullStream dan teruskan thread.signal.
  • Handler yang sama berperilaku berbeda di tiap platform: WhatsApp menampung balasan dan hanya mengizinkan tiga tombol, sedangkan modal hanya ada di Slack dan Teams.
  • Gunakan Redis atau PostgreSQL untuk state di production, dan ganti concurrency bawaan drop menjadi debounce, burst, atau queue untuk aplikasi chat yang penggunanya suka mengirim beberapa pesan pendek.
  • Jangan mengandalkan kiriman ulang dari platform untuk aksi penting, karena deduplikasi webhook bisa melewati event yang dikirim ulang.
  • Untuk bot WhatsApp yang melayani pelanggan, gunakan adapter Cloud API resmi, bukan adapter tidak resmi berbasis Baileys.
Bagikan artikel ini

Artikel terkait

Artikel lain tentang software development, AI, cloud, dan infrastruktur.

Tangan memilah formulir dan struk di samping kalkulatorPengembangan AI

10 menit baca

Otomatisasi Input Data Dokumen dengan AI: Invoice, Struk, dan Formulir

Cara AI membaca invoice, struk, KTP, dan formulir lalu mengubahnya menjadi data terstruktur, bagaimana OCR dan large language model bekerja bersama, kenapa validasi dan review manusia tetap penting, cara mengukur akurasi, dan hal yang perlu diperhatikan soal data pribadi.

Robot humanoid kecil duduk di bangku sambil membaca laptopPengembangan AI

9 menit baca

Cara Memulai Proyek AI di Perusahaan

Memilih use case pertama yang punya peluang berhasil, mengecek kesiapan data, memilih antara API AI dan model self-hosted, menjalankan pilot dengan data uji, komponen biaya, dan risiko yang perlu diatur sejak minggu pertama.

Mari berdiskusi

Sedang mencari partner untuk pengembangan software?

Ceritakan proyek yang sedang Anda bangun, kebutuhan yang ingin diselesaikan, dan tantangan yang dihadapi. Kami dapat membantu membahas pendekatan teknis, scope, timeline, dan estimasi biaya.

Mulai diskusi