Вложения в сообщениях

Вложения (attachments) позволяют оформить сообщение интеграции: цветная полоса, автор, заголовок, поля в виде таблицы, изображения, подвал, а также интерактивные кнопки и меню. Формат совместим со Slack.

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

Параметры вложения

Основные

• fallback — краткое описание вложения обычным текстом. Используется там, где вложение не отображается, например в уведомлениях.

• color — цвет полосы слева в формате HEX, например #FF8000.

  

• pretext — текст над вложением.

  

• text — основной текст вложения с поддержкой Markdown. Длинный текст сворачивается, и появляется кнопка «Показать ещё».

  

Автор

• author_name — имя автора, показывается в верхней части вложения.
• author_link — ссылка для author_name. Без author_name не используется.
• author_icon — адрес иконки 16×16 пикселей рядом с author_name.

Заголовок

• title — заголовок под информацией об авторе.
• title_link — ссылка для заголовка. Без title не используется.

Поля

fields — массив полей, которые отображаются таблицей внутри вложения. У каждого поля:

• title — заголовок поля, поддерживает эмодзи;
• value — значение с поддержкой Markdown;
• short — true, если значение короткое и его можно показать рядом с другими полями.

Изображения

• image_url — адрес изображения (GIF, JPEG, PNG, BMP или SVG) внутри вложения. Большие изображения уменьшаются с сохранением пропорций.
• thumb_url — адрес миниатюры справа от текста вложения. Рекомендуемый размер — 75×75 пикселей.

Подвал

• footer — текст в нижней части вложения. Текст длиннее 300 символов обрезается с многоточием.
• footer_icon — адрес иконки 16×16 пикселей перед текстом подвала.

Пример

{
  "attachments": [
    {
      "fallback": "Сборка #512 завершилась с ошибками",
      "color": "#FF8000",
      "pretext": "Результат ночной сборки",
      "text": "Сборка **#512** ветки `main` завершилась с ошибками в двух тестах.",
      "author_name": "CI",
      "author_icon": "https://example.ru/ci-icon.png",
      "author_link": "https://ci.example.ru/",
      "title": "Сборка #512",
      "title_link": "https://ci.example.ru/builds/512",
      "fields": [
        {"short": false, "title": "Коммит", "value": "Исправлена валидация формы входа"},
        {"short": true, "title": "Длительность", "value": "12 мин 30 с"},
        {"short": true, "title": "Упавшие тесты", "value": "2"}
      ],
      "image_url": "https://example.ru/coverage.png",
      "footer": "ci.example.ru",
      "footer_icon": "https://example.ru/ci-icon.png"
    }
  ]
}

Интерактивные кнопки и меню

Во вложение можно добавить массив actions — кнопки и выпадающие меню. Когда пользователь нажимает кнопку или выбирает пункт меню, Loop отправляет POST-запрос на integration.url.

{
  "attachments": [
    {
      "text": "Заявка на отпуск от @ivan: 1–14 августа",
      "actions": [
        {
          "id": "approve",
          "name": "Одобрить",
          "type": "button",
          "style": "success",
          "integration": {
            "url": "https://hr.example.ru/actions",
            "context": {"request_id": 42, "decision": "approve"}
          }
        },
        {
          "id": "reject",
          "name": "Отклонить",
          "type": "button",
          "style": "danger",
          "integration": {
            "url": "https://hr.example.ru/actions",
            "context": {"request_id": 42, "decision": "reject"}
          }
        }
      ]
    }
  ]
}

Поле действия	Описание
id	Идентификатор действия внутри сообщения. Если не указан, Loop сгенерирует его сам
name	Текст кнопки или подсказка меню
type	button — кнопка, select — выпадающее меню
style	Оформление кнопки: default, primary, success, good, warning, danger или HEX-цвет
disabled	true — действие неактивно
options	Для меню: массив пунктов {"text": "…", "value": "…"}
data_source	Для меню: users — список пользователей, channels — список каналов вместо options
default_option	Для меню: значение, выбранное по умолчанию
integration.url	Адрес, куда Loop отправит запрос
integration.context	Произвольные данные, которые Loop передаст в запросе без изменений

Запрос от Loop содержит JSON с полями user_id, user_name, channel_id, channel_name, team_id, team_domain, post_id, trigger_id, type, data_source и context. Для меню выбранное значение приходит в context.selected_option.

Ваш сервис может вернуть JSON:

• update — новое содержимое исходного сообщения (например, заменить кнопки на текст «Одобрено»);
• ephemeral_text — временное сообщение, которое увидит только нажавший пользователь.

trigger_id из запроса позволяет открыть интерактивный диалог с формой.

к сведению

Если integration.url указывает на внутренний адрес, системный администратор должен разрешить его в Системная консоль > Окружение > Разработчик > Разрешить недоверенные внутренние соединения для.

Отправка через REST API

Передайте вложения в props.attachments при создании сообщения методом POST /api/v4/posts:

curl -i -X POST -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <токен>' \
  -d '{"channel_id": "qmd5oqtwoibz8cuzxzg5ekshgr", "message": "Тестовое сообщение", "props": {"attachments": [{"pretext": "Это текст над вложением.", "text": "А это текст вложения."}]}}' \
  https://your-loop-server.ru/api/v4/posts

Ограничения

• Поле ts (время в подвале) не отображается.
• color принимает только HEX-цвет; значения Slack good, warning, danger для полосы не поддерживаются.