Интеграция Welcome Bot + Пачка

Репозиторий: https://github.com/pachca/public-integrations/tree/main/welcome-bot

Welcome Bot позволяет онбордить новых сотрудников. Он срабатывает, когда пользователь присоединяется к рабочему пространству, и автоматически пишет ему в личные сообщения. Это может быть короткое приветствие, список полезных ссылок или объяснение, как устроены ваши рабочие чаты.

Варианты работы

У этой интеграции мы подготовили три варианта для развертывания:

• На своем устройстве, чтобы протестировать работу бота
• Разворачивание на ресурсах сторонних сервисов (как Vercel в нашем варианте)
• На своем сервере

Ниже будет инструкция по локальному развертыванию бота и быстрому запуску на Vercel для команд, которым не хочется разбираться с арендой и настройкой своих серверов. Другие способы запуска бота описаны в README интеграции на GitHub.

Общие настройки бота

Шаг 1. Создайте Welcome Bot в Пачке

1. Откройте Автоматизации → Чат-боты и вебхуки.
2. Добавьте нового бота для нескольких чатов.
3. Дайте ему понятное название, например, Welcome Bot.
4. Сделайте бота публичным — иначе он не сможет создавать личные чаты с пользователями.
5. Выберите тип события исходящего Webhook: «Изменение участников пространства».
6. Сохраните токен бота (access_token) и Signing secret — они понадобятся далее.

Шаг 2. Настройте файл .env

Для работы бота необходимо настроить переменные окружения, которые бот использует для отправки приветственных сообщений.

В репозитории есть файл-пример .env.example — в нем указаны используемые переменные. Скопируйте этот файл, переназовите его в .env и заполните вашими переменными.

• PACHCA_TOKEN (токен вашего бота)
• PACHCA_WEBHOOK_SECRET (секрет для проверки подписи исходящего Webhook)
• WELCOME_MESSAGE_TYPE (шаблон сообщения)
  
  • Шаблоны хранятся в файле messages.yml — в нем же отредактируйте желаемый шаблон. Short подходит для очень коротких сообщений в одну строку, Default — это стандартный шаблон, а Extended нужен в том случае, если вы будете прикреплять ссылки и более подробные инструкции.

Остальные переменные в файле доступны опционально. В целях безопасности можете убрать # и сделать их активными. Посоветуйтесь с тех. спецами вашей команды :)

Локальный запуск через Docker

Как правило, этот пункт нужен только для проверки работоспособности бота. Если вам не нужно проверять бота, вы сразу же можете задеплоить его на Vercel или свой сервер.

Для упрощения процесса проверки рекомендуем запускать бота через Docker. Так вам не нужно будет устанавливать Ruby, гемы для него и зависимости. Для этого необходимо скачать Docker с их официального сайта, а дальше провести установку по инструкции ниже.

1) Проверьте версию Docker‍

docker --version и docker-compose --version

2) Скачайте проект и подготовьте окружение, если не сделали этого ранее

git clone https://github.com/pachca/public-integrations.git

cd public-integrations/welcome-bot

3) Запустите контейнер‍

docker-compose up -d

Для работы с Пачкой боту нужен публичный URL, чтобы отправлять на него вебхуки. Для этого необходимо скачать ngrok.

4) Откройте отдельный терминал (параллельно с ботом,запущенным через Docker), а затем установите и запустите там ngrok:

npm install -g ngrok

ngrok http 4567

После запуска ngrok покажет вам URL вида https://xxxx-xx-xx-xxx-xx.ngrok-free.app. На этот URL бот будет отправлять уведомления о новых участниках пространства, которым нужно отправить приветственные сообщения.

5) Настройте вебхук в Пачке, указав URL в формате:

https://xxxx-xx-xx-xxx-xx.ngrok-free.app/api/webhook

Примечание: Обратите внимание, что бесплатный URL ngrok меняется при каждом запуске, поэтому подходит только для проверок.

Запуск на Vercel

1. Если у вас еще нет аккаунта Vercel, зарегистрируйтесь на их официальном сайте vercel.com.

2. Дальше нужно скопировать наш репозиторий в ваш GitHub или, если вы его скачали на свое устройство, загрузить его на  и синхронизировать с Vercel

3. После импорта репозитория на Vercel: настройте переменные окружения. Для Vercel они задаются не в файле .env, а на самой платформе. Их можно задать при импорте проекта, а также в разделе "Settings" -> "Environment Variables":‍

• PACHCA_TOKEN (токен вашего бота)
• PACHCA_WEBHOOK_SECRET (секрет для проверки подписи исходящего Webhook)
• WELCOME_MESSAGE_TYPE (шаблон сообщения)
• Другие токены по необходимости

4. Настройте вебхук в Пачке, указав URL вашего приложения с путем /api/webhook (например, https://your-app.vercel.app/api/webhook)

Если вдруг что-то не получилось, описание непонятно или хотелось бы увидеть дополнительные возможности в интеграции, то мы всегда будем рады пообщаться с вами, чтобы улучшить инструкцию. Для этого напишите нашей команде поддержки!

‍