Siapkan integrasi Slack

Panduan ini menunjukkan cara menghubungkan Slack ke ruang kerja Control Center, baik dengan membiarkan Control Center membuat aplikasinya maupun dengan membuatnya sendiri.

Untuk percobaan pertama yang terpandu, lihat Jembatani Slack ke ruang kerja Anda.

Prasyarat

Peran owner atau admin di ruang kerja Control Center — menghubungkan aplikasi chat adalah perubahan pengaturan ruang kerja
Izin untuk membuat dan menginstal aplikasi di ruang kerja Slack
Tidak ada yang perlu dijangkau publik: koneksinya keluar (Socket Mode), jadi server tidak memerlukan port masuk, tunnel, atau domain

Tiga cara untuk mendapatkan aplikasi

Jalur	Yang Anda sediakan	Yang dilakukan Control Center
Terpandu	Token konfigurasi aplikasi (`xoxe-…`)	Membuat aplikasi dengan scope, peristiwa, Socket Mode, dan perintah slash yang tepat; menyerahkan kepada Anda dua langkah yang tidak punya API di Slack
Buat di Slack	Tidak ada	Membuka Slack dengan konfigurasi yang sama sudah terisi; Anda memilih ruang kerja dan mengonfirmasi
Secara manual	Token aplikasi yang sudah jadi	Memverifikasinya dan menghubungkan

Jalur terpandu adalah satu-satunya yang juga membuat aplikasi tetap dapat dikelola dari Control Center, dan itulah yang memungkinkan Sesuaikan bot chat. Aplikasi Buat di Slack dapat ditingkatkan menjadi aplikasi terkelola nanti dengan menempelkan token konfigurasi di dialog koneksi.

Memang sengaja tidak ada tombol “instal aplikasi Slack milik Control Center”. Menginstal aplikasi Slack yang didistribusikan memerlukan client secret bersama (Slack tidak punya PKCE) dan Socket Mode menyebarkan peristiwa sebuah aplikasi secara acak ke seluruh koneksinya — jadi satu aplikasi bersama akan mengirimkan pesan ruang kerja Anda ke server orang lain. Karena itu, setiap ruang kerja memiliki aplikasinya sendiri, dan ketiga jalur ini ada agar Anda hanya perlu sedikit usaha.

Opsi A: biarkan Control Center membuat aplikasinya

Buat pasangan token konfigurasi aplikasi di api.slack.com/apps dan salin token refresh (xoxe-…)
Di Control Center, buka Pengaturan → Ruang kerja → Umum dan gulir ke kartu Jembatan chat
Pada blok Slack, klik Buatkan aplikasi
Tempel tokennya, sesuaikan nama aplikasi, nama bot, deskripsi, dan perintah slash, lalu klik Buat aplikasi
Ikuti dua langkah tersisa yang ditampilkan dialog, masing-masing berupa tautan ke Slack:
- Basic Information → App-Level Tokens: buat token dengan scope connections:write (xapp-…)
- Install App: instal ke ruang kerja dan salin Bot User OAuth Token (xoxb-…)
Klik Tempel kredensial dan lanjutkan ke Hubungkan

Token konfigurasi dirotasi setiap kali digunakan. Control Center menyimpan nilai yang sudah dirotasi itu seiring prosesnya, jadi Anda tidak perlu menempelkannya lagi.

Opsi B: buat di Slack dengan konfigurasi terisi

Aplikasi yang sama, tanpa token konfigurasi — Slack membuka layar pembuatannya sendiri dengan seluruh manifes sudah terisi.

Di Control Center, buka Pengaturan → Ruang kerja → Umum dan gulir ke kartu Jembatan chat
Pada blok Slack, klik Buatkan aplikasi
Sesuaikan nama aplikasi, nama bot, deskripsi, dan perintah slash — semuanya ikut terbawa lewat tautan
Klik Buat di Slack. Browser Anda membuka halaman pembuatan aplikasi Slack dengan konfigurasi yang sudah terisi
Pilih ruang kerja Slack dan konfirmasi. Scope, peristiwa, Socket Mode, dan perintah slash sudah benar
Kembali di Control Center, ikuti dua langkah tersisa yang ditampilkan dialog:
- Basic Information → App-Level Tokens: buat token dengan scope connections:write (xapp-…)
- Install App: instal ke ruang kerja dan salin Bot User OAuth Token (xoxb-…)
Klik Tempel kredensial dan lanjutkan ke Hubungkan

