Компоненты сообщений

Боты прикрепляют к сообщениям components в формате Discord точно так же, как в Discord, а клик приходит как INTERACTION_CREATE с обычным токеном и обратным вызовом, так что библиотеки менять не нужно. На этой странице описано, что отображает GameVox, как взаимодействия доходят до вашего приложения и в чём ограничения отличаются от Discord.

Что работает

Строки действий (тип 1) с кнопками (тип 2, стили 1–5) и текстовыми списками выбора (тип 3). Кнопка-ссылка (стиль 5) открывает свой url и никогда не отправляет взаимодействие.
Облачные и собственные серверы. Компоненты хранятся вместе с сообщением и возвращаются при чтении через REST и в MESSAGE_CREATE / MESSAGE_UPDATE. Правка сообщения с components: [] удаляет их.
Все клиенты. Клиент для компьютера и веба, iOS и Android отображают кнопки и текстовые списки выбора (не более 5 строк по 5 элементов на сообщение), а также модальные окна и эфемерные ответы.
Модальные окна (обратный вызов типа 9) и эфемерные ответы (flags: 64), описанные ниже.

Сообщение со строкой кнопок и списком выбора:

POST /api/v10/channels/{channel_id}/messages

{
  "content": "Next map?",
  "components": [
    {
      "type": 1,
      "components": [
        { "type": 2, "style": 1, "label": "Vote", "custom_id": "vote" },
        { "type": 2, "style": 5, "label": "Rules", "url": "https://example.com/rules" }
      ]
    },
    {
      "type": 1,
      "components": [
        {
          "type": 3,
          "custom_id": "map",
          "placeholder": "Pick a map",
          "options": [
            { "label": "Dust", "value": "dust" },
            { "label": "Nuke", "value": "nuke" }
          ]
        }
      ]
    }
  ]
}

Не поддерживается

Списки выбора пользователей, ролей, упоминаемых и каналов (типы 5–8). Они принимаются и сохраняются, но клиенты показывают их отключёнными, поэтому они никогда не вызывают взаимодействие.
Компоненты v2 (компоненты разметки). Не отображаются.
Премиум-кнопки (стиль 6). Показываются отключёнными.
ЛС. Взаимодействия с компонентами, модальные окна и эфемерные ответы работают только в каналах сервера.

Получение клика

Клик приходит как INTERACTION_CREATE с type: 3 (MESSAGE_COMPONENT) и содержит data.custom_id, data.component_type, а для списка выбора ещё data.values. message – это полное сообщение, по которому кликнули, вместе с компонентами, независимо от интентов вашего бота. Отправленное модальное окно приходит как type: 5 (MODAL_SUBMIT) с введёнными значениями в data.components.

GameVox сверяет каждый клик с сохранённым сообщением, прежде чем его увидит ваше приложение: элемент должен по-прежнему быть в сообщении и быть включён, значения списка выбора должны входить в его варианты и укладываться в min_values / max_values, а участник должен видеть канал. Клик доставляется только тому приложению, чей бот опубликовал сообщение.

Взаимодействия доставляются через подключение вашего бота к шлюзу или отправляются POST на ваш URL эндпоинта взаимодействий, если он задан (см. OAuth2). В режиме HTTP два момента отличаются от Discord:

Всё равно держите сессию шлюза подключённой. GameVox передаёт каждое взаимодействие вашему приложению через неё и только потом отправляет POST на ваш эндпоинт. Без подключённой сессии ничего не доставляется, а участнику, который кликнул, сообщают, что приложение не в сети.
Тело ответа игнорируется. Отвечайте вызовом POST /interactions/{id}/{token}/callback; обратный вызов, возвращённый в теле ответа на POST, никуда не попадёт.

Ответ

Через обычный эндпоинт обратного вызова. Токен взаимодействия действует 15 минут.

Тип	Действие
`4` `CHANNEL_MESSAGE_WITH_SOURCE`	Публикует ответ в канале. С `flags: 64` ответ эфемерный.
`5` `DEFERRED_CHANNEL_MESSAGE_WITH_SOURCE`	Подтверждает сразу; первый `PATCH .../messages/@original` публикует ответ. С `flags: 64` этот ответ эфемерный.
`6` `DEFERRED_UPDATE_MESSAGE`	Подтверждает без видимых изменений. После этого `@original` указывает на сообщение, по которому кликнули, так что последующий `PATCH .../messages/@original` его редактирует.
`7` `UPDATE_MESSAGE`	Редактирует на месте сообщение, по которому кликнули, включая компоненты.
`9` `MODAL`	Открывает модальное окно для участника, который кликнул.

Последующие сообщения (до 5 на взаимодействие, flags: 64 для эфемерных) и GET / PATCH / DELETE для @original и последующих сообщений работают как в Discord. Типы 4, 5 и 9 и эфемерные ответы работают и для слэш-команд; типам 6 и 7 нужно сообщение, по которому кликнули.

Эфемерные ответы

Эфемерный ответ получает только участник, вызвавший взаимодействие, в своих открытых сессиях, и он помечен как видимый только ему. Он никогда не записывается в канал: его нет ни в истории сообщений, ни в MESSAGE_CREATE, он исчезает, когда участник перезагружает страницу, а ваше приложение может редактировать или удалять его в течение 15 минут. Компоненты в эфемерном ответе работают как любые другие. На облачных и собственных серверах всё одинаково.

Модальные окна

До 5 строк действий с текстовыми полями (тип 4). Всё остальное в модальном окне отбрасывается. Стиль 1 – одна строка, стиль 2 – абзац.
Заголовок и подписи обрезаются до 45 символов, подсказки – до 100. Поле вмещает до 4000 символов. required по умолчанию true.
GameVox сверяет отправленные данные с открытым модальным окном (обязательные поля, min_length, max_length), прежде чем их увидит ваше приложение.
Модальное окно истекает через 15 минут, и отправить его можно один раз.

Ограничения

components одного сообщения: 64 КиБ JSON на облачных серверах; 128 КиБ и 40 компонентов верхнего уровня на собственных серверах. Запрос больше этого завершается ошибкой 400.
custom_id: до 100 символов; элементом с более длинным значением воспользоваться нельзя. Списки выбора: до 25 значений длиной до 100 символов каждое.
Клики: одно взаимодействие с компонентом на участника и сервер раз в 0,7 секунды. Собственный сервер дополнительно разрешает участнику не более 5 кликов за 5 секунд. Более частые клики отклоняются и до вашего приложения не доходят.
Эфемерные ответы и модальные окна: 120 на приложение для каждого участника за 15-минутное окно, считаются вместе. Правка существующего не считается. При превышении запрос завершается ошибкой 429.
Текст эфемерного ответа: до 4000 символов.

← Назад к документации