راه‌اندازی یکپارچه‌سازی Slack

این راهنما نشان می‌دهد چگونه Slack را به یک فضای کاری Control Center وصل کنید — چه با سپردن ساخت برنامه به Control Center، چه با ساختن خودتان.

برای یک اجرای نخستِ راهنمایی‌شده، Slack را به فضای کاری‌تان متصل کنید را ببینید.

Slack تنها ارائه‌دهندهٔ گفتگو است

پل به‌حکم ساخت مستقل از ارائه‌دهنده است — یک رابط کاربری توصیف‌گرمحور روی یک آداپتور به‌ازای هر ارائه‌دهنده — اما Slack تنها آداپتوری است که وجود دارد. هیچ پیاده‌سازی‌ای برای Discord، Telegram، Teams یا Matrix نیست.

پیش‌نیازها

• نقش owner یا admin در فضای کاری Control Center — وصل‌کردن یک برنامهٔ گفتگو تغییری در تنظیمات فضای کاری است
• اجازهٔ ساخت و نصب برنامه در فضای کاری Slack
• هیچ‌چیز نباید از بیرون قابل‌دسترس باشد: اتصال رو به بیرون است (Socket Mode)، پس سرور به هیچ پورت ورودی، تونل یا دامنه‌ای نیاز ندارد

سه راه برای به دست آوردن برنامه

مسیر	شما چه فراهم می‌کنید	Control Center چه می‌کند
راهنمایی‌شده	یک توکن پیکربندی برنامه (xoxe-…)	برنامه را با اسکوپ‌ها، رویدادها، Socket Mode و دستور اسلش درست می‌سازد؛ دو گامی را که Slack برایشان API ندارد به شما می‌سپارد
ایجاد در Slack	هیچ‌چیز	Slack را با همان پیکربندی پیش‌پرشده باز می‌کند؛ شما یک فضای کاری انتخاب و تأیید می‌کنید
دستی	توکن‌های برنامهٔ آماده	آن‌ها را بررسی و وصل می‌کند

فقط مسیر راهنمایی‌شده است که برنامه را از Control Center هم قابل مدیریت باقی می‌گذارد، و همین است که سفارشی‌سازی ربات گفتگو را ممکن می‌کند. برنامه‌ای که با ایجاد در Slack ساخته شده باشد بعداً می‌تواند با جای‌گذاری یک توکن پیکربندی برنامه در پنجرهٔ گفتگوی اتصال به برنامه‌ای مدیریت‌شده ارتقا یابد.

به‌عمد هیچ دکمهٔ «نصب برنامهٔ Slack خودِ Control Center» وجود ندارد. نصب یک برنامهٔ Slack توزیع‌شده به یک client secret مشترک نیاز دارد (Slack سازوکار PKCE ندارد) و Socket Mode رویدادهای یک برنامه را به‌شکل تصادفی میان اتصالاتش پخش می‌کند — پس یک برنامهٔ مشترک پیام‌های فضای کاری شما را به سرورهای دیگران می‌رساند. بنابراین هر فضای کاری برنامهٔ خودش را دارد و این سه راه دربارهٔ این‌اند که این کار چقدر کم برایتان کار می‌برد.

گزینهٔ A: بگذارید Control Center برنامه را بسازد

1. در api.slack.com/apps یک جفت توکن پیکربندی برنامه بسازید و توکن تازه‌سازی (xoxe-…) را کپی کنید
2. در Control Center به تنظیمات ← فضای کاری ← عمومی بروید و تا کارت پل‌های گفتگو پایین بیایید
3. در بلوک Slack روی برنامه را برایم بساز کلیک کنید
4. توکن را جای‌گذاری کنید، نام برنامه، نام ربات، توضیحات و دستور اسلش را تنظیم کنید و سپس روی ایجاد برنامه کلیک کنید
5. دو گام باقی‌مانده‌ای را که پنجرهٔ گفتگو نشان می‌دهد دنبال کنید، هرکدام پیوندی به Slack:
   • Basic Information → App-Level Tokens: یک توکن با اسکوپ connections:write بسازید (xapp-…)
   • Install App: برنامه را در فضای کاری نصب کنید و Bot User OAuth Token (xoxb-…) را کپی کنید
6. روی جای‌گذاری اعتبارنامه‌ها کلیک کنید و با اتصال ادامه دهید

