Как создать Slack‑бота для автоматического приветствия новых участников канала

Важно: храните SLACK_BOT_TOKEN и SLACK_SIGNING_SECRET в приватном .env и никогда не выкладывайте их в публичные репозитории.

Что вы получите

• Рабочий Slack‑бот, который приветствует новых участников.
• Пример кода на Python с Flask и slackeventsapi.
• Инструкции по тестированию локально через ngrok и замене ngrok альтернативами.
• Контроль безопасности, GDPR‑заметки и чек‑листы для разных ролей.

Основной сценарий и варианты использования

Основная цель: автоматическое приветствие новых пользователей в публичных/приватных каналах. Возможные варианты: отправка приватного DM, приглашение в специальный канал, хранение статистики приветствий, логирование в внешнюю систему.

Изображения (с описанием)

1. Создание приложения Slack и получение токена API

1. Зарегистрируйтесь в Slack или войдите в существующий аккаунт. Создайте тестовую рабочую область (workspace) для разработки и проверки бота.

2. Войдите в новую рабочую область. Slack создаёт общую начальную комнату.

3. Перейдите на сайт Slack API (api.slack.com). В разделе Apps нажмите «Create an app», затем выберите «From scratch».

4. Задайте имя приложения и укажите рабочую область для разработки.

5. После создания перейдите в раздел приложения и найдите Signing Secret в разделe Basic Information — он понадобится для проверки подлинности входящих запросов от Slack.

6. Откройте OAuth & Permissions. В разделе Bot Token Scopes добавьте права:

• users:read — чтобы бот мог читать информацию о пользователях;
• chat:write — чтобы бот мог отправлять сообщения.

7. Установите приложение в рабочую область (Install to Workspace) и подтвердите разрешения. После установки сохраните Bot User OAuth Token из раздела OAuth & Permissions — это SLACK_BOT_TOKEN. Бот появится в разделе Apps вашей рабочей области.

2. Подготовка окружения и установка зависимостей

Требования: базовые знания Python. Создайте виртуальное окружение и файл .env в корне проекта. В .env будут храниться SLACK_BOT_TOKEN и SLACK_SIGNING_SECRET.

Установите зависимости:

pip install slack-sdk pathlib python-dotenv flask slackeventsapi

Примечание: пакет для работы с .env обычно называется python-dotenv (в некоторых системах dotenv). Мы используем load_dotenv из python-dotenv.

Кратко о библиотеках:

• slack-sdk — клиент для Web API Slack;
• pathlib — удобная работа с путями;
• python-dotenv — загрузка переменных окружения из .env;
• flask — лёгкий HTTP‑сервер;
• slackeventsapi — адаптер для приёма событий Slack.

Полный исходный код можно хранить в репозитории, но файл .env не следует добавлять в git (добавьте его в .gitignore).

3. Импорт библиотек и стартовый код

Создайте файл app.py и импортируйте нужные модули:

import slack_sdk as slack
import os
from pathlib import Path
from dotenv import load_dotenv
from flask import Flask
from slackeventsapi import SlackEventAdapter

load_dotenv загрузит значения SLACK_BOT_TOKEN и SLACK_SIGNING_SECRET из .env.

4. Настройка Flask и SlackEventAdapter

app = Flask(__name__)
env_path = Path('.') / '.env'
load_dotenv(dotenv_path=env_path)

slack_event_adapter = SlackEventAdapter(
    os.environ['SLACK_SIGNING_SECRET'],
    '/slack/events',
    app
)

client = slack.WebClient(token=os.environ['SLACK_BOT_TOKEN'])
BOT_ID = client.api_call("auth.test")['user_id']

GREETING_MESSAGE = "Hello {user_name}, welcome to the {channel_name} channel! We're excited to have you here."
welcomed_users = set()

Пояснения:

• /slack/events — публичный endpoint, на который Slack отправляет события;
• client.api_call(“auth.test”) — даёт ID бота;
• welcomed_users — множество, которое предотвращает повторные приветствия одному и тому же пользователю во время жизни процесса.

