Watch History

Track what your Discord community watches together with server-wide watch history.

Overview

Watch History is a server-level feature that tracks movies, TV shows, and episodes your community watches together during watch parties. It creates a public record of shared viewing experiences.

Important: This is NOT personal ratings or private tracking. Watch history is:

• ✅ Public and visible to all server members
• ✅ Server-wide community feature
• ✅ Tracks watch parties and group viewings
• ✅ Shows channel and who saved it
• ❌ Not for personal ratings or reviews
• ❌ Not user-specific tracking
• ❌ Not private or ephemeral

How It Works

1. Start a Watch Party Timer

Use the timer command to begin:

/timer start label:The Lord of the Rings: The Fellowship of the Ring duration:190

Optional parameters:

• label - Name of what you're watching
• duration - Duration in minutes (1-600) for auto-stop
• theme - modern (default, colorful countdown) or classic (text-based)

Runtime Auto-Detection: When a timer auto-detects the title from a Discord scheduled event:

1. Bot searches TMDB for the title
2. Shows selection menu if multiple matches found
3. You select the correct movie/TV show
4. Bot fetches runtime and adds 10-minute buffer
5. Timer starts with auto-stop enabled

Examples:

/timer start label:Movie Night duration:120
/timer start label:Jaws theme:classic
/timer start duration:45
/timer start

Without duration: Timer runs continuously until manually stopped.

2. Watch Together

Everyone in the channel watches together. The timer displays elapsed time.

3. Stop the Timer

When viewing ends, stop the timer:

/timer stop

NEW: The timer automatically logs to watch history!

4. Automatic Logging (Timers with Labels)

When the timer completes (manual stop or auto-stop), if a label was provided:

1. Bot searches TMDB for the title
2. Finds best match (uses first result)
3. Automatically saves to watch history
4. Shows confirmation with full details
5. "Log to Watch History" button appears for manual override

Information Saved:

• Movie/TV show title from TMDB
• Year and type (movie/TV)
• Date watched
• Timer duration as notes
• Channel where watched
• Who started/stopped the timer
• Poster image

Manual Override Button:

• Appears on ALL timer completions
• Lets timer starter/mods/admins manually log or correct
• For timers WITHOUT labels: enter title after the fact
• For timers WITH labels: override if wrong title detected

Button Permissions:

• ✅ Timer starter
• ✅ Server administrators
• ✅ Server moderators
• ❌ Other users (shows permission error)

5. Public Record

The entry appears publicly in the channel for everyone to see:

⏹️ Timer Stopped & Logged 🛑📝

The Lord of the Rings: The Fellowship of the Ring (2001)

✅ Automatically logged to watch history

Total Time: 3:02:15
Type: Movie
Channel: #movie-night
Started by: MovieFan
Stopped by: MovieFan

Use /watched history to view watch history • Use /timer start to begin a new timer

Permission System

Who Can Save to History?

After Timer Completion:

• ✅ User who started the timer (automatically authorized)
• ✅ Server Administrators
• ✅ Users with Manage Guild permission
• ✅ Users with Moderate Members permission

Manual Entry: Anyone can add entries manually using /watched add, subject to rate limiting.

Why This Restriction?

• Prevents random users from polluting server history
• Timer starter knows what was actually watched
• Moderators can verify and save legitimate entries
• Maintains history accuracy

Who Can Remove History?

Only Administrators can remove watch history entries:

/watched remove <id>

This restriction prevents:

• Casual deletion of server records
• Loss of community history
• Disputes about what was watched

Commands

View Watch History

/watched list [limit]

Shows recent watch history:

• Last 10 entries (default)
• Up to 50 entries with limit parameter
• Titles with TMDB links and ratings
• Dates and channels
• Who saved each entry
• Notes from viewers

Example:

/watched list 25

Shows last 25 entries.

Manual Entry

/watched add type:<movie|tv> title:<text> notes:<text>

Add to watch history without using a timer:

Parameters:

• type - "movie" or "tv"
• title - Title to search for
• notes - Optional notes about the viewing (optional)

Use Cases:

• Retroactive logging of past watch parties
• Manual entry when timer wasn't used
• Adding rewatches or favorites

Example:

/watched add type:movie title:Big Trouble in Little China notes:First watch for half the group!

Remove Entry

/watched remove id:<number>

Administrator only - Remove an entry from watch history.

Get the ID from /watched list, then:

/watched remove id:42

⚠️ Cannot be undone!

Check Timer Status

/timer status

See how long the current timer has been running and who started it.

Use Cases

Regular Watch Parties

Track your weekly or monthly watch parties:

1. Start timer: /timer start label:Movie Night - The Matrix
2. Watch together (timer runs)
3. Stop timer: /timer stop
4. Click "Log to Watch History" button
5. Add notes about reactions and highlights

Review history before next party to avoid repeats:

/watched list

Movie Marathons

Keep a record of marathon viewings:

Day 1: /timer start label:LotR: Fellowship
       → Watch, stop, save with notes
       
Day 2: /timer start label:LotR: Two Towers  
       → Watch, stop, save with notes
       
