The bot is written in Python, so you need Python 3.10 or newer. Download it from python.org/downloads and run the installer.

To check it worked, open a terminal (Windows: press Win, type cmd, press Enter) and type:

> python --version
Python 3.12.4

Download owstatsbot.zip and unzip it, for example on your desktop. You get a folder called owstatsbot with four files:

Open a terminal in the bot folder

A terminal is a black window where you type commands. The easiest way to open one directly in the right folder:

1. Open the owstatsbot folder in File Explorer, the one with owstatsbot.py inside.
2. Click once into the address bar at the top, where the folder path is shown. The path turns blue.
3. Type cmd (this replaces the blue path) and press Enter.
4. A black window opens. It's already in the right folder: the line ends with \owstatsbot>.

Microsoft Windows
C:\Users\you\Desktop\owstatsbot>_

Then install the packages:

> pip install -r requirements.txt
Collecting aiohttp>=3.9 ...
Collecting python-dotenv>=1.0 ...
Successfully installed aiohttp python-dotenv

Create a bot account

Create a second Twitch account for the bot, for example my_ow_bot. That way the answers show up under the bot's name instead of yours. Using your own streamer account also works if you prefer, but I'd recommend a separate account to be on the safe side: if the token ever leaks, only the bot account is affected, not your channel.

Generate an access token

Log in with the bot account and generate a chat token on twitchtokengenerator.com: choose “Bot Chat Token” and confirm with the bot account. It needs the scopes chat:read and chat:edit.

Make a copy of .env.example and rename it to exactly .env (no other name, no .txt at the end). Open it in a text editor such as Notepad and fill in the four highlighted lines:

# Access token of the bot account (scopes: chat:read and chat:edit)TWITCH_TOKEN=oauth:a1b2c3d4e5f6... # Name of the Twitch account the bot chats withTWITCH_BOT_NAME=my_ow_bot # Channel the bot should join (without #)TWITCH_CHANNEL=your_channel_name # Streamer's BattleTagBATTLETAG=Player#1234 # OptionalPLATFORM=pcCOOLDOWN_SECONDS=10GAMEMODE=competitiveREGION=europe

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.

Open a terminal in your bot folder again, the same way as in step 2, and run:

> python owstatsbot.py
Connected to #your_channel_name as my_ow_bot
Session start saved: 412 wins, 398 losses
> @you All commands and how to use them: https://imprala.de/owstats/commands.html

Now type !owshelp in your chat. Keep the terminal window open while you stream; closing it stops the bot. To stop it on purpose, press Ctrl+C.

Recommended: make the bot a mod

Type /mod my_ow_bot in your chat. Twitch limits how fast non-mods can post, and mod status avoids that.

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 .env. Add someone else's BattleTag to look them up instead, e.g. !profile Name#1234.

Choosing a game mode

Stats commands use Competitive by default (change it with GAMEMODE in .env). 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.

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.

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.
• !today remembers 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