Для разработчиков

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

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

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

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

Откройте Интеграции > Боты и нажмите Создать бота. Подробнее — в разделе Создание бота.

Включите исходящий вебхук

В карточке бота на вкладке Исходящий вебхук нажмите Включить и укажите URL вашего сервера. Подробнее — в разделе Исходящие вебхуки.

Включите событие и укажите домены

В списке событий в группе Ссылки включите Отправка ссылок в сообщении (unfurl) и перечислите через запятую до 5 доменов, ссылки на которые бот будет отслеживать. Бот получает ссылки из всех чатов пространства, поэтому добавлять его в чаты не нужно, а включать и выключать событие, задавать домены, менять адрес исходящего вебхука и включать историю событий у такого бота может только администратор или владелец пространства. Через API это событие message_link_shared в поле events и домены в unfurl_domains метода PUTРедактирование бота.

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

При появлении ссылки на отслеживаемый домен бот получит вебхук с массивом links. Каждый объект содержит url, domain и skip: boolean — если skip равен true, автор сообщения скрыл превью для этой ссылки и бот не должен создавать превью. Извлеките данные из вашего сервиса по оставшимся URL.

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

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

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

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

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

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

LinkSharedWebhookPayloadobject

Поля entity_type, entity_id и thread — те же, что в вебхуке о новом сообщении: по ним видно, в беседе, канале, треде или личной переписке отправлена ссылка. Бот не состоит в этом чате, поэтому в личной переписке entity_id приходит null.

Ссылки из сообщений другого бота приходят, только если у того включён показ превью ссылок во входящем вебхуке. Ссылки из своих сообщений бот не получает, если у него включено «Игнорировать свои сообщения».

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

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

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

Unfurl (разворачивание ссылок)
pachca messages unfurl 194275 \  --link-previews='{"https://example.com/articles/123":{"title":"Статья: Отправка файлов","description":"Пример отправки файлов на удаленный сервер","image_url":"https://example.com/img/landing.png","image":{"key":"attaches/files/93746/e354fd79-9jh6-f2hd-fj83-709dae24c763/${filename}","name":"files-to-server.jpg","size":695604}}}' \  --json \  --token YOUR_ACCESS_TOKEN

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

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

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

Ссылка, для которой автор сообщения скрыл превью, — не ошибка: она пропускается, а остальные превью из того же запроса создаются.

Веб-версия и десктопное приложение показывают в сообщении до пяти превью — те, у которых есть заголовок, описание или изображение.