Login
Commands

Botstat

Mar 12, 2026

BotStat

Automatic nick, status, avatar & homepage syncing for your bot

What is BotStat?

BotStat lets you connect your bot to real-life data sources — music, gaming platforms, streaming services, and more — so your xat nick and status automatically reflect what you're doing. Once enabled, the bot refreshes your appearance every 90 seconds without any manual commands.

BotStat is opt-in. You must run !botstat on to activate it. Nothing changes until you do.

Getting Started

Step 1 — Enable BotStat
!botstat on
This registers you in the system and starts tracking.

Step 2 — Connect a service
Pick any integration below (Twitch, Spotify, Steam, etc.) and run the matching setup command.

Step 3 — Done
The bot applies your nick/status immediately and auto-refreshes every 90 seconds.

Disable BotStat
!botstat off
Stops all tracking and auto-refresh for your account immediately.

Changing Your Active Source

By default, BotStat runs through all your configured integrations and picks the first active one (priority waterfall). If you want to lock it to one specific source — like always showing Xbox regardless of what else is set up — use the source command.

Check your current source
!botstat source
Shows which source is currently active.

Pin to a specific source
!botstat source xbox
From now on, only Xbox data will update your status — all other integrations are ignored.

Reset to automatic (priority waterfall)
!botstat source auto
Goes back to normal mode — first active integration wins.