توکن پیکربندی در هر بار استفاده می‌چرخد. Control Center مقدار چرخیده را همان‌طور که پیش می‌رود ذخیره می‌کند، پس هیچ‌وقت لازم نیست دوباره آن را جای‌گذاری کنید.

گزینهٔ B: ساختن در Slack، پیش‌پرشده

همان برنامه، بدون توکن پیکربندی — Slack صفحهٔ ساخت خودش را با کل مانیفست از پیش پرشده به شما می‌دهد.

1. در Control Center به تنظیمات ← فضای کاری ← عمومی بروید و تا کارت پل‌های گفتگو پایین بیایید
2. در بلوک Slack روی برنامه را برایم بساز کلیک کنید
3. نام برنامه، نام ربات، توضیحات و دستور اسلش را تنظیم کنید — این‌ها با پیوند می‌روند
4. روی ایجاد در Slack کلیک کنید. مرورگرتان صفحهٔ ساخت برنامهٔ Slack را با پیکربندی پیش‌پرشده باز می‌کند
5. فضای کاری Slack را انتخاب و تأیید کنید. اسکوپ‌ها، رویدادها، Socket Mode و دستور اسلش از پیش درست‌اند
6. به Control Center برگردید و دو گام باقی‌مانده‌ای را که پنجرهٔ گفتگو نشان می‌دهد دنبال کنید:
   • Basic Information → App-Level Tokens: یک توکن با اسکوپ connections:write بسازید (xapp-…)
   • Install App: برنامه را در فضای کاری نصب کنید و Bot User OAuth Token (xoxb-…) را کپی کنید
7. روی جای‌گذاری اعتبارنامه‌ها کلیک کنید و با اتصال ادامه دهید

Slack گزارش نمی‌دهد کدام برنامه را ساخته است، پس Control Center شناسهٔ برنامه را نمی‌آموزد و پیوندهای گام 6 به فهرست برنامه‌های شما می‌روند، نه مستقیم به آن برنامه. سفارشی‌سازی ربات به یک توکن پیکربندی برنامه نیاز دارد.

گزینهٔ C: برنامه را خودتان بسازید

در api.slack.com/apps یک برنامه بسازید و سپس آن را این‌گونه راه‌اندازی کنید.

Socket Mode: فعالش کنید و هر request URL را خالی بگذارید. Slack مانیفستی را که هم‌زمان Socket Mode و تحویل webhook بخواهد رد می‌کند.

Bot token scopes (OAuth & Permissions):

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

Event subscriptions (رویدادهای ربات):

app_home_opened
app_mention
message.channels
message.groups
message.im

message.channels و message.groups همان چیزهایی هستند که باعث می‌شوند یک پاسخ درون رشتهٔ Slack‌ای که از پیش پل شده کار کند. بدون آن‌ها، تنها نخستین منشن می‌رسد.

دستور اسلش: /cc (هر نامی کار می‌کند — پل همان دستوری را به کار می‌برد که آخرین بار با آن فراخوانی شده است).

App Home: تب Messages را فعال کنید و آن را قابل‌ویرایش بگذارید تا اعضا بتوانند به ربات پیام مستقیم بدهند.

Tokens: یک توکن سطح برنامه با connections:write بسازید، سپس برنامه را نصب کنید و توکن OAuth کاربر ربات را کپی کنید.

اتصال

1. به تنظیمات ← فضای کاری ← عمومی بروید و تا کارت پل‌های گفتگو پایین بیایید
2. در بلوک Slack روی اتصال Slack کلیک کنید
3. فیلدها را پر کنید:

فیلد	مقدار	جای آن در Slack
توکن ربات	xoxb-…	OAuth & Permissions → Bot User OAuth Token
توکن سطح برنامه	xapp-…	Basic Information → App-Level Tokens (connections:write)
توکن پیکربندی برنامه (اختیاری)	xoxe-…	جفت توکن پیکربندی برنامه در api.slack.com/apps

پیشوند هر مقدار پیش از آنکه چیزی فرستاده شود در هر دو سو بررسی می‌شود، پس مقداری که در کادر اشتباه جای‌گذاری شود، در هر دو حالت با همان جمله رد می‌شود.

4. روی اتصال کلیک کنید