5. Обработчик события member_joined_channel

@slack_event_adapter.on('member_joined_channel')
def handle_member_joined_channel(event_data):
    user_id = event_data['event']['user']
    channel_id = event_data['event']['channel']

    # Отправляем приветствие только если пользователь ещё не получал его
    if user_id not in welcomed_users:
        welcomed_users.add(user_id)

        user_info = client.users_info(user=user_id)
        user_name = user_info['user']['name']

        channel_info = client.conversations_info(channel=channel_id)
        channel_name = channel_info['channel']['name']

        greeting = GREETING_MESSAGE.format(user_name=user_name, channel_name=channel_name)

        client.chat_postMessage(channel=channel_id, text=greeting)

Пояснение: event_data содержит подробности события. Мы получаем user и channel, делаем дополнительные вызовы API для красивой строки приветствия и отправляем сообщение.

6. Запуск приложения локально

if __name__ == "__main__":
    app.run(debug=True, port=5000)

Важно: debug=True удобен для разработки, но опасен в продакшене. В продакшен‑среде используйте production WSGI‑сервер (gunicorn/uvicorn) и отключите режим отладки.

7. Экспонирование локального сервера и подписка на события

1. Скачайте и запустите ngrok. Он создаёт публичный HTTPS‑адрес для локального порта.

ngrok http 5000

Скопируйте адрес, например https://abcd1234.ngrok.io.

2. В Slack API откройте Event Subscriptions и включите их. В поле Request URL введите ваш ngrok URL + /slack/events, например https://abcd1234.ngrok.io/slack/events.

3. Подпишитесь на событие member_joined_channel. Сохраните изменения и при необходимости переустановите приложение после изменения scope.

8. Тестирование бота

• В рабочей области найдите бота в списке приложений и добавьте его в нужный канал.
• Пригласите нового пользователя в канал или создайте тестовый пользовательский аккаунт и подключитесь к каналу.
• Бот отправит приветственное сообщение в канал.

9. Улучшения и альтернативные подходы

Ниже — идеи, которые можно реализовать поверх базового сценария.

• Приватные приветственные сообщения (DM) вместо публичных.
• Персонализация на основе профиля пользователя (фамилия, роль, отдел).
• Хранение статистики приветствий в базе данных (Postgres, Redis).
• Интерфейс управления шаблонами приветствий (админ‑панель).

10. Альтернативы ngrok для проброса локального порта

• localtunnel — простой, бесплатный. Команда: npx localtunnel –port 5000
• Cloudflare Tunnel (argo) — безопасный и пригоден для продакшен‑подключения.
• Развернуть приложение в облаке (Heroku, Render, Vercel, AWS/GCP) и использовать постоянный публичный URL.

11. Безопасность и эксплуатация

• Храните токены в секретном хранилище (Vault, AWS Secrets Manager) для продакшена.
• Ограничьте права бота — давайте только необходимые scope.
• Периодически ревокируйте и обновляйте токены.
• Включите логирование входящих событий и ошибок (Sentry или аналог).

Краткие рекомендации по защите endpoint:

• Проверяйте подпись запросов Slack через signing secret (SlackEventAdapter делает это автоматически).
• Принимайте только POST запросы с корректными заголовками.

12. Конфиденциальность и соответствие GDPR

Если в приветствиях используются персональные данные (имя, должность), учтите требования конфиденциальности:

• Информируйте сотрудников о работе бота и о том, какие данные используются.
• Храните минимальный набор данных и удаляйте логи старых событий по регламенту.
• Если пользователи вправе требовать удаления данных, предоставьте процедуру удаления логов/записей.

13. Тесты и критерии приёмки

Критерии приёмки:

• Бот успешно получает event member_joined_channel и отвечает в течение допустимого времени (обычно < 5 с при нормальной сети).
• Бот не дублирует приветствия одному и тому же пользователю при повторных подключениях в рамках одной сессии сервера.
• Бот корректно обрабатывает приватные и публичные каналы.