Day 3: /timer start label:LotR: Return of the King
       → Watch, stop, save with notes

All saved to history with marathon context

TV Show Tracking

Track episode-by-episode progress:

/watched add type:tv title:Breaking Bad S01E01 notes:Pilot episode - hooked!
/watched add type:tv title:Breaking Bad S01E02 notes:Still excellent

Or use timers for each episode viewing.

Community Recommendations

See what the community has watched and enjoyed:

/watched list

Browse recent watches, read notes from other viewers, and discover new content.

Timer Auto-Detection

For advanced setups, configure watch party channels for automatic label detection from Discord events:

/eggshen-config watch-party add channel:#movie-night

When you start a timer in a configured channel with an active Discord event, the bot automatically uses the event name as the timer label.

See the Configuration Guide for details.

Avoiding Repeats

Check history before suggesting:

/watched list 50
→ Search for title
→ See if watched recently
→ Choose something new

Data Tracked

Each watch history entry includes:

Field	Description	Example
Title	Movie/TV show name	"The Matrix"
TMDB ID	Database identifier	603
Type	Content type	"movie" or "tv"
Date	When watched	"2026-06-21"
Channel ID	Discord channel ID	123456789
Channel Name	Channel display name	"movie-night"
Saved By ID	User who saved it	987654321
Saved By	Username	"MovieFan"
Notes	Optional comments	"Great special effects!"

Watch History vs Personal Tracking

Watch History (This Bot):

• Server-level tracking
• Public records
• Group viewing focus
• Channel-specific
• Community feature
• No ratings or reviews

Personal Tracking (Use External Services):

• Trakt.tv - Watch tracking and ratings
• Letterboxd - Movie diary and reviews
• TV Time - TV show tracking
• Simkl - Movies and TV tracking

Integration with Timer

Watch history is deeply integrated with the timer system:

Timer Flow

1. /timer start → Creates countdown
2. Timer runs → Community watches
3. Timer ends → "Log to Watch History" button appears
4. Button click → Opens save modal
5. Submit → Saves to history publicly
6. Public message → Everyone sees the entry

Button Behavior

Who sees the button: Everyone can see it

Who can click it:

• Timer starter
• Administrators
• Users with Manage Guild permission
• Users with Moderate Members permission

Others: See permission error if clicked

Modal Fields

When saving from timer:

• Title - Pre-filled from timer description
• Notes - Optional field for comments

All other data (channel, date, user) automatically captured.

Statistics Integration

Watch history contributes to server statistics:

• Total watches tracked
• Most watched titles
• Active watch party channels
• Most active watch party organizers
• Watch frequency trends

See Statistics for more details.

Best Practices

For Server Admins

1. Set Clear Expectations

   • Explain watch history is public
   • Document who can save entries
   • Post guidelines in server rules

2. Moderate Appropriately

   • Review history periodically
   • Remove duplicate entries
   • Ensure accuracy

3. Encourage Usage

   • Promote watch parties
   • Show history in welcome message
   • Celebrate milestones (100 watches, etc.)

For Watch Party Hosts

1. Use Timers

   • Always start timer for watch parties
   • Set correct duration
   • Include title in description

2. Add Detailed Notes

   • Mention highlights
   • Note attendance/participation
   • Include memorable moments

3. Check History First

   • Avoid recent repeats
   • Find popular past choices
   • Discover community preferences

For Server Members

1. Respect the System

   • Don't spam manual entries
   • Keep notes appropriate
   • Report issues to moderators

2. Participate

   • Join watch parties
   • Read notes from past watches
   • Suggest new content based on history

3. Use External Services

   • Use Trakt/Letterboxd for personal tracking
   • Keep ratings separate
   • Don't treat history as personal diary

Privacy Considerations

Watch history is intentionally public for these reasons:

1. Community Feature

   • Shared experience tracking
   • Group accountability
   • Social discovery

2. Transparency

   • Everyone sees same information
   • No hidden data
   • Clear attribution

3. Server Context

   • Channel-specific tracking
   • Server member visibility only
   • Not published outside Discord

If users want private tracking, they should use external services.

Troubleshooting

Can't save to watch history

Check:

• Did you start the timer?
• Do you have moderator permissions?
• Has timer actually completed?
• Is watch history enabled for server?

Solution:

• Wait for timer to complete
• Ask a moderator to save
• Check server configuration

Entry not appearing

Check:

• Was save confirmed?
• Is there an error message?
• Check mod logs for errors

Solution:

• Try manual entry with /watched add
• Check bot has database access
• Contact server administrator

Wrong information saved

Solution:

• Administrator can remove entry: /watched remove <id>
• Re-add with correct information
• Add note explaining correction

History showing 404 error

Issue: History list page not rendering

Solution:

• Use /watched list command instead
• Check bot permissions
• Verify database connection

Future Enhancements

Potential future features:

• Export watch history to CSV
• Statistics dashboard per user
• Integration with external services (Trakt, Letterboxd)
• Automatic show progress tracking
• Watch party scheduling
• Recommendation engine based on history

Submit feature requests on GitHub Issues!