TwitchFlags
TwitchFlags is a public registry where Twitch users pick an ISO 3166-1 country or territory flag to show next to their name, plus browser extensions that render those flags in Twitch live chat, VOD chat, and Creator Dashboard chat. A public, key-free API serves flag mappings by Twitch user ID, and a small client library (TwitchFlagsJS) wraps it for overlays and widgets.
Platforms: Web, Chrome extension, Firefox add-on, Public REST API, JavaScript client library
Product page: desertice.tech/products/twitchflags
Who it’s for: Twitch viewers who want a flag by their name, streamers who want to see flags in chat, and developers who want to read flags via the API
Features
Section titled “Features”- Set your public country or territory flag once at twitchflags.live
- Twemoji flags beside usernames in Twitch live chat, VOD chat, and Creator Dashboard chat
- Localized country or territory names on hover and keyboard focus
- Popup setting for flag placement before or after the username
- Seven-day local cache in the extension to reduce public API lookups
- Public GET /api/flags/{twitchUserId} endpoint with CORS enabled and one-week cacheable responses
- TwitchFlagsJS browser-global helper returning ISO codes, emoji, shortcodes, localized names, or Twemoji images
- Only the Twitch user ID-to-flag mapping is stored; OAuth tokens are not retained
Requirements
Section titled “Requirements”- A Twitch account to connect at twitchflags.live and set a flag
- A supported client (the Chrome or Firefox extension) to see flags in chat
- For API users: a digits-only Twitch numeric user ID; no authentication required
Install
Section titled “Install”- Visit twitchflags.live and click Connect Twitch
- Choose the country or territory to associate with your Twitch identity and save
- Install the browser extension from the Chrome Web Store (works in Edge, Brave, and other Chromium browsers) or Firefox Add-ons to see registered flags in chat
- Use the extension popup to place flags before or after usernames
- Make sure your browser allows the first-party twitchflags_session cookie so Twitch connect works
- Flag reads are cached for up to a week by clients and shared caches, so changes may take time to appear everywhere
Using it
Section titled “Using it”- Fetch any user’s flag with GET /api/flags/{twitchUserId}; a 200 response returns {“twitchUserId”:“…”,“flag”:“US”}
- A 404 flag_not_set response means the user has not saved a flag; 429 means rate limited
- Load TwitchFlagsJS from the pinned jsDelivr URL (with integrity hash) or the GitHub Pages build to follow future updates
- TwitchFlagsJS lookup methods return promises that resolve with an empty result instead of rejecting; successful flags are cached for the page lifetime and missing flags for one hour
- Community chat widgets (vertical-chat, horizontal-chat) show integration examples for placing flags beside usernames
Troubleshooting
Section titled “Troubleshooting”Twitch will not connect
Section titled “Twitch will not connect”Return to the home page and choose Connect Twitch again, make sure your browser allows the first-party twitchflags_session cookie, and if an old session seems stuck, sign out, refresh, and connect again.
The flag will not save or remove
Section titled “The flag will not save or remove”Choose a country or territory before saving, wait for the current request to finish, and after repeated attempts wait at least one minute because changes are rate limited. Refresh once to confirm whether the change was already applied.
A supported client still shows the old flag
Section titled “A supported client still shows the old flag”Browsers and shared edge caches may keep flag reads for one week. The service invalidates its CDN entry after a successful change but cannot clear copies already held by a browser or intermediary.
API returns 400 invalid_twitch_user_id
Section titled “API returns 400 invalid_twitch_user_id”Use a digits-only Twitch numeric user ID, not a username.
API returns 429 rate_limited
Section titled “API returns 429 rate_limited”Reduce request frequency, cache responses, avoid tight retry loops, and wait for the one-minute request window before retrying.
What data does TwitchFlags store?
Section titled “What data does TwitchFlags store?”Only the Twitch user ID-to-flag mapping. Twitch identity claims stay in the encrypted browser session, and OAuth access tokens, refresh tokens, and email addresses are not retained.
Is TwitchFlags affiliated with Twitch?
Section titled “Is TwitchFlags affiliated with Twitch?”No. It is independent and is not affiliated with, endorsed by, or sponsored by Twitch.