@helyx/module-polls

Polls lets authorised members publish single-choice or multiple-choice polls to Discord while keeping individual ballots private and exposing only aggregate results on public poll cards.

Availability and deployment

Polls is Live and supports both Hosted Helyx and Helyx Self-Hosted. The package does not need third-party credentials. Installing the package does not enable it for a server; a server manager must enable Polls before its commands and behavioral work can run.

What it does

• Guides a member through a private, durable poll draft and an explicit preview before publication.
• Publishes 2 to 10 unique choices in a text or announcement channel.
• Supports one-choice and multiple-choice ballots, optional vote changes, optional voter-role restrictions, live or after-close results, and optional creator attribution.
• Closes timed or manual polls through fenced durable work and converges the public message on current stored state.
• Retains final aggregates separately from private ballot identities.

Polls does not reveal voter identities on public cards, edit a poll after publication, or delete the Discord message when a retained dashboard record is deleted.

Commands and interactions

• /poll create opens the private guided builder. It uses poll.create and defaults to members with Manage Messages.
• /poll close closes the creator's poll or a poll the member is authorised to manage. It uses poll.close.
• /poll results shows aggregate results when the poll's visibility rule permits it. It uses poll.results.
• /poll list lists up to 25 active polls in the server. It uses poll.list.

The published poll uses a select menu to record a ballot and a button to clear it when vote changes are allowed. Every executable command path has its own permission identity and uses enabled-server registration.

Casting or changing a ballot requires the open-by-default polls.vote operation plus the poll's snapshotted required-role rule. Clearing the acting member's own ballot remains available after eligibility is lost when that poll allows vote changes.

Dashboard configuration

Settings define defaults for voting mode, maximum selections, result visibility, vote changes, duration, an optional required voter role, and creator attribution. Published polls snapshot these values, so later setting changes do not reinterpret existing polls.

The Polls resource can list, search, filter, inspect, preview, create, close, and permanently delete eligible retained polls. Published polls cannot be edited. Aggregate access uses polls.read; the Voters relation uses the narrower polls.voters.read; dashboard creation and deletion use polls.create and polls.delete.

Discord requirements

Helyx needs View Channel, Send Messages, and Read Message History in the destination channel so it can publish and later update the poll. It does not request Administrator, Manage Messages, Manage Roles, Mention Everyone, or Message Content as bot capabilities.

The destination must remain a viewable text or announcement channel. An optional voter role must still belong to the same server when the poll is published.

Data, privacy and retention

Polls stores server, channel, message, creator and closer IDs; the question and ordered choice labels; snapshotted voting rules; lifecycle state; and current ballot selections by Discord voter ID. It does not store usernames, display names, avatars, email addresses, or device details. Current display names shown in the protected dashboard relation are resolved lazily and are not retained as poll records.

Privacy access and erasure remain registered even while Polls is disabled. Creator and closer attribution can be detached, a requester's ballot rows can be deleted, and potentially identifying question or choice text requires manual review. Anonymous final aggregates are preserved.

After closure, ballot identities are scheduled for deletion after 30 days and aggregate poll history after 180 days through the core retention lane. These deadlines do not depend on Polls remaining enabled.

Operations and failure behavior

PostgreSQL-backed module records are authoritative. Opening-form and draft transitions use the shared interaction-session service with version fencing, votes use atomic owned-set replacement, timed closure uses a one-shot task, and live rendering uses a coalesced lane. Replayed close and render deliveries converge from current stored state.

If Polls is disabled, due behavioural work is deferred without changing the poll. Missing public messages or unusable channels move affected polls to an orphaned final state with retained aggregates. Optional customer Logging and Achievement delivery cannot roll back a committed vote or closure. Health reports stopped, missing-dependency, and bounded degraded recovery states without exposing raw exceptions or poll content.

Operational limits:

• 25 active polls per server and 5 active polls per creator.
• 2 to 10 choices, with each label limited to 100 characters.
• Questions are 5 to 300 characters.
• /poll create starts at most 5 drafts per member per hour; publication is limited separately to 5 polls per member per hour.
• Voting is limited to 12 actions per member per minute. Results and list commands are limited to 6 uses per member per minute.
• Dashboard collection reads are bounded to 100 records per page; member-name resolution and aggregate loading are bounded and failure tolerant.

Compatibility: Polls uses manifest v0.4 and depends only on the declared compatible @helyx/module-manifest and @helyx/sdk ranges. It contains one contiguous foundation migration and uses platform-owned configuration, records, privacy, permissions, audit, logging, Discord inspection, interaction sessions, message rendering, and scheduled work.

Documentation and support

• Polls documentation
• Helyx module catalogue
• Report an issue