Discord Webhook Polls: A Complete Guide to the Poll API

Discord added native polls to its platform, and you can send them directly through webhooks. No bot required, no OAuth flow, no library dependency. Just a webhook URL and a JSON payload. This guide walks through everything you need to know about the discord webhook poll API, from the object structure to working code examples.

What Is a Discord Webhook Poll?

A Discord poll is an interactive message that lets server members vote on a question. When you send a poll through a webhook, Discord renders it as a native poll card with vote buttons, a progress bar, and an automatic expiry timer.

Polls sent via webhooks behave the same as polls created through the Discord client. Members click to vote, results update in real time, and the poll closes automatically when the duration expires.

The Poll Object Structure

Every discord poll api payload wraps a poll object inside your webhook body. Here’s what each field does:

{
  "poll": {
    "question": { "text": "What is your favorite?" },
    "answers": [
      { "poll_media": { "text": "Option A", "emoji": { "name": "🅰️" } } },
      { "poll_media": { "text": "Option B", "emoji": { "name": "🅱️" } } }
    ],
    "duration": 24,
    "allow_multiselect": false,
    "layout_type": 1
  }
}

question.text — The poll question. Plain text only, up to 300 characters. No markdown, no embeds.

answers — An array of answer objects. Each answer contains a poll_media object with:

• text — The answer label (up to 55 characters)
• emoji — Optional. An object with either name (for Unicode emoji) or id (for custom server emoji)

You can include 1 to 10 answers per poll.

duration — How long the poll stays open, in hours. Minimum is 1 hour, maximum is 720 hours (30 days). There’s no way to create a poll without an expiry.

allow_multiselect — Boolean. When true, members can vote for more than one answer. When false, each member gets exactly one vote.

layout_type — Currently only 1 is valid. Discord may add more layout types in the future, but for now always set this to 1.

Basic Poll Example

The simplest possible discord voting webhook payload. No emojis, single-select, closes in 24 hours:

{
  "poll": {
    "question": { "text": "Which day works best for the community event?" },
    "answers": [
      { "poll_media": { "text": "Saturday" } },
      { "poll_media": { "text": "Sunday" } },
      { "poll_media": { "text": "Either day works for me" } }
    ],
    "duration": 48,
    "allow_multiselect": false,
    "layout_type": 1
  }
}

Poll With Emojis

Emojis make polls more visually distinct and easier to scan. Use any standard Unicode emoji in the name field:

{
  "poll": {
    "question": { "text": "What should we stream next?" },
    "answers": [
      { "poll_media": { "text": "Action RPG", "emoji": { "name": "⚔️" } } },
      { "poll_media": { "text": "Horror", "emoji": { "name": "👻" } } },
      { "poll_media": { "text": "Indie Platformer", "emoji": { "name": "🎮" } } },
      { "poll_media": { "text": "Survival Crafting", "emoji": { "name": "🪓" } } }
    ],
    "duration": 72,
    "allow_multiselect": false,
    "layout_type": 1
  }
}

For custom server emoji, replace "name" with "id" and provide the emoji’s snowflake ID:

{ "poll_media": { "text": "Custom Option", "emoji": { "id": "1234567890123456789" } } }

Multiselect Poll Example

When you want members to pick everything that applies, set allow_multiselect to true:

{
  "poll": {
    "question": { "text": "Which features do you use most?" },
    "answers": [
      { "poll_media": { "text": "Webhooks", "emoji": { "name": "🔗" } } },
      { "poll_media": { "text": "Embeds", "emoji": { "name": "📋" } } },
      { "poll_media": { "text": "Slash Commands", "emoji": { "name": "⚡" } } },
      { "poll_media": { "text": "Threads", "emoji": { "name": "🧵" } } },
      { "poll_media": { "text": "Forums", "emoji": { "name": "💬" } } }
    ],
    "duration": 168,
    "allow_multiselect": true,
    "layout_type": 1
  }
}

Sending a Poll with curl

Replace YOUR_WEBHOOK_URL with your actual webhook URL from Discord’s server settings:

