Опросы через Discord Webhook: полное руководство по Poll API

Discord добавил нативные опросы на платформу, и их можно отправлять напрямую через вебхуки. Никакого бота, никакого OAuth, никаких сторонних библиотек. Только URL вебхука и JSON-тело запроса. В этом руководстве разберём всё: от структуры объекта до рабочих примеров кода.

Что такое опрос через Discord Webhook?

Опрос в Discord — это интерактивное сообщение, в котором участники сервера голосуют за один из вариантов ответа. При отправке через вебхук Discord отображает его как нативную карточку с кнопками голосования, полосой прогресса и таймером автоматического завершения.

Опросы, отправленные через вебхук, ведут себя точно так же, как созданные через клиент Discord. Участники нажимают кнопку, результаты обновляются в реальном времени, а опрос закрывается автоматически по истечении заданного времени.

Структура объекта poll

Каждый запрос к discord poll api содержит объект poll внутри тела вебхука. Вот что означает каждое поле:

{
  "poll": {
    "question": { "text": "Что вам больше нравится?" },
    "answers": [
      { "poll_media": { "text": "Вариант А", "emoji": { "name": "🅰️" } } },
      { "poll_media": { "text": "Вариант Б", "emoji": { "name": "🅱️" } } }
    ],
    "duration": 24,
    "allow_multiselect": false,
    "layout_type": 1
  }
}

question.text — Текст вопроса. Только обычный текст, до 300 символов. Markdown и эмбеды не поддерживаются.

answers — Массив вариантов ответа. Каждый вариант содержит объект poll_media с полями:

• text — Подпись варианта (до 55 символов)
• emoji — Необязательное поле. Объект с name для Unicode-эмодзи или id для кастомного эмодзи сервера

Допустимо от 1 до 10 вариантов ответа.

duration — Продолжительность опроса в часах. Минимум — 1 час, максимум — 720 часов (30 дней). Создать опрос без срока завершения невозможно.

allow_multiselect — Булево значение. При true участники могут выбрать несколько вариантов. При false каждый участник голосует только за один.

layout_type — На данный момент допустимо только значение 1. Discord может добавить новые типы разметки в будущем, но пока всегда указывайте 1.

Простой опрос

Минимальный payload для discord voting webhook. Без эмодзи, одиночный выбор, закрывается через 48 часов:

{
  "poll": {
    "question": { "text": "Какой день удобнее для встречи сообщества?" },
    "answers": [
      { "poll_media": { "text": "Суббота" } },
      { "poll_media": { "text": "Воскресенье" } },
      { "poll_media": { "text": "Любой день подойдёт" } }
    ],
    "duration": 48,
    "allow_multiselect": false,
    "layout_type": 1
  }
}

Опрос с эмодзи

Эмодзи делают варианты ответа визуально различимыми и удобными для восприятия. Используйте любой стандартный Unicode-эмодзи в поле name:

{
  "poll": {
    "question": { "text": "Что будем стримить следующим?" },
    "answers": [
      { "poll_media": { "text": "Экшн-RPG", "emoji": { "name": "⚔️" } } },
      { "poll_media": { "text": "Хоррор", "emoji": { "name": "👻" } } },
      { "poll_media": { "text": "Инди-платформер", "emoji": { "name": "🎮" } } },
      { "poll_media": { "text": "Выживание и крафт", "emoji": { "name": "🪓" } } }
    ],
    "duration": 72,
    "allow_multiselect": false,
    "layout_type": 1
  }
}

Для кастомного эмодзи сервера замените "name" на "id" и укажите snowflake-идентификатор эмодзи:

{ "poll_media": { "text": "Свой вариант", "emoji": { "id": "1234567890123456789" } } }

Опрос с множественным выбором

Когда нужно узнать всё, что подходит участнику, установите allow_multiselect в true:

{
  "poll": {
    "question": { "text": "Какими функциями вы пользуетесь чаще всего?" },
    "answers": [
      { "poll_media": { "text": "Вебхуки", "emoji": { "name": "🔗" } } },
      { "poll_media": { "text": "Эмбеды", "emoji": { "name": "📋" } } },
      { "poll_media": { "text": "Слэш-команды", "emoji": { "name": "⚡" } } },
      { "poll_media": { "text": "Треды", "emoji": { "name": "🧵" } } },
      { "poll_media": { "text": "Форумы", "emoji": { "name": "💬" } } }
    ],
    "duration": 168,
    "allow_multiselect": true,
    "layout_type": 1
  }
}

Отправка опроса через curl

Замените YOUR_WEBHOOK_URL на реальный URL вебхука из настроек сервера Discord:

curl -X POST "YOUR_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{
    "poll": {
      "question": { "text": "Табы или пробелы?" },
      "answers": [
        { "poll_media": { "text": "Табы", "emoji": { "name": "📑" } } },
        { "poll_media": { "text": "Пробелы", "emoji": { "name": "␣" } } }
      ],
      "duration": 24,
      "allow_multiselect": false,
      "layout_type": 1
    }
  }'

Отправка опроса через JavaScript

Работает в Node.js и в любом современном браузерном окружении с поддержкой fetch:

const WEBHOOK_URL = "YOUR_WEBHOOK_URL";

const poll = {
  poll: {
    question: { text: "В каком часовом поясе большинство из вас?" },
    answers: [
      { poll_media: { text: "Америка (UTC-8 до UTC-4)", emoji: { name: "🌎" } } },
      { poll_media: { text: "Европа / Африка (UTC-1 до UTC+3)", emoji: { name: "🌍" } } },
      { poll_media: { text: "Азия / Тихоокеанский (UTC+5 до UTC+12)", emoji: { name: "🌏" } } },
    ],
    duration: 48,
    allow_multiselect: false,
    layout_type: 1,
  },
};

async function sendPoll() {
  const response = await fetch(WEBHOOK_URL, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(poll),
  });

  if (!response.ok) {
    const error = await response.json();
    console.error("Ошибка при отправке опроса:", error);
    return;
  }

  console.log("Опрос успешно отправлен!");
}

sendPoll();

Если вы работаете с вебхуками на JavaScript в целом, руководство по вебхукам на JavaScript подробно разбирает паттерны fetch, обработку ошибок и ограничения по частоте запросов.

Опрос вместе с текстом сообщения

Payload вебхука может содержать опрос вместе с обычным сообщением. Добавьте поле content — текст появится над карточкой опроса:

{
  "content": "Эй, @everyone, быстрое голосование перед тем, как утвердим расписание:",
  "poll": {
    "question": { "text": "Перенести еженедельную встречу на четверг?" },
    "answers": [
      { "poll_media": { "text": "Да, четверг лучше", "emoji": { "name": "✅" } } },
      { "poll_media": { "text": "Нет, оставить как есть", "emoji": { "name": "❌" } } },
      { "poll_media": { "text": "Мне всё равно", "emoji": { "name": "🤷" } } }
    ],
    "duration": 24,
    "allow_multiselect": false,
    "layout_type": 1
  }
}

Совмещать опрос с эмбедом в одном сообщении нельзя. Discord не позволяет использовать poll и embeds в одном payload вебхука.

Частые ошибки

Недопустимое значение duration. Значение 0 или больше 720 вернёт ошибку 400. Допустимый диапазон — от 1 до 720 часов.

Слишком много вариантов. API отклоняет payload с более чем 10 ответами. Проверяйте количество вариантов перед отправкой.

Отсутствует layout_type. Это поле обязательно. Его отсутствие вызывает ошибку валидации, даже несмотря на то что допустимое значение сейчас только одно.

Markdown в тексте вопроса. Discord не рендерит markdown внутри вопроса опроса. Жирный текст, курсив и ссылки там не работают.

Визуальный конструктор опросов

Писать JSON вручную удобно для разовых задач, но быстро надоедает. Конструктор опросов на discord-webhook.com/app позволяет настроить каждое поле через визуальный интерфейс, предварительно просмотреть опрос и скопировать готовый payload или отправить его напрямую.

Инструмент охватывает весь объект poll: вопрос, варианты ответа с выбором эмодзи, слайдер продолжительности, переключатель множественного выбора и тип разметки. Редактировать JSON не нужно.

Запланированные опросы

Опросы можно не только отправлять сразу, но и планировать на определённое время. Например, запустить голосование в начале рабочего дня или перед еженедельной встречей команды. Для этого воспользуйтесь функцией отложенных сообщений — создайте опрос в конструкторе, выберите дату и время, и сервер отправит его автоматически.

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

Связанные руководства

Только начинаете работать с вебхуками? Руководство по настройке Discord Webhook объясняет, как создать URL вебхука, настроить права доступа и отправить первое сообщение.

Для более богатых сообщений рядом с опросами руководство по Discord Embed Builder показывает, как собирать эмбеды с заголовками, полями, цветами и подвалами.

Если вы автоматизируете вызовы вебхуков из Node.js-проекта, руководство по JavaScript содержит всё необходимое для production-кода.

Хотите добавить к сообщению с опросом интерактивные кнопки? Ознакомьтесь с руководством по кнопкам и действиям. А для отправки опроса в тред или на форум — с руководством по тредам и форумам.

---

Опросы через Discord Webhook — одна из самых понятных частей API, как только разберёшься со структурой объекта. Главное запомнить: duration задаётся в часах (от 1 до 720), каждый вариант ответа оборачивается в poll_media, а layout_type всегда равен 1. Остальное — просто заполнение полей.