Slack tidak melaporkan aplikasi mana yang dibuatnya, jadi Control Center tidak mengetahui id aplikasinya dan tautan di langkah 6 mengarah ke daftar aplikasi Anda, bukan langsung ke aplikasi itu. Sesuaikan bot memerlukan token konfigurasi.

Opsi C: buat aplikasinya sendiri

Buat aplikasi di api.slack.com/apps, lalu siapkan sebagai berikut.

Socket Mode: aktifkan dan biarkan setiap request URL kosong. Slack menolak manifes yang meminta Socket Mode sekaligus pengiriman webhook.

Scope token bot (OAuth & Permissions):

app_mentions:read
assistant:write
channels:history
chat:write
commands
groups:history
im:history
users:read
users:read.email

Langganan peristiwa (peristiwa bot):

app_home_opened
app_mention
message.channels
message.groups
message.im

message.channels dan message.groups itulah yang membuat balasan di dalam thread Slack yang sudah dijembatani bisa berfungsi. Tanpa keduanya, hanya sebutan pertama yang akan sampai.

Perintah slash: /cc (nama apa pun bisa — jembatan memakai perintah apa pun yang terakhir dipakai untuk memanggilnya).

App Home: aktifkan tab Messages dan biarkan tetap bisa ditulis, agar anggota dapat mengirim DM ke bot.

Token: buat token tingkat aplikasi dengan connections:write, lalu instal aplikasi dan salin token OAuth pengguna bot.

Hubungkan

Buka Pengaturan → Ruang kerja → Umum dan gulir ke kartu Jembatan chat
Pada blok Slack, klik Hubungkan Slack
Isi kolom-kolomnya:

Kolom	Nilai	Letaknya di Slack
Token OAuth pengguna bot	`xoxb-…`	OAuth & Permissions → Bot User OAuth Token
Token tingkat aplikasi	`xapp-…`	Basic Information → App-Level Tokens (`connections:write`)
Token refresh konfigurasi aplikasi (opsional)	`xoxe-…`	Pasangan token konfigurasi aplikasi di api.slack.com/apps

Awalan setiap nilai diperiksa di kedua sisi sebelum apa pun dikirim, jadi nilai yang ditempel ke kotak yang salah akan ditolak dengan kalimat yang sama di kedua kasus.

Klik Hubungkan

Control Center memverifikasi token bot dengan auth.test milik Slack sebelum menyimpan apa pun, jadi salah ketik akan dilaporkan kepada Anda, bukan menjadi socket yang diam-diam tidak pernah berfungsi. Token tingkat aplikasi hanya bisa dibuktikan dengan membuka socket, jadi token yang salah akan muncul sesaat kemudian sebagai kesalahan koneksi pada baris yang sama.

Tanpa token konfigurasi aplikasi yang opsional ini, koneksinya tetap berfungsi — Anda hanya tidak dapat mengedit bot dari Control Center.

Apa yang dilakukan saat menghubungkan

Menyimpan kredensial di direktori ruang kerja itu sendiri, di samping databasenya, dan hanya bisa dibaca pemilik. Kredensial tidak pernah dikirim kembali ke klien
Membuka satu koneksi Socket Mode untuk ruang kerja ini dan mulai menerima sebutan, balasan thread Slack, DM, dan perintah slash
Menyiapkan ulang setiap thread Slack yang pernah dijembatani sebelumnya, sehingga koneksi ulang melanjutkan percakapan yang ada alih-alih menelantarkannya
Tidak memakan biaya untuk ruang kerja yang tidak punya aplikasi chat: tidak ada socket, tidak ada timer, tidak ada lalu lintas

Kredensial bot adalah satu file JSON biasa per penyedia di <dataDir>/<workspaceId>/chat_credentials/, ditulis secara atomik dan diperketat menjadi hanya pemilik. Itu disengaja, bukan kelalaian: menghapus ruang kerja akan menghapus tautan direktori tersebut sehingga tokennya ikut hilang, dan workspace.export serta cadangan menyalin workspace.db — bukan direktorinya — sehingga ruang kerja yang Anda serahkan kepada orang lain tidak pernah membawa token bot aktif di dalamnya. Konsekuensinya, memulihkan ruang kerja di tempat lain berarti menghubungkan ulang Slack di sana.