Available source names

    • auto — default, uses priority order
    • twitch — Twitch live status
    • spotify — Spotify now playing
    • lastfm — Last.fm scrobbling
    • youtube — YouTube live
    • steam — Steam profile
    • roblox — Roblox profile
    • xbox — Xbox gamertag
    • github — GitHub stats
    • reddit — Reddit karma
    • minecraft — Minecraft profile
    • fortnite — Fortnite stats
    • song — current song from DB
    • theme — seasonal/special theme
    • custom — your custom nick/status/avatar/homepage only

    If you pin to a source that has no data (e.g. your stream is offline and you pinned to twitch), BotStat won't apply anything until that source has live data. Use auto to always fall back to something.

    Priority Order

    When multiple integrations are configured, BotStat picks the first active one in this order:

    • 1. Twitch — if you have a username set
    • 2. Spotify — if you're currently playing something
    • 3. Last.fm — if a track is scrobbling now
    • 4. YouTube — if your channel is live
    • 5. Steam — profile status + top game
    • 6. Roblox — profile data
    • 7. Xbox — gamertag + gamerscore
    • 8. GitHub — repos + stars
    • 9. Reddit — karma stats
    • 10. Minecraft — UUID + skin info
    • 11. Fortnite — wins, K/D, level
    • 12. Current song (from DB, max 10 min old)
    • 13. Theme (holiday or special, if date matches)
    • 14. Custom nick/status/avatar/homepage overrides

    Custom overrides (step 14) are always applied on top of whatever source was chosen. For example, if Twitch is live, it sets the status — but your custom nick still applies.

    Want to skip the waterfall entirely and always use one specific source? See Changing Your Active Source above.

    Template Variables

    All nick and status templates support variables. Use either {variable} or $variable syntax.

    Universal

    • {nick} — your current xat username
    • {uid} — your xat user ID

    Twitch

    • {name} — Twitch login name
    • {displayname} — Twitch display name
    • {game} — current game being streamed
    • {title} — stream title
    • {viewers} — live viewer count
    • {live} — ONLINE or OFFLINE
    • {followers} — total follower count
    • {description} — channel bio
    • {twitchurl} — full Twitch URL

    Music (Spotify / Last.fm)

    • {track} — song title
    • {artist} — artist name(s)
    • {album} — album name (Last.fm only)

    YouTube

    • {youtubetitle} — live stream title
    • {youtubeviewers} — live viewer count

    Steam

    • {steamusername} — Steam display name
    • {steamgame} — top/recent game
    • {steamstatus} — Online / Away / Offline etc.
    • {steamcountry} — country code

    Roblox

    • {robloxusername} — Roblox username
    • {robloxdisplayname} — display name
    • {robloxfriends} — friend count
    • {robloxfollowers} — follower count

    Xbox

    • {xboxgamertag} — gamertag
    • {xboxgamerscore} — total gamerscore
    • {xboxgame} — most recent game played
    • {xboxaccounttier} — Gold / Silver etc.

    GitHub

    • {githubusername} — GitHub login
    • {githubdisplayname} — display name
    • {githubrepos} — public repo count
    • {githubfollowers} — follower count
    • {githubstars} — total stars across all repos
    • {githubbio} — profile bio

    Reddit

    • {redditusername} — Reddit username
    • {redditkarma} — total karma
    • {redditpostkarma} — post karma
    • {redditcommentkarma} — comment karma

    Minecraft

    • {minecraftusername} — Minecraft username
    • {minecraftuuid} — UUID (dashed format)
    • {minecraftskinmodel} — classic or slim

    Fortnite

    • {fortniteusername} — Epic/PSN/XBL username
    • {fortniteplatform} — epic, psn, or xbl
    • {fortnitelvl} — battle pass level
    • {fortnitewins} — total wins (all modes)
    • {fortniteld} — K/D ratio
    • {fortnitematches} — total matches played
    • {fortnitewinrate} — win rate (e.g. 4.20%)

    Integrations

    🎮 Twitch
    Shows live status, game, viewer count, and more from any Twitch channel.

    !botstat twitch [username] [livenick] [livestatus]

    Example:
    !botstat twitch ninja "{nick} is live — {game} ({viewers} viewers)" "🔴 Streaming {game}"

    Template example output:

    • Nick: Ninja is live — Fortnite (42000 viewers)
    • Status: 🔴 Streaming Fortnite

    If your customstatus contains any Twitch variable (like {game} or {viewers}), it is used automatically even without a livestatus argument.

    🎵 Spotify
    Shows what you're currently playing on Spotify. Requires a connected OAuth token on the bot.

    !botstat spotify [username] [playingnick] [playingstatus]

    Example:
    !botstat spotify mySpotifyUser "{nick} 🎵" "🎵 {artist} — {track}"

    Template example output:

    • Nick: Tj 🎵
    • Status: 🎵 Drake — God's Plan

    Spotify uses an OAuth access token stored in the bot's settings, not a public username lookup. Contact the bot owner if Spotify isn't working.

    🎧 Last.fm
    Shows the track currently scrobbling on your Last.fm profile.

    !botstat lastfm [username] [playingnick] [playingstatus]

    Example:
    !botstat lastfm myLastfmUser "{nick} 🎧" "🎧 {artist} — {track} ({album})"

    📺 YouTube
    Detects when your YouTube channel is live and updates your nick/status.

    !botstat youtube [channelid] [livenick] [livestatus]

    Example:
    !botstat youtube UCxxxxxx "{nick} 📺 LIVE" "📺 {youtubetitle}"

    YouTube requires a YouTube Data API key to be configured on the bot server.

    🕹️ Steam
    Pulls your Steam profile status and most recently played game.

    !botstat steam [vanityusername] [nick] [status]

    Example:
    !botstat steam mysteamname "{nick} 🕹️" "Steam: {steamstatus} — {steamgame}"

    🟥 Roblox
    Shows your Roblox profile data — display name, friends, followers.

    !botstat roblox [username] [nick] [status]

    Example:
    !botstat roblox myRobloxUser "{robloxdisplayname} 🟥" "Roblox | {robloxfriends} friends"

    🎮 Xbox
    Shows gamertag, gamerscore, account tier, and most recently played game.

    !botstat xbox [gamertag] [nick] [status]

    Example:
    !botstat xbox MyGamertag "{xboxgamertag} 🎮" "GS: {xboxgamerscore} | {xboxgame}"

    🐙 GitHub
    Displays your public GitHub stats — repos, stars, followers.

    !botstat github [username] [nick] [status]

    Example:
    !botstat github myGithubUser "{githubdisplayname} 🐙" "⭐ {githubstars} stars | {githubrepos} repos"

    🤖 Reddit
    Shows your Reddit karma stats on your nick or status.

    !botstat reddit [username] [nick] [status]

    Example:
    !botstat reddit myRedditUser "{nick} 🤖" "Reddit karma: {redditkarma}"

    ⛏️ Minecraft
    Looks up your Minecraft profile via the Mojang API — no API key needed.

    !botstat minecraft [username] [nick] [status]

    Example:
    !botstat minecraft Notch "{minecraftusername} ⛏️" "MC UUID: {minecraftuuid}"

    🏆 Fortnite
    Pulls your Fortnite stats — wins, K/D, level, win rate — across all modes.

    !botstat fortnite [username] [platform] [nick] [status]

    Platform options: epic (default), psn, xbl

    Example:
    !botstat fortnite MyEpicName epic "{nick} 🏆" "Fortnite | {fortnitewins} wins | KD {fortniteld}"

    Stats must be set to public in your Fortnite account settings or the lookup will fail.

    Themes

    Themes automatically apply a nick and status template during a seasonal date window. You don't need to set a custom nick or status — the theme handles it.

    !botstat theme [themename]

    Holiday Themes
    Active automatically during their date windows:

    • christmasgifts — Dec 1–26 | Merry Christmas! 🎁
    • christmasreindeer — Dec 1–26 | Reindeer games! 🦌
    • christmassanta — Dec 1–26 | Ho Ho Ho! 🎅
    • christmassnowflake — Dec 1–26 | Let it snow ❄️
    • christmasswinter — Dec 1–26 | Winter vibes ⛄
    • easterbunny — Apr 10–20 | Happy Easter 🐰
    • halloweenpooky — Oct 25–Nov 1 | Spooky season 🎃
    • halloweenwitch — Oct 25–Nov 1 | Witching hour 🧙‍♀️
    • newyearcelebration — Dec 31–Jan 2 | Happy New Year 🎉
    • newyearfireworks — Dec 31–Jan 2 | Boom boom 🎆
    • stpatrickslucky — Mar 15–18 | Lucky clover ☘️
    • thanksgivingturkey — Nov 20–28 | Happy Thanksgiving 🦃
    • valentineshearts — Feb 10–15 | Love is in the air ❤️

    Special Themes
    No date restriction — always active when set:

    • birthdaycelebration | Birthday mode 🎂
    • gamingmode | Gaming mode 🎮
    • musiclistening | Listening to music 🎵
    • streaminglive | Streaming live 📺

    If the theme's date window hasn't started or has passed, BotStat skips it and falls through to custom overrides.

    Custom Overrides

    Custom overrides are applied on top of any integration source. They're the fallback if nothing else matches, and also layer over themes or platform data.

    • !botstat nick [your custom nick]
    • !botstat status [your custom status]
    • !botstat avatar [avatar url]
    • !botstat homepage [url]

    Examples:

    • !botstat nick {nick} (glow#gamingmode)
    • !botstat status Just vibing 🎮
    • !botstat avatar https://example.com/myavatar.png
    • !botstat homepage https://pythbots.com

    Custom status is skipped if a current song is actively playing (from DB source). It also defers to Twitch templates if your custom status contains Twitch variables.

    Cooldown & Refresh



    Cooldown
    Prevents applying botstat more than once per 5 seconds


    5 seconds



    Auto-refresh interval
    How often BotStat re-checks your integrations and updates the bot


    90 seconds



    Current song max age
    If a song in the DB is older than this, it's skipped


    10 minutes

    Command Reference

    • !botstat on — enable BotStat for your account
    • !botstat off — disable BotStat and stop all tracking
    • !botstat twitch [username] [nick] [status] — configure Twitch
    • !botstat spotify [username] [nick] [status] — configure Spotify
    • !botstat lastfm [username] [nick] [status] — configure Last.fm
    • !botstat youtube [channelid] [nick] [status] — configure YouTube
    • !botstat steam [username] [nick] [status] — configure Steam
    • !botstat roblox [username] [nick] [status] — configure Roblox
    • !botstat xbox [gamertag] [nick] [status] — configure Xbox
    • !botstat github [username] [nick] [status] — configure GitHub
    • !botstat reddit [username] [nick] [status] — configure Reddit
    • !botstat minecraft [username] [nick] [status] — configure Minecraft
    • !botstat fortnite [username] [platform] [nick] [status] — configure Fortnite
    • !botstat theme [themename] — set a seasonal/special theme
    • !botstat source — check your active source
    • !botstat source [name] — pin to a specific source (xbox, github, auto, etc.)
    • !botstat nick [value] — set custom nick override
    • !botstat status [value] — set custom status override
    • !botstat avatar [url] — set custom avatar override
    • !botstat homepage [url] — set custom homepage override

    Profanity Filter

    All nick, status, homepage, and avatar values are automatically passed through a profanity filter before being applied. Matched words are replaced with .

    The filter uses two layers:

    • Basic blocked words — a hardcoded list of common profanity
    • Custom rules — loaded from cuss.json, supports wildcard patterns and per-rule exceptions

    Any value that triggers the filter will have matching words replaced silently. The command will not fail — only the filtered text is applied.

    Troubleshooting

    Nothing is updating

    • Make sure you ran !botstat on
    • Confirm your integration is configured (e.g. !botstat twitch ...)
    • Check if your stats/stream is private (Fortnite, Steam, etc.)
    • Cooldown: wait at least 5 seconds between manual triggers

    Twitch not showing live info

    • Confirm the Twitch username is spelled correctly
    • Verify your stream is actually live
    • Make sure your livestatus template uses a Twitch variable (e.g. {game}, {viewers}) — otherwise the bot has nothing to apply

    Fortnite stats not loading

    • Go to Fortnite → Settings → Account → Public Game Stats and enable it
    • Make sure the platform flag matches your account (epic, psn, or xbl)

    Spotify isn't detecting music

    • Spotify uses an OAuth token stored server-side — if it's expired, contact the bot owner to reconnect it
    • Make sure music is actually playing (not paused)

    Theme not applying

    • Themes only activate within their date window — check the dates listed above
    • Special themes (gamingmode, musiclistening, etc.) have no date restriction and always activate

    My nick has in it

    • The profanity filter replaced a word in your nick/status template
    • Edit your template to remove or rephrase the flagged text

BotStat — PythBots | Auto-refreshes every 90s