Unfurling ссылок в Пачке

👉 сейчас в открытой Beta

Что такое Unfurl?

Unfurl (развертывание) - это процесс создания превью ссылки. Когда пользователь отправляет ссылку в чат, функция unfurl позволяет показать предварительный просмотр содержимого этой ссылки, включая заголовок, описание и изображение.

Эта функция особенно полезна, когда контент по ссылке доступен только по авторизации. В таких случаях unfurl позволяет предоставить краткую информацию о содержимом ссылки всем участникам чата, даже если у них нет прямого доступа к ресурсу.

Как работает Unfurl в Пачке

Процесс работы Unfurl в Пачке состоит из трех основных этапов:

1. Создание Unfurl бота администратором рабочего пространства.
2. Получение вебхука ботом при отправке сообщения с ссылкой.
3. Использование метода публичного API для создания превью ссылки.

Создание Unfurl бота

Только администратор рабочего пространства может создать Unfurl бота. При создании бота необходимо указать домены, для которых будет работать развертывание (максимум 5 доменов).

Процесс создания бота:

1. Выберите раздел "Автоматизации" > "Интеграции" > "Чат-боты и Вебхуки".
2. Нажмите "Создать нового бота" и выберите тип "Unfurl бот".
3. Укажите имя бота и до 5 доменов, для которых будет работать развертывание.
4. Сохраните настройки и получите access_token для работы с API.

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

• Домены должны иметь корректный формат (например, example.com или subdomain.example.com).
• Протокол (http:// или https://) не указывается при настройке домена.
• Поддомены автоматически включаются. Например, если указан example.com, то subdomain.example.com также будет обрабатываться.
• Пути и параметры URL не учитываются при сопоставлении доменов.
• IP-адреса не поддерживаются в качестве доменов.
• Порты в URL игнорируются при сопоставлении доменов.

Получение вебхука

Когда в любом чате рабочего пространства отправляется сообщение, содержащее ссылку на один из указанных доменов, Пачка отправляет вебхук Unfurl боту.

Вебхук приходит в следующих случаях:

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

Пример вебхука с несколькими ссылками:

{
  "type": "message",
  "event": "link_shared",
  "chat_id": 23438,
  "created_at": "2024-09-18T19:53:14.000Z",
  "message_id": 268092,
  "links": [
    {
      "url": "https://example.com/page1",
      "domain": "example.com"
    },
    {
      "url": "https://subdomain.example.org/page2",
      "domain": "example.org"
    }
  ]
}

Использование метода публичного API

Для создания превью ссылки используется метод публичного API Пачки. Этот метод доступен только для Unfurl ботов, созданных администратором рабочего пространства.

Актуальная документация метода доступна по ссылке.

Метод API

POST https://api.pachca.com/api/shared/v1/messages/{message_id}/link_previews

Пример запроса с несколькими ссылками

{
    "link_previews": {
        "https://example.com/page1": {
            "title": "Заголовок страницы 1",
            "description": "Описание страницы 1",
            "image_url": "https://example.com/image1.jpg"
        },
        "https://subdomain.example.org/page2": {
            "title": "Заголовок страницы 2",
            "description": "Описание страницы 2",
            "image": {
                "key": "путь/к/файлу/изображения2.jpg",
                "name": "изображение2.jpg",
                "size": 12345
            }
        }
    }
}

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