Hockey Game Bot
The Hockey Game Bot is a Python application that leverages the NHL API and other hockey related statistics sites to send (near) real-time messages to social media platforms. The game bot allows fans of NHL teams to view the events & stats of a game all in one convenient place.
The game bot currently supports 3 social media platforms - Twitter, Discord & Slack. If you would like to add your own, feel free to submit your code via a Pull Request.
Game Bot Messages / Events
The messages are broken down into four sections for each part of a game day (and one extra section of the day after a game day). I am currently adding more events and features as they are requested or they are found to be useful in the context of following the game via social media. This list will be kept up to date as more types of messages and / or customizations to these are added.
Each message is linked to a sample tweet from the NJ Devils game bot Twitter account.
- Morning Gameday Image (w/ time, broadcast channel & hashtag)
- Season Series (w/ Points Leaders & TOI Leaders)
- This becomes last season series if this is the first meeting.
- Confirmed goalie for each team (with season & career stats).
- Confirmed lines for each team (with lineup change checks)
- If the lineup / lines for a game change, an updated message will be sent.
- Referees and Linesman
- Preferred team starters (~5 minutes before game time)
Live Game Messages
- Start of Period
- Penalties & Power Plays
- Team stats & NHL rank
- Strength Status (PP, PK, etc)
- Coming Soon: End of penalty detection
- Shots that hit the cross-bar or post
- Notification of 1-minute remaining per period
- Intermission Reports
End of Game Messages
- Final game report including next game, basic stats and scoring summary
- Three Stars
- Advanced Stats Charts (via Natural Stat Trick)
- Game Score charts for both teams (via Hockey Stat Cards)
Day After Game Messages
On the day after a game, the game bot will generate two charts that provide context to how the team is performing for the entire season and in their last 10 games compared to the league average. The chart includes the following categories -
- Team Point Percentage
- Expected Goals & Actual Goals
- Shooting Percentage & Save Percentage
- High Danger Shooting Percentage & Save Percentage
- PDO (SPSV% - the sum of a team's shooting percentage and its save percentage)
The game bot ideally runs on a server that is always on as it is built with that assumption in mind - this is because the game bot is set to start hours before the game and checks at defined intervals for updated information related to that day's game.
The stand-alone Python script can run on anything from a Raspberry Pi to an AWS EC2 instance, while the current Docker implementation can only run on x86_64 machines.
Coming Soon: Currently there is a Docker image that is built for x86_64 and I am currently working on building an image that supports Raspberry Pi ARMv7 / ARM64 machines.
Prerequisites and Installation
To start the installation process, perform the following steps in order -
Download the most current release from Github.
$ git clone email@example.com:mattdonders/nhl-twitter-bot.git
Change to the cloned directory, create a new virtual environment & activate it.
$ cd nhl-twitter-bot $ python3 -m venv .env $ source .env/bin/activate
Install the Python requirements packages via pip.
$ pip install -r requirements.txt
Social Media Setup
In order for the game bot to send messages to social media, you will need API or Developer keys for each service.
- If you are sending messages to Twitter, Create a new Twitter application by filling out the form on Twitter's website. Your account will be revied for developr access. Once completed, create a new application and request an Access Token once completed as 4 keys are needed for Twitter integration.
- If you are sending messages to Discord, create a new Discord Webhook by going to your Discord channel, choosing settings, webhooks and click the “Create Webhook” button.
Once you have the application's keys and /or webhook URLs, rename
config.yaml and fill in the proper credentials.
$ cp hockeygamebot/config/config-sample.yaml hockeygamebot/config/config.yaml
Social media services are enabled & disabled through this configuration file as well (by marking them as True / False). Access tokens and keys are secret and should not be shared or uploaded to Github for any reason.
There are two sets of Twitter credentials defined in the configuration file. The second set can be used to setup a debug / test account, but are not required and can be left blank.
This part of the config.yaml code is what you will edit to provide the API Keys / Tokens & Webhooks to the game bot process.
# Team Name used if no --team argument is passed into the game bot default: team_name: New Jersey Devils # Enabling / disabling of social media services socials: twitter: True discord: True slack: False # Twitter API Keys / Tokens # Only use debug if you have a secondary debug account twitter: prod: consumer_key: XXX consumer_secret: XXX access_token: XXX access_secret: XXX handle: XXX debug: consumer_key: XXX consumer_secret: XXX access_token: XXX access_secret: XXX handle: XXX # Discord Webhook URLs # Only use debug if you have a secondary debug server / channel discord: prod: webhook_url: https://discordapp.com/api/webhooks/XXX debug: webhook_url: https://discordapp.com/api/webhooks/XXX
The Github repository contains a shell script named
hockeygamebot.sh which will automatically start the Python script in the background and disown the process. When a Linux process is disowned, it means that you can disconnect from your Linux session (if running on a remote host) without stopping or interrupting the script process.
To start the bot using the script, run the
hockeygamebot.sh command (modify the location to your cloned folder) -
If you want to start the Python script from the command line and pass in debug arguments, you can execute the script directly. Some of these options are debug or testing options, but have not yet been cleaned up for this version of the script.
$ python -m hockeygamebot --help usage: hockeygamebot [-h] [--notweets] [--console] [--debug] [--team TEAM] [--debugtweets] [--debugsocial] [--localdata] [--overridelines] [--yesterday] [--date DATE] [--split] [--docker] [--discord] [--config CONFIG] [-v] optional arguments: -h, --help show this help message and exit --notweets log tweets to console instead of Twitter --console log to console instead of file --debug print debug log items --team TEAM override team in configuration --debugtweets send tweets from debug account --debugsocial use debug social accounts --localdata use local data instead of API --overridelines override lines if None are returned --yesterday get yesterday game on the schedule --date DATE override game date --split split squad game index --docker running in a docker container --discord Send messages to discord channel --config CONFIG Overrides the config.yaml with another filename. -v Increased verbosity.
Automating The Game Bot
If you want to run the game bot automatically every day, you can setup a cron job on Linux / Mac that restarts the bot everyday at any specified time (mine runs at 9:00AM so I can start checking other sites for game data as early as possible). You can edit your crontab file by executing the
crontab -e command and pasting in the below line (again modifying the path to your script path).
Crontab is also supported in the Windows Subsystem for Linux if the game bot is running within this type of environment.
A sample crontab entry -
0 9 * * * $HOME/python/nhl-twitter-bot/hockeygamebot.sh
Currently Operating Game Bots
As of March 15, 2020 there is currently game bot covereage for 12 of 31 teams. The table below contains information about the accounts, their respective owners and any notes. More than one person can run one for the same team without issue, but there will be overlap in the Twitter feed.
|Team Name||Twitter Account||Owner||Notes|
|Columbus Blue Jackets||@CBJGameBot||@mattdonders||Willing to reliquensh to a Blue Jackets fan.|
|Detroit Red Wings|
|Los Angeles Kings|
|New Jersey Devils||@NJDevilsGameBot||@mattdonders|
|New York Islanders|
|New York Rangers|
|Saint Louis Blues||@STLBluesGameBot||@mattdonders||Willing to reliquensh to a Blues fan.|
|San Jose Sharks||@Sharks_Gamebot||@projpatsummit|
|Tampa Bay Lighting|
|Toronto Maple Leafs||@MapleLeafsBot||@RevelMagic|
|Vegas Golden Knights||@VGKGameBot||@702goonie||Forked version of V1 - not sure about V2 upgrade.|
|Washington Capitals||@CapitalsHill||@CapitalsHill||Game bot mixed into regular feed.|
- Matt Donders - https://mattdonders.com
Special thanks to all who have helped test along the way and provide data and stats to help improve the game bot and allow it to be a one-stop shop for most in-game events.