Команды «/» и кнопки

Команды «/» появляются в подсказках поля ввода на серверах, где есть бот. Когда человек вызывает команду или нажимает кнопку под сообщением бота, боту приходит событие INTERACTION_CREATE, и он должен ответить в течение 3 секунд.

Регистрация команд

Глобальные команды действуют на всех серверах бота, серверные — только на одном (удобно для отладки). PUT заменяет весь набор: команды, которых нет в списке, удаляются.

curl -X PUT https://voice-chat.ru/api/applications/@me/commands \
  -H "Authorization: Bot $VOICE_TOKEN" -H "Content-Type: application/json" \
  -d '[{
    "name": "погода",
    "description": "Погода в городе",
    "options": [
      { "type": "string", "name": "город", "description": "Город", "required": true },
      { "type": "string", "name": "единицы", "description": "Шкала",
        "choices": [{ "name": "Цельсий", "value": "c" }, { "name": "Фаренгейт", "value": "f" }] }
    ]
  }]'

Формат команды

Сервер проверяет значения до того, как событие уйдёт боту: числа — в границах, user — участник этого сервера, channel — канал этого сервера, role — роль сервера. Боту приходят уже проверенные значения: для user/channel/role — id.

Событие INTERACTION_CREATE

{
  "id": "1791234567890123456",
  "token": "q2V…",
  "type": "command",
  "applicationId": "1790000000000000001",
  "channelId": "c_…",
  "serverId": "s_…",
  "user": { "id": "u_…", "username": "alice", "displayName": "Алиса", "avatar": "/uploads/avatars/…" },
  "data": {
    "id": "1790000000000000777",
    "name": "погода",
    "options": [{ "name": "город", "type": "string", "value": "Казань" }]
  }
}

{
  "id": "…", "token": "…", "type": "component",
  "applicationId": "…", "channelId": "c_…", "serverId": "s_…",
  "user": { "id": "u_…", "username": "alice", "displayName": "Алиса" },
  "message": { "id": "m_…", "content": "Голосование", "components": [ … ] },
  "data": { "customId": "vote_yes", "componentType": "button" }
}

Ответ

POST /api/interactions/:id/:token/callback — один раз, в течение 3 секунд. Если не ответить, человек увидит «… не ответил вовремя».

// d — данные INTERACTION_CREATE
await fetch(`https://voice-chat.ru/api/interactions/${d.id}/${d.token}/callback`, {
  method: "POST",
  headers: { Authorization: `Bot ${TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    type: "message",
    data: { content: "Видно только вам 🤫", ephemeral: true },
  }),
});

Ответ «видно только вам»

ephemeral: true (или flags: 64, как в Discord) — сообщение получает только вызвавший; оно нигде не хранится и пропадает после перезагрузки.

Продолжения

Токен взаимодействия действует 15 минут и только для бота, которому пришло событие. Полный список полей — в справочнике.