Интеграция Unfurl-бот + Пачка

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

Unfurl-бот разворачивает ссылки из рабочих сервисов и показывает для них превью в Пачке. Например, вы можете отправить ссылку на карточку из Trello, Kaiten или на сообщение из Пачки в чат. Вместо простой ссылки для всех будет отображаться небольшое превью того, что указано по ссылке: заголовок, описание или изображение.

Когда пригодится

• Доступ в некоторые рабочие сервисы нужно держать ограниченным, а превью может помочь при оперативном реагировании на ошибки на сервере или для другой задачи
• Коммуникация разработки и поддержки. Оператор поддержки отправляет ссылку на обращение клиента в Helpdesk-системе, а через превью разработка будет видеть вопрос, по которому нужно помочь
• Быстро поделиться контекстом, о чем карточка, которую нужно обсудить

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

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

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

Также в боте уже написаны обработчики ссылок для Пачки Trello и Kaiten. А если вам нужно добавить обработчики для других инструментов, в README есть шаблон по их написанию.

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

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

Шаг 1. Создайте Unfurl-бота в Пачке

1. Откройте Автоматизации → Чат-боты и вебхуки.
2. Добавьте нового Unfurl бота.
3. Сохраните две переменные:
   • UNFURL_BOT_TOKEN - токен бота во вкладке API
   • PACHCA_WEBHOOK_SECRET - Signing secret на вкладке Исходящих вебхуков.
4. Если нужны превью ссылок на сообщения из Пачки, создайте еще одного бота и сохраните его токен.

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

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

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

Переменные, для которых реализованы обработчики:

• UNFURL_BOT_TOKEN
• PACHCA_WEBHOOK_SECRET
• PACHCA_API_TOKEN
• TRELLO_KEY
• TRELLO_TOKEN
• KAITEN_TOKEN

Kindly reminder: При необходимости добавьте новые обработчики и токены других сервисов. Для упрощения задачи, в нашем репозитории в README есть пример, как можно реализовать новые обработчики.

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

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

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

1. Проверьте версию Docker
2. docker --version docker-compose --version
3. Скачайте проект и подготовьте окружение, если не сделали этого ранее
4. git clone https://github.com/artemypmnchk/pachca_unfurl_public.git cd pachca_unfurl_public
5. Запустите контейнер
6. docker-compose up -d

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

4. Установите ngrok на устройство:
   1. Для Mac: brew install ngrok или скачайте с ngrok.com
   2. Для Windows: скачайте с ngrok.com
   3. Для Linux: sudo snap install ngrok или скачайте с ngrok.com
5. Запустите ngrok в отдельном терминале (параллельно с ботом, запущенным через Docker) этой командой:
6. ngrok http 4567
7. После запуска ngrok покажет вам URL вида https://xxxx-xx-xx-xxx-xx.ngrok-free.app. На этот URL бот будет отправлять ссылки из Пачки, для которых нужно показать превью.
8. Настройте вебхук в Пачке, указав URL в формате:
9. https://xxxx-xx-xx-xxx-xx.ngrok-free.app/v1/unfurl

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

Другие команды для бота описаны в README в нашем репозитории.

Запуск на Vercel

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

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

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

• ‍UNFURL_BOT_TOKEN - токен для авторизации в API Пачки‍
• PACHCA_WEBHOOK_SECRET - Signing secret бота в Пачке
• Другие токены для используемых сервисов (TRELLO_KEY, PACHCA_API_TOKEN, TRELLO_TOKEN, KAITEN_TOKEN и т.д.)

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

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

Для этого напишите нашей команде поддержки в Телеграм бот

‍