Control Center توکن ربات را با auth.test اسلک پیش از ذخیره‌کردن هر چیزی بررسی می‌کند، پس یک اشتباه تایپی به شما گزارش می‌شود، نه اینکه به سوکتی تبدیل شود که بی‌صدا هرگز کار نمی‌کند. توکن سطح برنامه را تنها با بازکردن سوکت می‌توان اثبات کرد، پس یکی خراب یک لحظه بعد به‌صورت خطای اتصال در همان ردیف پیدا می‌شود.

بدون توکن پیکربندی برنامهٔ اختیاری، اتصال بی‌مشکل کار می‌کند — فقط نمی‌توانید ربات را از Control Center ویرایش کنید.

اتصال چه می‌کند

• اعتبارنامه‌ها را در دایرکتوری خودِ فضای کاری، کنار پایگاه‌داده‌اش، ذخیره می‌کند؛ فقط مالک می‌تواند بخواندشان. آن‌ها هرگز به یک کلاینت بازنمی‌گردند
• یک اتصال Socket Mode برای این فضای کاری باز می‌کند و شروع می‌کند به دریافت منشن‌ها، پاسخ‌های رشتهٔ Slack، پیام‌های مستقیم و دستورات اسلش
• هر رشتهٔ Slack را که پیش‌تر پل شده بود دوباره مسلح می‌کند، تا یک اتصال مجدد گفتگوهای موجود را ادامه دهد نه رهاشان کند
• برای فضای کاری‌ای که هیچ برنامهٔ گفتگویی ندارد هیچ هزینه‌ای ندارد: نه سوکتی، نه تایمری، نه ترافیکی

توکن‌ها کجا زندگی می‌کنند و چرا نه در جاکلیدی

اعتبارنامه‌های ربات یک فایل JSON ساده به‌ازای هر ارائه‌دهنده در <dataDir>/<workspaceId>/chat_credentials/ است، که اتمی نوشته می‌شود و به فقط‌مالک محدود می‌شود. این عمدی است، نه از سر غفلت: حذف یک فضای کاری آن دایرکتوری را جدا می‌کند، پس توکن‌هایش هم همراه آن می‌روند، و workspace.export و پشتیبان‌ها workspace.db را کپی می‌کنند — نه دایرکتوری را — پس فضای کاری‌ای که به کس دیگری می‌دهید هرگز توکن‌های ربات زنده را در خود حمل نمی‌کند. نتیجهٔ لازمش این است که بازیابی یک فضای کاری در جای دیگر یعنی وصل‌کردن دوبارهٔ Slack در آنجا.

دسترسی به پل عضویت در فضای کاری است، نه در اختیار داشتن یک توکن. یک حساب Slack باید به کاربری در Control Center پیوند داده شود که عضوی با نقشی نویسنده است. اتصال، قطع اتصال، راه‌اندازی راهنمایی‌شده، پیوند راه‌اندازی و سفارشی‌سازی ربات همگی محدود به ادمین‌اند.

بررسی

ردیف Slack یک برچسب وضعیت نشان می‌دهد: زنده، در حال اتصال…، خطای اتصال (با خطای خود Slack کنارش)، یا متصل نیست. برای بررسی سرتاسری:

1. در Slack، ربات را به یک کانال دعوت کنید: /invite @your-bot-name
2. با یک درخواست منشنش کنید
3. یک پاسخ در رشتهٔ Slack ظاهر می‌شود و یک فضای متناظر در Control Center پدیدار می‌گردد

سپس هر عضوی که می‌خواهد از پل استفاده کند حساب خودش را پیوند می‌زند — اتصال حساب Slack شما را ببینید.

پاسخ در Slack چه شکلی است

بالای واژه‌های استریم‌شده یک کارت گروه‌بندی‌شده با یک ردیف به‌ازای هر گام می‌نشیند. راه‌اندازی یک ردیف است که عنوانش از Working on it… به Cloning … و بعد Starting the agent… تغییر می‌کند. استدلال یک ردیف Thinking… اضافه می‌کند؛ وقتی آن گام تمام شود، یک اندیشهٔ کوتاه می‌تواند رویش ظاهر شود. هر ابزار ردیف خودش را دارد (Read lib/main.dart). پاسخ به‌صورت متن معمولی زیر کارت می‌رسد. کارت وقتی نوبت تمام می‌شود کامل می‌شود و وقتی اجرا شکست خورده، قطع شده یا به سقف نوبتش رسیده باشد خطاخورده.

