fantasy_football_chat_bot

Fantasy Football Chat Bot - ESPN → Discord, Slack, GroupMe

Automated league updates in your league’s chat: scoreboards, standings, Power Rankings, weekly trophies, waiver reports, matchup previews, and Players to Monitor - posted on a schedule so nobody has to open the ESPN app to start an argument.

There are two ways to run it. Pick the one that matches how much of your season you want to spend on maintenance.

Option 1: let us run it - GameDayBot.com

Same bot, none of the upkeep. No server, no config files, no season rollover, no cookie refreshes. Buy on the site and a setup wizard walks you through it - connecting your chat app and your league in a few clicks, instead of a tour of three developer portals. Prefer Discord? Add it from the App Directory and run /league_setup instead. Either way it’s ESPN and Sleeper leagues, on Discord, Slack and GroupMe. Posting to league chats since 2017.

👉 Start a free 7-day trial at GameDayBot.com 👈

The trial runs at the top tier, so you see everything before deciding. One per league. On Discord you can add it straight from the App Directory.

What self-hosting actually costs

Not money - time, and always at the worst moment. None of this is hard; it’s just never finished:

What you get, side by side

Everything this repo sends, the managed bot sends too. The difference is what’s on top - and how you drive it.

The same messages, either way

Only on GameDayBot.com

Subscribe annually on GameDayBot.com or monthly inside Discord. One subscription covers one league, it auto-renews, and nothing expires mid-season. Current plans and pricing are always on GameDayBot.com.

Option 2: run it yourself

Everything below is for that, starting at Self-hosting. It’s fully supported and always will be - the same GPL-3.0 code the bot has always been, and the managed service is built on it.

Table of Contents

• What it sends, and when
• What the messages look like
• Self-hosting
  • What you need
  • 1. Set up your chat app
  • 2. Get your ESPN league info
  • 3. Configure
  • 4. Run it
  • Every season: the rollover checklist
  • Running functions on demand
• Development
• FAQ
• Support
• Donations
• License

What it sends, and when

Times marked local use your TIMEZONE setting. Times marked ET are always Eastern, because they’re pinned to kickoff windows. Nothing sends outside START_DATE to END_DATE, and the bot goes quiet once the league’s matchup periods are over.

Optional: DAILY_WAIVER moves the Waiver Report to a daily send, and MONITOR_REPORT (on by default) controls the Sunday Players to Monitor message.

The managed schedule - including the daily Waiver Report and the Elite chart messages - is at gamedaybot.com/message-schedule.

What the messages look like

Same text goes to every chat app you’ve configured; only the wrapping differs (Discord turns the first line into an embed title, Slack wraps the message in a code block, GroupMe sends it as-is).

Trophies of the week:
👑 High score 👑
Dynasty Kings with 187.34 points
💩 Low score 💩
Punt Life with 72.18 points
😱 Blow out 😱
Dynasty Kings blew out Punt Life by 115.16 points
😅 Close win 😅
The Victors barely beat The Losers by 1.24 points
🍀 Lucky 🍀
Big Losers was 2-7 against the league, but still got the win
😡 Unlucky 😡
Almost There was 7-2 against the league, but still took an L
📈 Overachiever 📈
Dynasty Kings was 32.50 points over their projection
📉 Underachiever 📉
Punt Life was 28.75 points under their projection
🤖 Best Manager 🤖
The Victors scored 98.24% of their optimal score!
🤡 Worst Manager 🤡
Punt Life left 42.50 points on their bench. Only scoring 63.10% of their optimal score.

Score Update
DKNG 120.34 -  98.56 PNLF
GRDG 145.22 - 134.18 VCTS
ALMT  87.50 - 102.44 BGLS

Approximate Projected Scores
DKNG 118.90 - 101.22 PNLF
GRDG 139.75 - 128.60 VCTS
ALMT  94.10 -  99.80 BGLS

Current Standings
 1: (10-3 ) Dynasty Kings
 2: ( 9-4 ) Gridiron Gods
 3: ( 8-5 ) The Victors
 4: ( 7-6 ) Almost There
 5: ( 5-8 ) Big Losers
 6: ( 3-10) Punt Life