Минимальные тест‑кейсы:

1. Новый пользователь присоединяется к публичному каналу — бот публикует приветствие.
2. Пользователь, который уже был вами разприветствован, вновь присоединяется — бот не дублирует сообщение (в пределах запущенного процесса).
3. Ошибка вызова users_info или conversations_info — бот логирует ошибку и не падает.
4. Неправильный signing secret — Slack не подтвердит Request URL (проверьте логи ngrok и статус в Slack).

14. Чек‑листы по ролям

Разработчик:

• Создал виртуальное окружение и установил зависимости.
• Настроил .env и локально загрузил секреты.
• Проверил работу обработчика локально через ngrok/localtunnel.

Администратор Slack:

• Создал приложение Slack и установил его в рабочую область.
• Добавил необходимые scopes и повторно установил приложение.
• Включил Event Subscriptions и указал валидный Request URL.

Операции/DevOps:

• Перенёс приложение на постоянный URL/сервер для продакшена.
• Организовал безопасное хранение секретов.

15. Типовые ошибки и способы их устранения

• Ошибка валидации Request URL: проверьте, что публичный адрес доступен по HTTPS и возвращает 200 на вызов Slack для проверки.
• 401 Unauthorized при вызовах Web API: проверьте SLACK_BOT_TOKEN.
• Пустые значения user_name или channel_name: убедитесь, что у бота есть scope users:read и conversations:read, и что канал не является приватным без доступа.

16. Развёртывание в продакшен — быстрая инструкция

1. Забейте секреты в менеджер секретов.
2. Разверните на надежном хостинге (Heroku/Render/AWS).
3. Установите HTTPS‑домен и укажите его как Request URL в Slack.
4. Настройте мониторинг и автоматический перезапуск процесса.

17. Решение: обязателен ли Bot ID и welcomed_users?

• BOT_ID полезен если бот должен игнорировать события, где он сам является актором.
• welcomed_users в памяти процесса — простая защита против дублирования в одной сессии. Для устойчивой работы при перезапуске используйте базу данных (Redis).

18. Decision flowchart

Ниже — простая диаграмма принятия решения при обработке события (Mermaid):

flowchart TD
  A[Получено событие member_joined_channel] --> B{Пользователь уже был поприветствован?}
  B -- Да --> C[Игнорировать]
  B -- Нет --> D[Получить user_info и channel_info]
  D --> E{Вызовы API успешны?}
  E -- Да --> F[Отправить приветствие]
  E -- Нет --> G[Залогировать ошибку и уведомить админа]

19. Короткая методология разработки

1. Начните с локального прототипа и ngrok.
2. Добавьте логирование и обработку ошибок.
3. Перенесите состояние (welcomed_users) из памяти в внешнюю систему, если нужно.
4. Проведите аудит прав доступа приложения.

20. Глоссарий (1‑строчные определения)

• Bot User OAuth Token — токен бота, дающий доступ к Web API.
• Signing Secret — секрет для проверки подписи запросов от Slack.
• Event Subscriptions — подписка приложения на события Slack.

21. Пример короткого объявления для команды (используйте при запуске бота)

Мы запускаем нового Slack‑бота приветствий. Он будет автоматически приветствовать новых участников канала. Если вы не хотите получать публичное приветствие — сообщите в #it‑help, и мы изменим шаблон или перенесём приветы в личные сообщения.

22. Резюме

• Создайте приложение в Slack, дайте ему права users:read и chat:write.
• Сохраните SLACK_BOT_TOKEN и SLACK_SIGNING_SECRET в .env.
• Настройте Flask + SlackEventAdapter и подпишитесь на member_joined_channel.
• Тестируйте локально через ngrok, затем безопасно разверните в продакшен.

Ключевые материалы: код обработчика, список прав (scopes), чек‑листы для ролей, тест‑кейсы и список распространённых ошибок помогут собрать и безопасно эксплуатировать бота.