کارت همان لحظه‌ای باز می‌شود که ربات منشن را می‌پذیرد — Working on it… — تا رشتهٔ Slack زمانی که فضای کاری هنوز در حال ساخته‌شدن است ساکت نماند. نخستین منشن شما در یک کانال Slack گفتگو را می‌سازد، و آن هم مخزن‌هایی را که عامل در آن‌ها کار می‌کند کلون می‌کند، پس آن ردیف راه‌اندازی بعد Cloning acme/widgets… را می‌خواند، سپس Setting up Reviewer…، سپس Starting the agent…، و بعد از آنکه عامل واقعاً استدلال می‌کند یک ردیف Thinking…. روی یک مخزن بزرگ آن راه‌اندازی نخست مدتی طول می‌کشد؛ کارت همان چیزی است که با آن می‌فهمید دارد کار می‌کند و نادیده‌تان نمی‌گیرد. منشن‌های بعدی در همان رشتهٔ Slack همچنان با Working on it… باز می‌شوند، اما گام‌های کلون را رد می‌کنند چون فضای کاری از قبل آنجاست.

استدلال به‌شکل دیواری از متن و خروجی ابزار هرگز از Control Center بیرون نمی‌رود — اندیشهٔ روی ردیف Thinking… یک خط کوتاه است، نه رونوشت. View in Control Center روی کارت کل گفتگو را در برنامهٔ رومیزی باز می‌کند — پیوند به سرور Control Center خودتان می‌رود، که مرورگر را به برنامه تحویل می‌دهد.

اگر با کلیک روی آن هیچ اتفاقی نمی‌افتد، سروری که پیام را فرستاده از ماشینی که روی آن کلیک کرده‌اید قابل‌دسترس نیست (مثلاً سروری که فقط روی loopback گوش می‌دهد و از گوشی کلیک شده است)، یا Control Center آنجا اجرا نمی‌شود. سروری که نشانی قابل‌دسترس ندارد، کارتی بدون دکمه می‌فرستد، نه کارتی که به جایی نمی‌رسد.

چرخاندن یک توکن

مقدار تازه را در پنجرهٔ گفتگوی اتصال دوباره جای‌گذاری کنید و روی اتصال کلیک کنید. اتصال هر اتصالی را که برای این فضای کاری در حال اجرا بوده جایگزین می‌کند، پس سوکت با اعتبارنامه‌های تازه دوباره شماره‌گیری می‌شود.

دو توکن لازم باید در هر اتصال حاضر باشند. توکن پیکربندی برنامهٔ اختیاری وقتی کادر را خالی بگذارید مقدار ذخیره‌شده‌اش را نگه می‌دارد، پس چرخاندن یک توکن ربات هیچ‌وقت توانایی ویرایش برنامه را از شما نمی‌گیرد.

قطع اتصال

روی ردیف Slack روی قطع اتصال کلیک کنید (فقط ادمین‌ها). سوکت بسته می‌شود و اعتبارنامه‌ها فراموش می‌شوند.

پیوندهای فضا و کاربر به‌عمد باقی می‌مانند: وصل‌کردن دوبارهٔ همان برنامه هر رشتهٔ Slack پل‌شده را برمی‌گرداند. آن‌ها ردیف‌هایی در دامنهٔ فضای کاری‌اند، پس حذف فضای کاری به‌هرحال آن‌ها را پاک می‌کند.

عیب‌یابی

ردیف می‌گوید «خطای اتصال»

خطای نمایش‌داده‌شده کنار برچسب را بخوانید. اعتبارنامهٔ ردشده (invalid_auth، not_authed، token_revoked، account_inactive) پایانی است — پل دیگر تلاش نمی‌کند و منتظر توکن‌های تازه می‌ماند، چون تلاش بی‌پایان برای یک توکن باطل‌شده فقط شما را دچار محدودیت نرخ می‌کند. توکن‌ها را در پنجرهٔ گفتگوی اتصال دوباره جای‌گذاری کنید.

خطای missing_scope یعنی برنامه با اسکوپ‌های کمتر از آنچه پل لازم دارد نصب شده است. اسکوپ گمشده را اضافه کنید، برنامه را در Slack دوباره نصب کنید، بعد دوباره وصل شوید.