Power Rankings (Playoff %)
99.99[🟢12.5%] (87.5) - DKNG
85.25[🔻 8.2%] (62.5) - VCTS
78.10[🟢 1.4%] (50.0) - GRDG
65.40[🟢 5.1%] (37.5) - ALMT
52.80[🔻 3.8%] (25.0) - BGLS
41.20[🔻 6.2%] (12.5) - PNLF

Matchups
Dynasty Kings vs Punt Life
Gridiron Gods vs The Victors
Almost There vs Big Losers

DKNG (8-4) vs (5-7) PNLF
GRDG (7-5) vs (9-3) VCTS
ALMT (6-6) vs (4-8) BGLS

Starting Players to Monitor
Dynasty Kings:
QB Lamar Jackson - Questionable
WR Cooper Kupp - Out
TE Dalton Kincaid - BYE

Gridiron Gods:
K Justin Tucker - Projected 0
WR Puka Nacua - Not IR eligible

Waiver Report 2026-10-15:
Dynasty Kings
ADDED QB - Josh Allen ($85, won by $40)
DROPPED QB - Gardner Minshew

Gridiron Gods
ADDED RB - Gus Edwards ($12, Punt Life outbid by $1)
DROPPED WR - Kendall Hinton

Projected Close Scores
DKNG 142.50 - 138.25 PNLF
GRDG 115.88 - 118.44 VCTS

Self-hosting

Don’t run two copies of the bot in the same chat - you’ll double every message. In general, let the commissioner do the setup.

The next two steps - creating a webhook in each chat app, and pulling your league ID out of a URL - are the ones GameDayBot.com’s setup wizard does for you. If any of it stops being fun, it runs the same messages (plus Sleeper, slash commands, trades, @mentions and charts) with none of the upkeep.

What you need

• An ESPN fantasy football league - public, or private with cookies (see below). The league must be full for ESPN’s API to return usable data.
• A chat destination - a GroupMe bot ID, a Slack incoming webhook, and/or a Discord webhook. Set as many as you want; each configured platform gets every message.
• Somewhere to run it 24/7. The bot is a long-lived process with an internal cron scheduler - it has to stay running to send anything. A Raspberry Pi, a VPS, a home server, or any container host works.
• Docker, or Python 3.9+ if you’d rather run it directly. The image and CI both use 3.11, so that’s the best-tested version.

1. Set up your chat app

2. Get your ESPN league info

League ID - open your league on fantasy.espn.com and take the leagueId value out of the URL.

3. Configure

Everything is environment variables. Set at least one chat destination and LEAGUE_ID; the rest have defaults.

Two older variables, WAIVER_REPORT and TEST, are still read but no longer do anything - leave them unset. RANDOM_PHRASE and TOP_HALF_SCORING have been removed entirely; if either is still in your config, drop it.

4. Run it

git clone https://github.com/dtcarls/fantasy_football_chat_bot
cd fantasy_football_chat_bot
docker compose up -d

git clone https://github.com/dtcarls/fantasy_football_chat_bot
cd fantasy_football_chat_bot
docker build -t fantasy_football_chat_bot .

docker run -d --restart=always \
  -e LEAGUE_ID=1234567 \
  -e LEAGUE_YEAR=2026 \
  -e START_DATE=2026-09-10 \
  -e END_DATE=2027-01-10 \
  -e TIMEZONE=America/Chicago \
  -e DISCORD_WEBHOOK_URL="https://discord.com/api/webhooks/..." \
  fantasy_football_chat_bot

git clone https://github.com/dtcarls/fantasy_football_chat_bot
cd fantasy_football_chat_bot
pip install -r requirements.txt

export LEAGUE_ID=1234567
export LEAGUE_YEAR=2026
export DISCORD_WEBHOOK_URL="https://discord.com/api/webhooks/..."
python3 gamedaybot/espn/espn_bot.py

