Разворачивание ссылок

Unfurling — это создание превью ссылки в сообщении. Когда пользователь отправляет ссылку на один из отслеживаемых доменов, бот получает вебхук, извлекает данные по URL из вашего сервиса и отправляет превью обратно в Пачку. В результате все участники чата видят заголовок, описание и изображение — даже если у них нет доступа к ресурсу.

Как это работает

Создайте Unfurl-бота

Перейдите в Автоматизации > Интеграции > Чат-боты и Вебхуки и создайте бота с типом Unfurl бот. Создать такого бота может только владелец пространства или участник с ролью «Администратор». Подробнее — в разделе Боты.

Укажите домены

В настройках Unfurl-бота укажите до 5 доменов, ссылки на которые бот будет отслеживать. Бот отслеживает ссылки во всех чатах пространства — добавлять его в конкретные чаты не нужно.

Настройте исходящий вебхук

На вкладке Исходящий Webhook укажите URL вашего сервера и включите событие Отправка ссылок. Подробнее — в разделе Исходящие вебхуки.

Обработайте вебхук

При появлении ссылки на отслеживаемый домен бот получит вебхук с массивом обнаруженных ссылок. Извлеките данные из вашего сервиса по полученным URL.

Отправьте превью

Вызовите метод POSTUnfurl (разворачивание ссылок), передав заголовок, описание и изображение для каждой ссылки.

Правила распознавания доменов

  • Формат: example.com или subdomain.example.com
  • Протокол не указывается — отслеживаются и http, и https
  • Поддомены включаются автоматически: example.com покрывает sub.example.com
  • Пути и параметры не учитываются — проверяется только домен
  • IP-адреса и порты не поддерживаются

Вебхук о ссылке

При появлении ссылки на отслеживаемый домен бот получает вебхук с типом link_shared:

LinkSharedWebhookPayloadobject

Создание превью

Для создания превью используйте метод POSTUnfurl (разворачивание ссылок), передав message_id из вебхука.

Тело запроса — объект link_previews, где каждый ключ — URL из массива links вебхука:

Unfurl (разворачивание ссылок)
curl "https://api.pachca.com/api/shared/v1/messages/194275/link_previews" \  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \  -H "Content-Type: application/json" \  -d '{  "link_previews": {    "https://website.com/articles/123": {      "title": "Статья: Отправка файлов",      "description": "Пример отправки файлов на удаленный сервер",      "image_url": "https://website.com/img/landing.png",      "image": {        "key": "attaches/files/93746/e354fd79-9jh6-f2hd-fj83-709dae24c763/${filename}",        "name": "files-to-server.jpg",        "size": 695604      }    }  }}'

Изображение можно указать двумя способами:

  • По ссылке — параметр image_url с публичным URL изображения
  • Загрузкой файла — параметр image с данными, полученными через метод POSTЗагрузка файлов. Если указаны оба параметра, image является приоритетным

Если среди переданных URL будет ошибка (URL отсутствует в сообщении или домен не указан в настройках бота), запрос не будет выполнен — не будет создано ни одного превью.

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