curl -X POST "YOUR_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{
    "poll": {
      "question": { "text": "Tabs or spaces?" },
      "answers": [
        { "poll_media": { "text": "Tabs", "emoji": { "name": "📑" } } },
        { "poll_media": { "text": "Spaces", "emoji": { "name": "␣" } } }
      ],
      "duration": 24,
      "allow_multiselect": false,
      "layout_type": 1
    }
  }'

Sending a Poll with JavaScript

This works in Node.js or any modern browser environment with fetch:

const WEBHOOK_URL = "YOUR_WEBHOOK_URL";

const poll = {
  poll: {
    question: { text: "What time zone are most of you in?" },
    answers: [
      { poll_media: { text: "Americas (UTC-8 to UTC-4)", emoji: { name: "🌎" } } },
      { poll_media: { text: "Europe / Africa (UTC-1 to UTC+3)", emoji: { name: "🌍" } } },
      { poll_media: { text: "Asia / Pacific (UTC+5 to 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("Failed to send poll:", error);
    return;
  }

  console.log("Poll sent successfully!");
}

sendPoll();

If you’re working with webhooks in JavaScript more broadly, the JavaScript webhook guide covers fetch patterns, error handling, and rate limits in detail.

Combining Polls With Other Content

A webhook payload can include a poll alongside a regular message. You can add content (plain text) to appear above the poll card:

{
  "content": "Hey @everyone, quick vote before we finalize the schedule:",
  "poll": {
    "question": { "text": "Should the weekly meetup move to Thursday?" },
    "answers": [
      { "poll_media": { "text": "Yes, Thursday is better", "emoji": { "name": "✅" } } },
      { "poll_media": { "text": "No, keep the current day", "emoji": { "name": "❌" } } },
      { "poll_media": { "text": "No preference", "emoji": { "name": "🤷" } } }
    ],
    "duration": 24,
    "allow_multiselect": false,
    "layout_type": 1
  }
}

You can’t combine a poll with an embed in the same message. Discord treats polls and embeds as mutually exclusive in a single webhook payload.

Common Mistakes

Duration out of range. Setting duration to 0 or anything above 720 will return a 400 error. Always stay between 1 and 720.

Too many answers. The API rejects payloads with more than 10 answers. Count your answers before sending.

Missing layout_type. This field is required. Omitting it causes a validation error even though there’s only one valid value right now.

Markdown in question text. Discord doesn’t render markdown inside poll questions. Bold, italics, and links won’t work there.

Build Polls Visually

Writing JSON by hand is fine for one-off polls, but it gets tedious fast. The discord-webhook.com/app Poll Builder lets you configure every field through a visual interface, preview the poll before sending, and copy the generated payload or send it directly.

It handles the full poll object: question, answers with emoji pickers, duration slider, multiselect toggle, and layout type. No JSON editing required.

You can also send polls to threads and forum posts by appending ?thread_id= to your webhook URL, keeping poll discussions organized within specific threads.

Want to launch a poll at a specific time? Use the scheduled messages feature on discord-webhook.com to queue your poll payload for a future date and time. Schedule a feedback poll to go live right when your event starts, or a weekly survey every Monday morning — without being at your computer.

Related Guides

Getting started with webhooks? The Discord webhook setup guide covers creating webhook URLs, permissions, and basic message sending from scratch.

For richer messages alongside your polls, the Discord embed builder guide explains how to construct embed objects with titles, fields, colors, and footers.

And if you’re automating webhook calls from a Node.js project, the JavaScript webhook guide has everything you need for production-ready code.

Looking to add interactive buttons alongside your polls? The interactive buttons and actions guide shows how to set up role assignments, forms, and action chains — no coding required.

For posting polls into threads or forum channels, see the thread and forum support guide.

---

Discord webhook polls are one of the more straightforward parts of the API once you understand the object structure. The main things to remember: duration is in hours (1-720), answers need poll_media wrappers, and layout_type must always be 1. Everything else is just filling in the fields.