Akses ke jembatan adalah keanggotaan ruang kerja, bukan kepemilikan token. Akun Slack harus ditautkan ke pengguna Control Center yang merupakan anggota dengan peran yang bisa menulis. Menghubungkan, memutuskan, penyiapan terpandu, tautan penyiapan, dan penyesuaian bot semuanya dibatasi admin.

Verifikasi

Baris Slack menampilkan tag status: Aktif, Menghubungkan…, Kesalahan koneksi (dengan galat dari Slack sendiri di sampingnya), atau Tidak terhubung. Untuk memeriksa secara menyeluruh:

Di Slack, undang bot ke sebuah kanal: /invite @your-bot-name
Sebut botnya dengan sebuah permintaan
Balasan thread Slack akan muncul dan space yang sesuai muncul di Control Center

Setiap anggota yang ingin memakai jembatan ini lalu menautkan akunnya sendiri — lihat Tautkan akun Slack Anda.

Bagaimana balasan terlihat di Slack

Di atas kata-kata yang dialirkan ada satu kartu terkelompok, dengan satu baris per langkah. Penyiapan adalah satu baris yang judulnya berpindah dari Working on it… ke Cloning … ke Starting the agent…. Penalaran menambahkan baris Thinking…; saat langkah itu selesai, pemikiran singkat dapat muncul di baris itu. Setiap alat memiliki barisnya sendiri (Read lib/main.dart). Jawabannya tiba sebagai teks biasa di bawah kartu. Kartu berubah menjadi selesai saat giliran berakhir, dan menjadi galat saat prosesnya gagal, terputus, atau mencapai batas gilirannya.

Kartu mulai muncul begitu bot menerima sebutan — Working on it… — sehingga thread Slack tidak sepi selama ruang kerja masih dibangun. Sebutan pertama Anda di sebuah kanal Slack membuat percakapan, yang mengkloning repo tempat agen bekerja, sehingga baris penyiapan itu kemudian berbunyi Cloning acme/widgets…, lalu Setting up Reviewer…, lalu Starting the agent…, lalu baris Thinking… saat agen benar-benar bernalar. Pada repo besar, penyiapan pertama itu memerlukan waktu; kartu inilah cara Anda tahu bahwa bot sedang bekerja, bukan mengabaikan Anda. Sebutan berikutnya di thread Slack yang sama tetap dibuka dengan Working on it…, lalu melewati langkah kloning karena ruang kerjanya sudah ada.

Penalaran berupa dinding teks dan keluaran alat tidak pernah keluar dari Control Center — pemikiran pada baris Thinking… adalah satu baris pendek, bukan transkrip. View in Control Center di kartu membuka percakapan lengkap di aplikasi desktop — tautannya mengarah ke server Control Center Anda sendiri, yang menyerahkan browser ke aplikasi tersebut.

Jika tidak terjadi apa-apa saat Anda mengkliknya, server yang mengirim pesan itu tidak dapat dijangkau dari mesin tempat Anda mengklik (misalnya server yang hanya loopback diklik dari ponsel), atau Control Center tidak berjalan di sana. Server tanpa alamat yang dapat dijangkau mengirim kartu tanpa tombol, bukan tombol yang tidak menuju ke mana pun.

Merotasi token

Tempel kembali nilai baru di dialog koneksi dan klik Hubungkan. Menghubungkan akan menggantikan koneksi apa pun yang sedang berjalan untuk ruang kerja ini, jadi socket dipanggil ulang dengan kredensial baru.

Dua token yang wajib harus ada pada setiap penghubungan. Token konfigurasi aplikasi yang opsional tetap menyimpan nilainya saat Anda membiarkan kotaknya kosong, jadi merotasi token bot tidak pernah menghilangkan kemampuan Anda untuk mengedit aplikasi.

Memutuskan

Klik Putuskan pada baris Slack (hanya admin). Socket ditutup dan kredensialnya dilupakan.

Tautan space dan pengguna sengaja dipertahankan: menghubungkan kembali aplikasi yang sama akan memulihkan setiap thread Slack yang dijembatani. Itu adalah baris dengan cakupan ruang kerja, jadi menghapus ruang kerja tetap menghapusnya.

