Налаштувати інтеграцію Slack

У цьому посібнику описано, як підключити Slack до робочого простору Control Center — або дозволивши Control Center створити застосунок, або зібравши його самостійно.

Для першого запуску під проводом дивіться Підключіть Slack до робочого простору.

Передумови

Роль owner або admin у робочому просторі Control Center — підключення чат-застосунку змінює налаштування робочого простору
Право створювати й установлювати застосунки в робочому просторі Slack
Нічого публічно доступного: з’єднання вихідне (Socket Mode), тож серверу не потрібні вхідний порт, тунель чи домен

Три способи отримати застосунок

Шлях	Що надаєте ви	Що робить Control Center
Покроковий	Токен конфігурації застосунку (`xoxe-…`)	Створює застосунок із потрібними областями доступу, подіями, Socket Mode і slash-командою; передає вам два кроки, для яких у Slack немає API
Створити в Slack	Нічого	Відкриває Slack із тією самою конфігурацією, уже заповненою; ви вибираєте робочий простір і підтверджуєте
Вручну	Токени готового застосунку	Перевіряє їх і підключає

Лише покроковий шлях ще й залишає застосунок керованим із Control Center — саме це уможливлює Налаштувати чат-бота. Застосунок, створений через Створити в Slack, можна згодом перевести в керований, вставивши токен конфігурації в діалозі підключення.

Кнопки «установити застосунок Slack від Control Center» навмисно немає. Установлення розповсюджуваного застосунку Slack потребує спільного клієнтського секрету (у Slack немає PKCE), а Socket Mode розподіляє події застосунку випадково між його з’єднаннями — тож один спільний застосунок доставляв би повідомлення вашого робочого простору на сервери інших людей. Тому кожен робочий простір володіє власним застосунком, а ці три шляхи — про те, як мало роботи це від вас вимагає.

Варіант A: дозвольте Control Center створити застосунок

Створіть пару токенів конфігурації застосунку на api.slack.com/apps і скопіюйте токен оновлення (xoxe-…)
У Control Center перейдіть у Налаштування → Робочий простір → Загальні і прокрутіть до картки Чат-мости
У блоці Slack натисніть Створити застосунок за мене
Вставте токен, скоригуйте назву застосунку, ім’я бота, описи та slash-команду, потім натисніть Створити застосунок
Виконайте два кроки, що залишилися, які показує діалог, — кожен як посилання в Slack:
- Basic Information → App-Level Tokens: згенеруйте токен з областю доступу connections:write (xapp-…)
- Install App: установіть у робочий простір і скопіюйте Bot User OAuth Token (xoxb-…)
Натисніть Вставити облікові дані й продовжте з розділу Підключення

Токен конфігурації оновлюється за кожного використання. Control Center зберігає оновлене значення по ходу, тож вставляти його знову не доведеться.

Варіант B: створіть його в Slack із заповненою конфігурацією

Той самий застосунок, але без токена конфігурації — Slack відкриває власний екран створення з уже заповненим маніфестом.

У Control Center перейдіть у Налаштування → Робочий простір → Загальні і прокрутіть до картки Чат-мости
У блоці Slack натисніть Створити застосунок за мене
Скоригуйте назву застосунку, ім’я бота, описи та slash-команду — вони передаються разом із посиланням
Натисніть Створити в Slack. Браузер відкриє сторінку створення застосунку Slack із уже заповненою конфігурацією
Виберіть робочий простір Slack і підтвердьте. Області доступу, події, Socket Mode і slash-команда вже правильні
Повернувшись у Control Center, виконайте два кроки, що залишилися, які показує діалог:
- Basic Information → App-Level Tokens: згенеруйте токен з областю доступу connections:write (xapp-…)
- Install App: установіть у робочий простір і скопіюйте Bot User OAuth Token (xoxb-…)
Натисніть Вставити облікові дані й продовжте з розділу Підключення

Slack не повідомляє, який застосунок він створив, тож Control Center не дізнається ідентифікатор застосунку, і посилання на кроці 6 ведуть до списку ваших застосунків, а не прямо до цього застосунку. Для Налаштувати бота потрібен токен конфігурації.

