Streamer.bot and other tools
Updated 5 days agoThe companion is optional. Any tool that can append a line to a text file can drive the mod: Streamer.bot, Mix It Up, your own bot...
All files are in %LOCALAPPDATA%\Helden\Saved\GrainRotChatChaos\. Each line is one flat JSON object (no nested objects, no arrays), UTF-8, ending with a line break.
Sending a redemption: inbox.jsonl
Append one line per redemption:
{"v":1,"t":"redeem","id":"8f1c2e9a-...","src":"points","reward":"yeet","user":"viewer_login","name":"Viewer Name","cost":800,"ts":1760371200}
| Field | Required | Value |
|---|---|---|
v |
yes | 1 |
t |
yes | "redeem" |
id |
yes | Unique id, at most 64 characters (the Twitch redemption id). The same id is never played twice. |
reward |
yes | Effect key: scare, boom, yeet, trip, moon, boss, slowmo, coins, stamina, god, spawn, weapon, infect, smite |
name |
no | Name shown on the banner (cut to 25 characters) |
src |
no | Free text, for example "points" or "bits" |
user, cost, ts |
no | Informative |
cd |
no | Whole number of seconds: cooldown to apply for this effect, instead of the default one |
Write each line in one go. Lines over 1 KB, invalid JSON or "v" other than 1 are ignored and logged.
Reading the answer: outbox.jsonl
The mod appends one answer per redemption:
{"v":1,"t":"ack","id":"8f1c2e9a-...","status":"FULFILLED","reason":"ok"}
{"v":1,"t":"ack","id":"7a9b...","status":"CANCELED","reason":"wrong_place"}
FULFILLED: the effect was played.CANCELED: it wasn't, refund the viewer. The reasons are explained on the Troubleshooting page.
Every 5 seconds the mod also writes a heartbeat:
{"v":1,"t":"hb","ts":1760371206,"where":"dungeon","host":1,"enabled":1}
where is menu, outpost or dungeon. If no heartbeat came for 15 s, or it says menu, host:0 or enabled:0, pause your rewards: everything redeemed now would be refunded.
Refunds
Twitch only lets the app that created a reward refund its redemptions. If Streamer.bot created your rewards, it has to handle CANCELED itself (for example by reading outbox.jsonl). Rewards created by hand in the dashboard can't be refunded by any app.
Testing without Twitch
Write a line with Notepad and save:
{"v":1,"t":"redeem","id":"test-1","reward":"scare","name":"Test"}
Press Enter after the line before saving: the mod only reads complete lines. The jump scare plays within a second, and outbox.jsonl gets the answer. Use a new id each time.