Pemecahan masalah

Baris menampilkan “Kesalahan koneksi”

Baca galat yang ditampilkan di samping tag. Kredensial yang ditolak (invalid_auth, not_authed, token_revoked, account_inactive) bersifat final — jembatan berhenti mencoba ulang dan menunggu token baru, karena mencoba ulang token yang sudah dicabut selamanya hanya akan membuat Anda terkena pembatasan laju. Tempel kembali tokennya di dialog koneksi.

Galat missing_scope berarti aplikasi diinstal dengan scope lebih sedikit daripada yang dibutuhkan jembatan. Tambahkan scope yang kurang, instal ulang aplikasi di Slack, lalu hubungkan kembali.

Apa pun yang bersifat sementara (socket terputus, gangguan Slack) akan menyambung ulang sendiri dengan backoff eksponensial yang dibatasi maksimum 30 detik, dan rotasi socket rutin dari Slack tidak menaikkan backoff tersebut.

Bot tidak menjawab sebutan

Apakah bot ada di kanal? Slack hanya mengirimkan pesan kanal ke aplikasi yang menjadi anggotanya. Jalankan /invite @your-bot-name
Apakah Anda sudah tertaut? Anggota yang belum tertaut akan menerima balasan di thread Slack itu yang menjelaskan cara menautkan. Lihat Tautkan akun Slack Anda
Apakah Anda anggota ruang kerja dengan peran yang bisa menulis? viewer atau guest akan diberi tahu bahwa perannya hanya baca. Jembatan tidak pernah memulai pekerjaan atas nama seseorang yang tidak dapat diatribusikan
Apakah ruang kerja punya agen? Tanpa agen, pesannya disimpan tetapi tidak ada yang menjawabnya

Ia menjawab di kanal tetapi mengabaikan pesan biasa

Itu memang disengaja. Di luar DM, jembatan hanya menanggapi pesan yang menyebut bot, atau balasan di dalam thread Slack yang sudah dimilikinya. Sisanya adalah percakapan orang lain.

Balasan tiba sebagai satu pesan besar alih-alih streaming

Baris tersebut menampilkan “Streaming langsung nonaktif untuk aplikasi Slack ini — balasan tiba sebagai satu pesan.” Balasan streaming dari Slack memerlukan fitur Agents & AI Apps pada paket berbayar; saat Slack menolaknya, jembatan berhenti memintanya selama sisa masa hidup koneksi itu dan mengirim balasan utuh sebagai gantinya. Tidak ada yang hilang — transkrip lengkapnya selalu ada di Control Center.

Streaming juga memerlukan jangkar thread Slack, jadi balasan yang tidak punya thread Slack untuk tumbuh akan dikirim utuh. Kartu tugas tetap datang dalam kedua kasus: pada balasan utuh, kartu itu menumpang pesan yang sama dan sudah selesai.

Balasan tidak punya kartu di atasnya

Kartu tugas Slack adalah bagian dari permukaan Agents & AI Apps baru yang sama dengan streaming, dan Slack hanya menolaknya pada saat pemanggilan. Saat itu terjadi, Control Center mempertahankan balasan dan membuang kartunya selama sisa masa hidup koneksi itu — jawaban tanpa baris status lebih baik daripada baris status tanpa jawaban.

“Control Center memerlukan token konfigurasi aplikasi untuk mengedit bot”

Baris Sesuaikan bot dinonaktifkan karena koneksinya tidak punya token konfigurasi aplikasi. Ini wajar untuk aplikasi yang dibuat secara manual atau melalui Buat di Slack — Slack tidak pernah memberi tahu Control Center aplikasi mana itu. Buat pasangan token di api.slack.com/apps dan hubungkan kembali dengan token refresh yang sudah diisi.

Jawaban panjang terpotong

Slack membatasi satu pesan maksimum 40.000 karakter, jadi jembatan memotong pada 39.000 karakter dan menambahkan penunjuk ke Control Center — balasan yang dipersingkat lebih baik daripada balasan yang langsung ditolak Slack. Teks lengkapnya selalu ada di transkrip space.

Panduan terkait

Konsep terkait

Jembatan chat