This package creates a docker container that runs a GroupMe, Discord, or Slack chat bot to send ESPN Fantasy Football information to a GroupMe, Discord or Slack chat room.
What does this do?
- Sends out the following messages on this schedule:
- Close Scores - Mon - 18:30 east coast time (Games that are within 16 points of eachother to keep an eye on during the Monday night game)
- Scoreboard - Mon,Tue,Fri - 7:30 local time (Current ESPN fantasy scoreboard)
- Trophies- Tue - 7:30 local time (High score, low score, biggest win, closest win)
- Power rankings - Tue -18:30 local time
- Matchups - Thu - 19:30 east coast time (Upcoming matchups)
- Scoreboard - Sun - 16:00, 20:00 east coast time (Current ESPN fantasy scoreboard)
These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.
With Docker:
git clone https://github.com/dtcarls/ff_bot
cd ff_bot
docker build -t ff_bot .Without Docker:
git clone https://github.com/dtcarls/ff_bot
cd ff_bot
python3 setup.py installThis gives an overview of all the features of ff_bot
- BOT_ID: This is your Bot ID from the GroupMe developers page (REQUIRED IF USING GROUPME)
- SLACK_WEBHOOK_URL: This is your Webhook URL from the Slack App page (REQUIRED IF USING SLACK)
- DISCORD_WEBHOOK_URL: This is your Webhook URL from the Discord Settings page (REQUIRED IF USING DISCORD)
- LEAGUE_ID: This is your ESPN league id (REQUIRED)
- START_DATE: This is when the bot will start paying attention and sending messages to your chat. (2019-09-04 by default)
- END_DATE: This is when the bot will stop paying attention and stop sending messages to your chat. (2019-12-30 by default)
- LEAGUE_YEAR: ESPN League year to look at (2019 by default)
- TIMEZONE: The timezone that the messages will look to send in. (America/New_York by default)
- INIT_MSG: The message that the bot will say when it is started (“Hi” by default, can be blank for no message)
- ESPN_S2: Used for private leagues. See Private Leagues Section for documentation
- SWID: Used for private leagues. See Private Leagues Section for documentation
Use BOT_ID if using Groupme, DISCORD_WEBHOOK_URL if using Discord, and SLACK_WEBHOOK_URL if using Slack (or multiple to get messages in multiple places)
>>> export BOT_ID=[enter your GroupMe Bot ID]
>>> export WEBHOOK_URL=[enter your Webhook URL]
>>> export LEAGUE_ID=[enter ESPN league ID]
>>> export LEAGUE_YEAR=[enter league year]
>>> cd ff_bot
>>> docker run --rm=True \
-e BOT_ID=$BOT_ID \
-e LEAGUE_ID=$LEAGUE_ID \
-e LEAGUE_YEAR=$LEAGUE_YEAR \
ff_botUse BOT_ID if using Groupme, DISCORD_WEBHOOK_URL if using Discord, and SLACK_WEBHOOK_URL if using Slack (or multiple to get messages in multiple places)
>>> export BOT_ID=[enter your GroupMe Bot ID]
>>> export WEBHOOK_URL=[enter your Webhook URL]
>>> export LEAGUE_ID=[enter ESPN league ID]
>>> export LEAGUE_YEAR=[enter league year]
>>> cd ff_bot
>>> python3 ff_bot/ff_bot.pyAutomated tests for this package are included in the tests directory. After installation,
you can run these tests by changing the directory to the ff_bot directory and running the following:
python3 setup.py testDo not deploy 2 of the same bot in the same chat. In general, you should let your commissioner do the setup
Go to www.groupme.com and sign up or login
If you don't have one for your league already, create a new "Group Chat"
Next we will setup the bot for GroupMe
Go to https://dev.groupme.com/session/new and login
Click "Create Bot"
Create your bot. GroupMe does a good job explaining what each thing is.
After you have created your bot you will see something similar to this. Click "Edit"
This page is important as you will need the "Bot ID" on this page.You can also send a test message with the text box to be sure it is connected to your chat room. Side note: If you use the bot id depicted in the page you will spam an empty chat room so not worth the effort
Go to https://slack.com/signin and sign in to the workspace the bot will be in
If you don't have one for your league already, create a new League Channel
Next we will setup the bot for Slack
Go to https://api.slack.com/apps/new
Name the app, and choose the intended workspace from the dropdown.
Select the Incoming Webhooks section on the side.
Change the toggle from Off to On.
Select Add New Webhook to Workspace
In the Post to dropdown, select the channel you want to send messages to, then select Authorize.
This page is important as you will need the "Webhook URL" on this page.
Log into or create a discord account
Go to or create a discord server to receive messages in
Open the server settings
Go to Webhooks
Create a webhook, give it a name and pick which channel to receive messages in
Save the "Webhook URL" on this page
Heroku is what we will be using to host the chat bot (for free)
You should not need to enter credit card information for this hosting service for our needs. You may run out of free hours without a credit card linked. If you decide to link your credit card you will have enough free hours for the month for a single application since this more than doubles your available hours. We are not responsible for any charges associated with Heroku.
Go to https://id.heroku.com/login and sign up or login
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
Click this handy button:
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
Go to your dashboard (https://dashboard.heroku.com/apps) Now you will need to setup your environment variables so that it works for your league. Click Settings at your dashboard. Then click "Reveal Config Vars" button and you will see something like this.
Now we will need to edit these variables (click the pencil to the right of the variable to modify) Note: App will restart when you change any variable so your chat room may be semi-spammed with the init message of "Hi" you can change the INIT_MSG variable to be blank to have no init message. It should also be noted that Heroku seems to restart the app about once a day
- BOT_ID: This is your Bot ID from the GroupMe developers page (REQUIRED IF USING GROUPME)
- SLACK_WEBHOOK_URL: This is your Webhook URL from the Slack App page (REQUIRED IF USING SLACK)
- DISCORD_WEBHOOK_URL: This is your Webhook URL from the Discord Settings page (REQUIRED IF USING DISCORD)
- LEAGUE_ID: This is your ESPN league id (REQUIRED)
- START_DATE: This is when the bot will start paying attention and sending messages to your chat. (2019-09-04 by default)
- END_DATE: This is when the bot will stop paying attention and stop sending messages to your chat. (2019-12-30 by default)
- LEAGUE_YEAR: ESPN League year to look at (2019 by default)
- TIMEZONE: The timezone that the messages will look to send in. (America/New_York by default)
- INIT_MSG: The message that the bot will say when it is started (“Hi” by default, can be blank for no message)
- ESPN_S2: Used for private leagues. See Private Leagues Section for documentation
- SWID: Used for private leagues. See Private Leagues Section for documentation
After you have setup your variables you will need to turn it on. Navigate to the "Resources" tab of your Heroku app Dashboard.
You should see something like below. Click the pencil on the right and toggle the buton so it is blue like depicted and click "Confirm."
You're done! You now have a fully featured GroupMe/Slack/Discord chat bot for ESPN leagues! If you have an INIT_MSG you will see it exclaimed in your GroupMe, Discord, or Slack chat room.
Unfortunately to do auto deploys of the latest version you need admin access to the repository on git. You can check for updates on the github page (https://github.com/dtcarls/ff_bot/commits/master) and click the deploy button again; however, this will deploy a new instance and the variables will need to be edited again.
For private league you will need to get your swid and espn_s2.
You can find these two values after logging into your espn fantasy football account on espn's website.
(Chrome Browser)
Right click anywhere on the website and click inspect option.
From there click Application on the top bar.
On the left under Storage section click Cookies then http://fantasy.espn.com.
From there you should be able to find your swid and espn_s2 variables and values.
League must be full.
The bot isn't working
Did you miss a step in the instructions? Try doing it from scratch again. If still no luck, post here so the answer can be shared with others.
How are power ranks calculated?
They are calculated using 2 step dominance, as well as a combination of points scored and margin of victory. Weighted 80/15/5 respectively. I wouldn't so much pay attention to the actual number but more of the gap between teams. Full source of the calculations can be seen here: https://github.com/cwendt94/ff-espn-api/commit/61f8a34de5c42196ba0b1552aa25282297f070c5
Is there a version of this for Yahoo/CBS/NFL/[insert other site]?
No, this would require a significant rework for other sites.
I'm not getting the init message
Are you sure you flipped the switch in Heroku to activate the worker (the toggle should be blue)? The other common mistake is misconfigured environment variables.
I keep getting the init message
Remove your init message and it will stop. The init message is really for first setup to ensure it is working.
How do I set another timezone?
Specify your variable https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List
Is there a version of this for Messenger/WhatsApp/[insert other chat]?
No, but I am open to pull requests implementing their API for additional cross platform support.
- BTC: 3C8SEcDh52iDSYQY55kwELrNWoQRMkXLCR
- ETH: 0xA098c4e8CC1c12422d5B34d6454133190CDdCAC3
- LTC: MHx74YbrHE592ePBbdQ4cL9ZQC15xaAjtM