Verify it’s alive: set INIT_MSG to anything, start the bot, confirm the message lands in your chat, then unset it and restart.

Every season: the rollover checklist

Nothing here is automatic. Before Week 1:

1. Set LEAGUE_YEAR to the new season.
2. Set START_DATE and END_DATE to the new season’s window.
3. Refresh ESPN_S2 / SWID if you use a private league - the Chrome extension makes this a few seconds.
4. Pull the latest release - ESPN changes their API most years, and the fix usually lands in espn-api and gets picked up here.
5. Restart and confirm with an INIT_MSG.

If doing this every August is the part you’d rather skip, GameDayBot.com handles all five and the mid-season cookie expiry that isn’t on this list.

Running functions on demand

Every message type is a function name you can call directly - useful for testing without waiting until Tuesday:

python3 -c "from gamedaybot.espn.espn_bot import espn_bot; espn_bot('get_standings')"

Valid names: get_scoreboard_short, get_projected_scoreboard, get_matchups, get_monitor, get_close_scores, get_power_rankings, get_trophies, get_standings, get_final, get_waiver_report, win_matrix, trophy_recap, init.

win_matrix (how the standings would look if everyone played everyone) and trophy_recap (season-long trophy tally) aren’t on the schedule - they’re on-demand only, and they read best at the end of a season.

Development

git clone https://github.com/dtcarls/fantasy_football_chat_bot
cd fantasy_football_chat_bot

pip install -r requirements.txt
pip install -r requirements-test.txt

pytest                       # run the tests
pytest tests/test_utils.py   # run one file

Lint config is in setup.cfg (max line length 120). Note the pinned flake8==3.3.0 predates Python 3.11 and won’t start on it - install a current flake8 to lint.

tests/dry_run_all_functions.py prints every message against a real league - handy for eyeballing formatting changes before they hit a chat full of people.

Pull requests are welcome, especially fixes to ESPN parsing and support for additional chat platforms.

FAQ

The bot isn’t sending anything. Check, in order: the process is still running; today is between START_DATE and END_DATE; LEAGUE_YEAR is the current season; your league is full; the webhook still works (set INIT_MSG and restart). If you’re still stuck, open an issue or ask in the Discord so the answer helps the next person too.

The Waiver Report is always empty. It only reports transactions from that same day, so a quiet waiver wire produces no message at all - that’s normal, not a failure. It does not need ESPN_S2/SWID; it works on public leagues.

How are Power Rankings calculated? Two-step dominance, weighted 80% dominance / 15% average points scored / 5% average margin of victory. Watch the gaps between teams rather than the raw number. Algorithm source · dominance matrix explainer.

How do I change the timezone? Set TIMEZONE to a TZ identifier, e.g. America/Chicago. The Sunday scoreboards, Monday Close Scores and Thursday Matchups stay on Eastern - they’re tied to kickoff times, not to your league.

Is there a version for Yahoo / CBS / NFL.com? Not in this repo. GameDayBot.com supports Sleeper alongside ESPN.

Is there a version for Messenger / WhatsApp / Teams? No, but pull requests adding a chat platform are welcome - see gamedaybot/chat/ for how small a platform module is.

Can I run this for two leagues? Run a second instance with its own config. One process serves one league. On GameDayBot.com a second league is a second subscription in the same server, with no second anything to deploy.

What does the managed version do that this doesn’t? Sleeper leagues, Discord slash commands (this repo is a one-way webhook - it can’t be talked to), Trade Announcements, team @mentions, and the Elite analytics pack: trend charts, Bad Management, Fortune Index, a weekly Win Matrix and Trophy Case, and an AI weekly recap. The comparison above has the full split.

Support

• GitHub issues - bugs and feature requests
• Discord - troubleshooting and release notifications
• GameDayBot on the Discord App Directory - add the managed bot to a server
• [email protected] - managed subscriptions

Donations

If the bot made your league chat better, a coffee is always appreciated - or subscribe at GameDayBot.com and let someone else run the server.

• PayPal:
• Venmo: @dtcarls

Starring the repo helps too.

License

GPL-3.0.