Дополнительные поля сообщения

Дополнительные поля (extras) передают вместе с сообщением дополнительную информацию и меняют поведение клиентов. Они хранятся в схеме ключ-значение и передаются в JSON-теле запроса POST /message (Content-Type: application/json).

Пространства имён

Ключи под .extras должны быть в следующем формате: <top-namespace>::[<sub-namespace>::]<action>. Некоторые из пространств имён используются официальными клиентами:

Пространство имён	Описание
client::*	Зарезервировано
client::display	Изменяет способ отображения информации клиентом
client::notification	Настраивает уведомление
android::*	Зарезервировано
android::action	Реагирует на события
ios::*	Зарезервировано
notifly::*	Служебные поля, которые проставляет сервер — не задавайте их сами
Все остальные	Определены конечными пользователями

client::display

contentType

Определение

contentType	описание
text/markdown	По умолчанию; сообщение должно быть отображено как markdown. HTML должен быть проигнорирован.
text/plain	Сообщение будет отображаться как обычный текст. Ссылки могут быть выделены и интерактивны.

Примечание: Notifly по умолчанию рендерит сообщения как markdown. Markdown поддерживает отображение изображений через ![](img url), эти изображения будут автоматически загружены при просмотре сообщения. Аналогично тому, почему удалённое содержимое блокируется по умолчанию в почтовых клиентах, автоматическая загрузка удалённых изображений может использоваться для сбора информации от пользователя.

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

Если сообщение собирается из внешних источников (например, вывода скриптов), рекомендуется явно указать text/plain — обычный текст не интерпретирует markdown и снижает возможные проблемы безопасности.

Пример

{
  "extras": {
    "client::display": {
      "contentType": "text/plain"
    }
  }
}

Поддержка

Клиент	описание
Веб-админка	Использует GitHub Flavored Markdown
Notifly Android	Использует CommonMark

client::notification

click.url

click.url (строка): открывает URL при нажатии на уведомление.

Пример

{
  "extras": {
    "client::notification": {
      "click": {"url": "https://example.com/deploy/42"}
    }
  }
}

Поддержка

Клиент	описание
Notifly Android	Тап по уведомлению открывает URL вместо самого сообщения в ленте
Notifly iOS	Тап по уведомлению открывает URL во встроенной админке (бета)

bigImageUrl

bigImageUrl (строка): показывает большое изображение в уведомлении.

Пример

{
  "extras": {
    "client::notification": {
      "bigImageUrl": "https://placekitten.com/400/300"
    }
  }
}

Поддержка

Клиент	описание
Notifly Android	Может потребоваться развернуть уведомление.

android::action

onReceive.intentUrl

onReceive.intentUrl (строка): открывает URL сразу после доставки уведомления.

Пример

{
  "extras": {
    "android::action": {
      "onReceive": {"intentUrl": "https://example.com/status"}
    }
  }
}

Поддержка

Клиент	описание
Notifly Android	По умолчанию перед открытием показывается диалог подтверждения (настройка «Подтверждать onReceive Intents»). Для беззвучных сообщений (тихие часы, окна обслуживания) URL не открывается.

notifly::*

Поля с префиксом notifly:: проставляет сам сервер. Клиенты читают их, чтобы правильно показать сообщение; отправлять их в своих запросах не нужно.

Ключ	Что означает
notifly::ask	Сообщение — интерактивный вопрос: тип, варианты или поля формы, статус, срок ответа
notifly::delivery	Подсказка доставки. {"silent": true, "reason": "maintenance"} — канал в активном окне обслуживания: сообщение показывается в ленте, но беззвучно и без режима будильника
notifly::screenshot	Ключ скриншота, снятого браузерной проверкой при сбое; клиенты показывают картинку прямо в ленте
notifly::event, notifly::command, notifly::silent	Служебные кадры (статус heartbeat, команды клиенту и т. п.) — не показываются как уведомления; см. WebSocket-протокол