Варіант C: зберіть застосунок самостійно

Створіть застосунок на api.slack.com/apps, потім налаштуйте його так.

Socket Mode: увімкніть його й залиште всі request URL порожніми. Slack відхиляє маніфест, який просить і Socket Mode, і доставку через вебхуки.

Області доступу токена бота (OAuth & Permissions):

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

Підписки на події (події бота):

app_home_opened
app_mention
message.channels
message.groups
message.im

Саме message.channels і message.groups забезпечують роботу відповіді в уже підключеній гілці Slack. Без них доходить лише перша згадка.

Slash-команда: /cc (підійде будь-яка назва — міст використовує ту команду, якою його викликали останньою).

App Home: увімкніть вкладку Messages і залиште її доступною для запису, щоб учасники могли писати боту в особисті повідомлення.

Токени: згенеруйте токен застосунку з областю доступу connections:write, потім установіть застосунок і скопіюйте токен OAuth користувача-бота.

Підключення

Перейдіть у Налаштування → Робочий простір → Загальні і прокрутіть до картки Чат-мости
У блоці Slack натисніть Підключити Slack
Заповніть поля:

Поле	Значення	Де це міститься в Slack
Токен бота	`xoxb-…`	OAuth & Permissions → Bot User OAuth Token
Токен застосунку	`xapp-…`	Basic Information → App-Level Tokens (`connections:write`)
Токен конфігурації застосунку (необов’язково)	`xoxe-…`	Пара токенів конфігурації застосунку на api.slack.com/apps

Префікс кожного значення перевіряється з обох боків, перш ніж щось надішлеться, тож значення, вставлене не в те поле, відхиляється в будь-якому разі з тією самою фразою.

Натисніть Підключити

Control Center перевіряє токен бота через auth.test Slack перед тим, як щось зберегти, тож одруківка повідомляється вам, а не перетворюється на сокет, який тихо ніколи не працює. Токен застосунку можна підтвердити лише відкриттям сокета, тож невірний проявляється мить пізніше як помилка з’єднання в тому самому рядку.

Без необов’язкового токена конфігурації застосунку з’єднання працює нормально — ви просто не можете редагувати бота з Control Center.

Що робить підключення

Зберігає облікові дані у власному каталозі робочого простору, поруч із його базою даних, доступні лише для читання власником. Вони ніколи не повертаються назад клієнту
Відкриває для цього робочого простору одне з’єднання Socket Mode і починає отримувати згадки, відповіді в гілках Slack, особисті повідомлення та slash-команди
Знову бере на себе кожну раніше підключену гілку Slack, тож перепідключення продовжує наявні розмови, а не залишає їх покинутими
Нічого не коштує для робочих просторів без чат-застосунку: ні сокета, ні таймерів, ні трафіку

Облікові дані бота — це один звичайний JSON-файл на провайдера за шляхом <dataDir>/<workspaceId>/chat_credentials/, записаний атомарно й доступний лише власнику. Це зроблено навмисно, а не через недогляд: видалення робочого простору відв’язує цей каталог, тож його токени зникають разом із ним, а workspace.export і резервні копії копіюють workspace.db — не каталог — тож робочий простір, який ви передаєте комусь іншому, ніколи не несе всередині живих токенів бота. Наслідок: відновлення робочого простору в іншому місці означає, що Slack там потрібно підключити заново.

Доступ до мосту визначається членством у робочому просторі, а не володінням токеном. Обліковий запис Slack має бути прив’язаний до користувача Control Center, який є учасником із роллю, що дає право запису. Підключення, відключення, покрокове налаштування, посилання налаштування й налаштування бота — усе це доступне лише адміністраторам.

Перевірка

У рядку Slack відображається тег стану: Наживо, Підключення…, Помилка з’єднання (поруч — власна помилка Slack) або Не підключено. Щоб перевірити все від початку до кінця:

У Slack запросіть бота в канал: /invite @your-bot-name
Згадайте його із запитом
У гілці 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 відхилить цілком. Повний текст завжди є в транскрипті простору.

Пов’язані посібники

Пов’язані поняття

Чат-мости