Install Python
The bot is written in Python, so you need Python 3.10 or newer once. Download it from python.org/downloads and run the installer.
Install Python 3
Download and start
Download owstatsbot.zip and unzip it, for example on your desktop (right-click → Extract all). Open the folder owstatsbot and double-click START.bat.
| File | What it is |
|---|---|
START.bat | Double-click this to start the bot |
owstatsbot.py | The bot itself |
requirements.txt | Tells the setup which Python package to install |
setup-guide.html | This guide |
If Windows shows a blue “Windows protected your PC” box, click More info → Run anyway. That happens with every downloaded script, not just this one.
On the first start the bot sets itself up (about a minute) and asks two questions: your Twitch channel name and your BattleTag. Type each one and press Enter.
First start: setting up, this takes about a minute ... Welcome to OWStats! Two quick questions, then you're done. 1/2 Your Twitch channel name: your_channel 2/2 Your BattleTag (e.g. Name#1234): Player#1234 Found your profile. Saved to settings.txt.
settings.txt. You can change them there later.Log in with Twitch
Right after the questions, your browser opens Twitch. Log in with the account the bot should chat as and click Authorize. That's the whole login: no token, no copying. The bot remembers it and renews it by itself.
Recommended: a separate bot account
Create a second Twitch account for the bot, for example my_ow_bot. Then the answers show up under the bot's name, and your own account stays out of it. Your browser is probably logged in as you, so open the link the bot shows in a private/incognito window and log in there with the bot account. Using your own account also works.
TWITCH LOGIN Your browser opens Twitch now. Log in with the account the bot should chat as (a separate bot account is recommended) and click "Authorize". Browser didn't open, or you want another account? Open this link in a private/incognito window: https://www.twitch.tv/activate?... Waiting for you ... Logged in as my_ow_bot. The bot remembers this, no need to log in again. Connected to #your_channel as my_ow_bot Session start saved: 412 wins, 398 losses
Make your profile public
The bot reads your stats from your public career profile. If the profile is private, there's nothing to read. In Overwatch, open Options → Social → Career Profile Visibility and set it to Public.
The change often only takes effect after you play one match or log out and back in. Profiles also update a few minutes after each match, not instantly.
Test it
Type !owshelp in your chat. The bot answers with a link to all commands. Keep the black window open while you stream; closing it stops the bot.
!owshelpRecommended: make the bot a mod
Type /mod my_ow_bot in your chat (with your bot's name). Twitch limits how fast non-mods can post, and mod status avoids that.
/mod my_ow_botFrom now on: double-click
START.bat at the start of each stream, so !today counts from the right moment. No questions, no login.All commands
Upper and lower case don't matter. Every command except !reset has a cooldown (10 seconds by default). If someone tries too early, the bot tells them once how long to wait.
Stats from the streamer's profile
All of these use the BattleTag from your settings.txt. Add someone else's BattleTag to look them up instead, e.g. !profile Name#1234.
| Type in chat | What the bot answers |
|---|---|
!rank | Tank, DPS and Support rank (plus Open Queue if placed) |
!rank tank | Only one role. Also works with dps, support, open and short forms like dmg, supp, heal |
!main | Top 3 most played heroes with playtime and win rate |
!stats <hero> | Games, win rate, KDA, playtime and per-10-minute averages, e.g. !stats kiriko |
!playtime | Total playtime, split into Quick Play and Competitive. !playtime ana does the same for one hero. |
!roles | Win rate, KDA and playtime for Tank, DPS and Support, plus the best role |
!best | Career records from a single game: most elims, damage, healing, longest kill streak and more |
!best <hero> | Records on one hero, including hero-specific ones like most enemies slept as Ana |
!besthero | Hero with the highest win rate (only heroes with at least 5 games count) |
!worst | Hero with the lowest win rate, for some friendly roasting |
!profile | Title, endorsement level and when the profile was last updated (!endorse does the same) |
!compare Name#1234 | Win rate, KDA and games played side by side with another player |
!today | Wins, losses and rank changes since the bot started or the last reset |
!reset | Sets the !today counter back to 0. Streamer and mods only. |
Choosing a game mode
Stats commands use Competitive by default (change it with GAMEMODE in settings.txt). Add qp, comp or all to any of !main, !stats, !roles, !best, !besthero, !worst and !compare to switch, for example !main qp or !stats ana all.
Game info
These don't need a profile at all.
| Type in chat | What the bot answers |
|---|---|
!hero <hero> | Role, HP, home location and abilities of a hero, e.g. !hero ana |
!meta | Top 5 heroes in Competitive by win rate right now. Narrow it down with a role and a rank: !meta support diamond. Add pick or ban to sort by pick rate or ban rate. |
!owshelp | Posts a link to the command overview page (set with HELP_URL) |
Hero nicknames
s76 Soldier: 76, ball or hammond Wrecking Ball, jq Junker Queen, dva D.Va, widow Widowmaker, rein Reinhardt, zen Zenyatta, brig Brigitte, bap Baptiste, torb Torbjörn, sym Symmetra, hog Roadhog, lw Lifeweaver, cass Cassidy, soj Sojourn, doom Doomfist, rama Ramattra, cat Jetpack Cat. All other heroes work with their normal name, accents optional. If you make a typo, the bot suggests the closest hero.
Settings
Everything is optional. Open settings.txt in the bot folder (double-click opens Notepad), change a value, save, and restart the bot.
| Setting | What it does |
|---|---|
TWITCH_CHANNEL | Your channel name, the part after twitch.tv/ |
BATTLETAG | Your BattleTag including the number, with exact upper and lower case |
PLATFORM | pc or console |
GAMEMODE | Default mode for stats commands: competitive or quickplay |
REGION | Region for !meta: europe, americas or asia |
COOLDOWN_SECONDS | How long each command is locked after use. Default is 10 seconds, the minimum is 5. |
MIN_GAMES | How many games a hero needs to count for !besthero and !worst (default 5) |
HELP_URL | The link !owshelp posts in chat (default https://imprala.de/owstats/commands) |
To log the bot in with a different Twitch account, delete the data folder in the bot folder and start START.bat again.
How it works
Overwatch has no official stats API. The bot uses the free community project OverFast API, which reads public career profiles and returns them as data.
- The bot runs on your own computer. Nothing is installed on Twitch.
!todayremembers your total wins and losses when the bot starts and compares them later. That's why it counts from bot start or the last!reset.- To go easy on the free API, the bot remembers player stats for 2 minutes, and hero and map info for several hours.
- The very first lookup of a profile can take up to a minute, because OverFast has to fetch it fresh. After that it's cached and fast. The bot waits up to 60 seconds and retries 3 times.
Troubleshooting
| You see | What to do |
|---|---|
Windows protected your PC | Click More info → Run anyway. Windows shows this for every downloaded script. |
Python 3.10 or newer is missing | Install Python from python.org and tick “Add python.exe to PATH”. If it's installed already: run the installer again, choose Modify, and tick “Add Python to environment variables”. |
Twitch refused the login | The bot renews the login by itself. If it keeps asking, just log in again in the browser. Nothing to copy. |
Logged in with the wrong account | Delete the data folder in the bot folder and start START.bat again. Open the login link in a private window to choose the bot account. |
Updating from an older version | Your old .env keeps working. To get the automatic login instead: copy the new files into your bot folder, delete .env and start START.bat. |
Player not found | Check the BattleTag, including upper and lower case. Make sure the profile is public, then play one match. You can test with overfast-api.tekrop.fr/players?name=YourName: if your name shows up there, the listed player_id tells you the exact spelling. After a failed lookup the API waits before asking Blizzard again (10 minutes at first, longer after repeated tries); the bot tells you how long. |
The Overwatch API is not responding | Usually the slow first lookup. Wait a minute and try again. If it keeps happening, the OverFast service is overloaded; try later. |
Tank: unranked | Normal if you haven't placed in that role this season. |
!today shows 0 right after a win | Blizzard updates profiles a few minutes after each match. Ask again a bit later. |
!rank is on cooldown | Each command can only be used once every 10 seconds. The bot tells each person once per cooldown and stays quiet if they keep trying, so chat isn't flooded. You can lower it to 5 seconds, but not below. |