Added polls module documentation.

2026-04-08 12:01:52 -04:00
parent 2258c917c8
commit 8ee1356eb3
4 changed files with 146 additions and 0 deletions
@@ -35,6 +35,17 @@ For more information, see [Clips](Clips).

 For more information, see [Custom Commands](Custom-Commands).

+## Polls
+
+| Command | Aliases | Description |
+|---------|---------|-------------|
+| `!poll` | | Start the poll creation process. Sends a private link to the creation form. |
+| `!vote` | | Vote in the active poll. With a number, votes directly (single-select only). Without arguments, sends a voting page link. |
+| `!endpoll` | | End the active poll early and announce results. |
+| `!cancelpoll` | | Cancel the active poll without saving results. |
+
+For more information, see [Polls](Polls).
+
 ## Quotes

 | Command | Aliases | Description |
@@ -7,6 +7,7 @@ Owlbot is a modular, event-driven toolkit for extending [Owncast](https://owncas
 - **[Clips](Clips)**: Capture and save moments from the live stream. Viewers clip directly from chat and trim their footage in a browser-based editor, no extra software needed.
 - **[Custom commands](Custom-Commands)**: Moderators can create, edit, and delete chat commands at runtime without code changes or restarts. Responses support dynamic placeholders like `$(user)`, `$(count)`, `$(rand)`, `$(countdown)`, and positional arguments.
 - **[Emoji Wall](Emoji-Wall)**: Display floating emojis and custom emotes from chat as animated particles in an OBS browser source overlay.
+- **[Polls](Polls)**: Run interactive polls in chat with live results. Moderators create polls through a web form, viewers vote by number in chat or on a voting page, and results update in real time.
 - **[Quotes](Quotes)**: Codify the streamer's hot takes, wild claims, and memorable one-liners said live on air. Moderators add quotes, and anyone can recall them at random or look up a specific quote by ID.
 - **[Timers](Timers)**: Set up recurring chat messages that fire on a simple duration or cron schedule. An optional minimum chat line threshold keeps timers from firing into an empty chat.

@@ -0,0 +1,133 @@
+# Polls
+
+The `polls` module lets moderators create interactive polls that viewers can vote on through chat commands or a web interface. Results update in real time and are available for one hour after the poll ends.
+
+This is a built-in module that ships with Owlbot and is enabled by default.
+
+## Quick Start
+
+Start a poll:
+
+```
+!poll
+```
+
+Owlbot sends you a private link to a poll creation form. Fill in the question, options, duration, and settings, then submit. Owlbot announces the poll in chat:
+
+```
+Poll: "What game should we play next?"
+1. Minecraft
+2. Terraria
+3. Stardew Valley
+Type a number in chat or use !vote to vote. Voting ends in 4 minutes.
+```
+
+Vote by typing a number in chat or visiting the voting page:
+
+```
+3
+!vote
+```
+
+When the timer expires (or you type `!endpoll`), the winner is announced and a results link is shared.
+
+## Commands
+
+| Command | Aliases | Usage | Permission | Description |
+|---------|---------|-------|------------|-------------|
+| `!poll` | | `!poll` | Moderator | Start the poll creation process. Sends a private link to the creation form. |
+| `!vote` | | `!vote [number]` | Everyone | Vote in the active poll. With a number, votes directly (single-select only). Without arguments, sends a voting page link. |
+| `!endpoll` | | `!endpoll` | Moderator | End the active poll early and announce results. |
+| `!cancelpoll` | | `!cancelpoll` | Moderator | Cancel the active poll without saving results. |
+
+## Creating a Poll
+
+Type `!poll` to receive a private message with a link to the poll creation form. The link expires after 15 minutes if not used. The form has the following fields:
+
+- **Question** - the poll question (required)
+- **Options** - between 2 and 10 answer options
+- **Duration** - how long the poll runs in seconds (default: 240, between 30 and 600 seconds)
+- **Hide results until end** - when enabled, voters cannot see vote counts during the poll. You can always see live results as a moderator.
+- **Require authentication** - when enabled, only users logged into Owncast can vote
+- **Allow multiple selections** - when enabled, voters can select more than one option. Optionally set a minimum and maximum number of selections.
+
+Once submitted, the poll is announced in chat with numbered options.
+
+## Voting
+
+### In Chat
+
+For single-select polls, you can vote by typing a bare number in chat (e.g. `3`) or by using `!vote <number>`. Both methods hide the message from chat to keep votes private and prevent spam. Owlbot sends a private confirmation with a link to view live results.
+
+For multi-select polls, bare number voting and `!vote <number>` are not available. Type `!vote` to get a link to the voting page instead.
+
+### On the Web
+
+`!vote` (with no argument) sends a private link to the voting page. The page shows:
+
+- The question and options with radio buttons (single-select) or checkboxes (multi-select)
+- A countdown timer synced with the server
+- Live vote counts and percentages (unless the poll is hidden)
+- Moderators always see live results regardless of the hidden setting
+
+You can only vote once. Votes cannot be changed after submission.
+
+## Ending a Poll
+
+A poll ends in one of three ways:
+
+1. **Timer expires** - the poll automatically ends after its configured duration
+2. **`!endpoll`** - end the poll early from chat
+3. **End Poll button** - click "End Poll" on the voting page
+
+When a poll ends, the winner is announced in chat and a results link is shared. All connected voting pages redirect to the results page.
+
+## Cancelling a Poll
+
+`!cancelpoll` or the "Cancel Poll" button on the voting page discards the poll without saving results or announcing a winner. A cancellation message is posted to chat.
+
+## Notifications
+
+### 60-Second Reminder
+
+For polls longer than 60 seconds, Owlbot sends a reminder to chat when 60 seconds remain. The reminder repeats the question and voting instructions.
+
+### User Join Notification
+
+When you join chat while a poll is active, you receive a private message with the poll question, options, and instructions on how to vote.
+
+### Stream Grace Period
+
+If the stream goes offline during an active poll, the poll continues for a 5-minute grace period. If the stream does not come back online within that window, the active poll is automatically cancelled. If the stream restarts before the grace period expires, the poll continues normally.
+
+## Results
+
+The most recently completed poll is accessible at `/owlbot/polls/results` for one hour after it ends. The results page shows:
+
+- The question
+- Each option with its vote count, percentage, and a visual bar
+- Winner or tie badges
+
+Options are sorted by vote count (highest first). Ties are indicated when two or more options share the highest vote count.
+
+## Examples
+
+```
+# Start the poll creation flow (moderator only)
+!poll
+
+# Vote by typing a bare number in chat (single-select only)
+3
+
+# Vote using the command (single-select only)
+!vote 2
+
+# Get a link to the voting page (works for all polls)
+!vote
+
+# End the poll early and announce results (moderator only)
+!endpoll
+
+# Cancel the poll without saving results (moderator only)
+!cancelpoll
+```
@@ -9,6 +9,7 @@
 * [Clips](Clips)
 * [Custom Commands](Custom-Commands)
 * [Emoji Wall](Emoji-Wall)
+* [Polls](Polls)
 * [Quotes](Quotes)
 * [Timers](Timers)