server/docs/polls.md

Poll Feature Implementation

This document describes the poll feature implementation for posting notes with polls.

API Usage

Creating a Note with a Poll

To create a note with a poll, include the following parameters in your POST request to /api/v1/statuses:

{
  "status": "Which do you prefer?",
  "poll[options]": ["Option 1", "Option 2", "Option 3"],
  "poll[expires_in]": 3600,
  "poll[multiple]": false,
  "poll[hide_totals]": false
}

Parameters

• poll[options]: Array of poll option strings (2-20 options, max 500 chars each)
• poll[expires_in]: Duration in seconds (60 seconds to 100 days)
• poll[multiple]: Boolean, allow multiple choice selection (optional, default: false)
• poll[hide_totals]: Boolean, hide vote counts until poll ends (optional, default: false)

Constraints

• Polls cannot be attached to posts with media attachments
• Minimum 2 options required
• Maximum options and duration are configurable in server settings

API Response

When fetching a note with a poll, the response includes:

{
  "id": "note-id",
  "content": "Which do you prefer?",
  "poll": {
    "id": "poll-id",
    "expires_at": "2025-01-07T14:11:00.000Z",
    "expired": false,
    "multiple": false,
    "votes_count": 6,
    "voters_count": 3,
    "options": [
      {
        "title": "Option 1",
        "votes_count": 4
      },
      {
        "title": "Option 2", 
        "votes_count": 2
      }
    ],
    "emojis": [],
    "voted": true,
    "own_votes": [0]
  }
}

Database Schema

The implementation adds three new tables:

Polls

• id: Primary key
• noteId: Foreign key to Notes table (unique)
• expiresAt: Poll expiration timestamp (nullable)
• multiple: Allow multiple choice
• hideTotals: Hide vote counts until expired
• votesCount: Total vote count
• votersCount: Unique voter count

PollOptions

• id: Primary key
• pollId: Foreign key to Polls table
• title: Option text
• index: Option position (0-based)
• votesCount: Votes for this option

PollVotes

• id: Primary key
• pollId: Foreign key to Polls table
• optionId: Foreign key to PollOptions table
• userId: Foreign key to Users table
• Unique constraint on (pollId, userId, optionId)

Implementation Details

• Polls are created atomically with the note in a database transaction
• Poll data is included in note queries via relations
• Expiration is checked dynamically when converting to API format
• Vote totals can be hidden until poll expires based on hideTotals setting
• User vote status and choices are included when user context is available