هر چیز گذرا (سوکتی که افتاده، یک وقفهٔ کوتاه Slack) خودش با عقب‌نشینی نمایی با سقف 30 ثانیه دوباره وصل می‌شود و چرخش سوکت روتین Slack آن عقب‌نشینی را تشدید نمی‌کند.

ربات به یک منشن پاسخ نمی‌دهد

• آیا ربات در کانال است؟ Slack پیام‌های کانال را فقط به برنامه‌هایی می‌رساند که عضو باشند. /invite @your-bot-name را اجرا کنید
• آیا پیوند دارید؟ عضوی که پیوند ندارد در همان رشتهٔ Slack پاسخی می‌گیرد که توضیح می‌دهد چگونه پیوند بزند. اتصال حساب Slack شما را ببینید
• آیا عضوی از فضای کاری با نقش نویسنده هستید؟ به یک viewer یا guest گفته می‌شود که نقشش فقط‌خواندنی است. پل هرگز به نمایندگی کسی که نمی‌تواند به او نسبت دهد کاری را شروع نمی‌کند
• آیا فضای کاری هیچ عاملی دارد؟ بدون عامل، پیام ذخیره می‌شود اما کسی را ندارد که پاسخش دهد

در یک کانال پاسخ می‌دهد اما پیام‌های ساده را نادیده می‌گیرد

این عمدی است. بیرون از یک پیام مستقیم، پل فقط روی پیامی عمل می‌کند که ربات را منشن کند، یا پاسخی درون یک رشتهٔ Slack که از قبل مالکش است. هر چیز دیگری گفتگوی دیگران است.

پاسخ‌ها به‌جای استریم به‌صورت یک پیام بزرگ می‌رسند

ردیف می‌گوید «استریم زنده برای این برنامهٔ Slack خاموش است — پاسخ‌ها به‌صورت یک پیام می‌آیند.» پاسخ‌های استریمی Slack به قابلیت Agents & AI Apps روی یک پلن پرداختی نیاز دارند؛ وقتی Slack آن را رد کند، پل برای باقی عمر آن اتصال دیگر درخواست نمی‌کند و به‌جایش پاسخ‌های کامل می‌گذارد. چیزی از دست نمی‌رود — رونوشت کامل همیشه در Control Center است.

استریم به یک لنگر رشتهٔ Slack هم نیاز دارد، پس پاسخی که رشتهٔ Slack‌ی برای رشد در آن ندارد کامل فرستاده می‌شود. کارت وظیفه در هر دو حالت می‌رسد: روی یک پاسخ کامل، سوار همان پیام است، از قبل کامل.

بالای پاسخ کارتی نیست

کارت‌های وظیفهٔ Slack بخشی از همان سطح تازهٔ Agents & AI Apps هستند که استریم هم بخشی از آن است، و Slack فقط هنگام فراخوانی رد می‌کند. وقتی رد کند، Control Center پاسخ را نگه می‌دارد و کارت را برای باقی عمر آن اتصال رها می‌کند — پاسخی بدون خط وضعیت بهتر از خط وضعیتی بدون پاسخ است.

«Control Center برای ویرایش ربات به توکن پیکربندی برنامه نیاز دارد»

ردیف سفارشی‌سازی ربات غیرفعال است چون اتصال توکن پیکربندی برنامه ندارد. این برای برنامه‌ای که دستی یا از طریق ایجاد در Slack ساخته شده انتظار می‌رود — Slack هرگز به Control Center نگفته کدام برنامه است. در api.slack.com/apps یک جفت توکن بسازید و با توکن تازه‌سازی پرشده دوباره وصل شوید.

پاسخ بلند بریده می‌شود

Slack یک پیام تکی را روی 40,000 کاراکتر سقف می‌گذارد، پس پل روی 39,000 می‌برد و یک اشاره‌گر به Control Center ضمیمه می‌کند — پاسخ کوتاه‌شده بهتر از پاسخی است که Slack یکسره رد می‌کند. متن کامل همیشه در رونوشت فضا است.

راهنماهای مرتبط

• اتصال حساب Slack شما
• سفارشی‌سازی ربات گفتگو
• پل گفتگو

مفهوم‌های مرتبط

• پل‌های گفتگو