Bot integration

The Chatters module exposes a plain-text bot API that external chat bots (Nightbot, StreamElements, Fossabot, and others) can call from a $(urlfetch ...) or equivalent command. The API returns a plain-text string the bot pastes directly to chat — no parsing required.

You don’t need the API for commands that run in Chatters itself: $(randomchatter [FILTER]) in a custom command draws from the same chatter list with the same filters.

Getting your API key

1. Open Chatters → Bot Setup in the StreamerCatalyst dashboard and select the Bot API tab.
2. Click Regenerate to create a key (or to replace the one you have). Only the broadcaster can do this.
3. Copy the 64-character hex key straight away. It is shown in full only right after you regenerate it; after a reload the page shows it masked, and moderators only ever see the masked form.

Regenerating replaces the key immediately — every bot command using the old key stops working until you paste in the new one.

Keep your API key private. Anyone with it can call the bot API for your channel and read who is in your chat.

Base URL

All bot API endpoints are on:

https://chatters.streamercatalyst.com

Every endpoint is a GET that authenticates with the apikey query parameter. The key identifies your channel, so no other channel parameter is needed; the URLs the dashboard builds also carry a channel= parameter, which the API ignores.

Endpoints

Random chatter

Returns a random chatter’s display name (or a comma-separated list if n > 1).

GET /api/random?apikey=<key>
GET /api/random?apikey=<key>&filter=<filter>
GET /api/random?apikey=<key>&filter=<filter>&n=<count>
GET /api/random?apikey=<key>&n=2&format=<template>

Parameter	Description
apikey	Your 64-char hex API key (required)
filter	Optional chatter filter (see Filter values). Without one, the Default filter for !random set on the Bot API tab applies (none by default)
n	Number of distinct chatters to return, 1–10 (default: 1). If fewer people match, you get fewer names
format	A template whose {0}, {1}, … placeholders are replaced by the picked names, in order. Only as many placeholders are filled as names were picked, so use n to pick enough

Example response:

StreamerName

Example with n=3:

Alice, Bob, Carol

Example with n=2 and format set to {0} owes {1} a coffee (in the URL, write the spaces as %20: &n=2&format={0}%20owes%20{1}%20a%20coffee):

Alice owes Bob a coffee

With @mention prefix switched on (Chatters → Bot Setup → Settings), each name comes back as @Alice. A format template is left exactly as you wrote it, so put the @ in the template yourself if you want it (@{0}).

FMK (Marry/Kill picker)

Returns exactly three different random chatters joined with vs.

GET /api/fmk?apikey=<key>

Parameter	Description
apikey	Your 64-char hex API key (required)

Example response:

Alice vs Bob vs Carol

FMK draws from everyone in chat; it takes no filter. It needs at least three chatters and answers Not enough chatters for FMK when there are fewer. The @mention prefix setting applies here too (@Alice vs @Bob vs @Carol).

Chatter list

Returns the full chatter list as plain text (comma-separated display names) or JSON.

GET /api/chatters?apikey=<key>
GET /api/chatters?apikey=<key>&filter=<filter>
GET /api/chatters?apikey=<key>&filter=<filter>&format=json

Parameter	Description
apikey	Your 64-char hex API key (required)
filter	Optional chatter filter (see Filter values). The Bot API tab’s default filter does not apply here
format	Pass json to receive a JSON array instead of plain text

Example plain-text response:

Alice, Bob, Carol, Dave

Example JSON response — one object per chatter:

[{"user_id":"123456","user_login":"alice","user_name":"Alice"}]

If a filter leaves nobody, the plain-text answer is No chatters (and the JSON answer an empty array). The @mention prefix is not applied to this endpoint.

Filter values

Filters are comma-separated tokens, matched without regard to case. Combine them to narrow the chatter pool — every token must match, so sub,not_follower returns subscribers who are not followers. A token the API doesn’t recognise is ignored rather than rejected, so check the spelling if a filter seems to do nothing.

Filter	Keeps chatters who are…
sub	Any subscriber
not_sub	Not subscribed (not_subbed also works)
tier1	Tier 1 subscriber (exactly)
tier2	Tier 2 subscriber (exactly)
tier3	Tier 3 subscriber (exactly)
vip	VIP
mod	Moderator
follower	Following the channel
not_follower	Not following the channel

How fresh the lists are. The chatter list and the filter lists are read from Twitch and kept for a while so that a bot command answers quickly: the chatter list and subscriber lists are refreshed after about three minutes, the VIP and moderator lists after about fifteen, and the follower list after about an hour. Someone who joined chat, subscribed or followed moments ago may not be picked yet.

Error responses

All endpoints return a plain-text error string when something goes wrong — the bot pastes it to chat, which is useful for debugging:

Error	Cause
Invalid or missing apikey	The apikey parameter is absent, isn’t a 64-character lowercase hex key, or isn’t a current key (for example, it was regenerated)
Channel not found or disabled	The Chatters bot is switched off on Chatters → Overview, or Chatters has no settings stored for the channel yet — saving any Chatters setting (such as Save under Command aliases & defaults on the Bot API tab) creates them
Channel tokens expired — broadcaster must re-authenticate	The broadcaster’s Twitch authorization is missing or expired; they need to sign in to the dashboard again
No chatters found — is the stream live?	Nobody is connected to your chat right now (any endpoint)
No chatters found matching filter	/api/random only: the filter left nobody to pick
No chatters	/api/chatters only (plain text): the filter left nobody
Not enough chatters for FMK	/api/fmk only: fewer than three people in chat

Ready-made commands

The Bot API tab builds these for you: pick StreamElements, Nightbot or Fossabot and copy the command text for your !random command (with your default filter), a subscribers-only !sub, and !fmk. The names in the !random alias and !fmk alias boxes are just the labels for that list — the command is created in your other bot, under whatever name you give it there. The key is filled in only while it is shown in full (right after Regenerate); otherwise the URLs carry a YOUR_API_KEY placeholder to replace.

Nightbot setup

In Nightbot, create a custom command with a $(urlfetch ...) response:

$(urlfetch https://chatters.streamercatalyst.com/api/random?apikey=YOUR_KEY)

To pick from subscribers only:

$(urlfetch https://chatters.streamercatalyst.com/api/random?apikey=YOUR_KEY&filter=sub)

An FMK command:

$(urlfetch https://chatters.streamercatalyst.com/api/fmk?apikey=YOUR_KEY)

StreamElements setup

In StreamElements, use ${customapi.URL} in a command response:

${customapi.https://chatters.streamercatalyst.com/api/random?apikey=YOUR_KEY}

The dashboard’s StreamElements tab writes the same thing as $(customapi.URL), which StreamElements also accepts.

Fossabot setup

In Fossabot, use $(customapi URL):

$(customapi https://chatters.streamercatalyst.com/api/random?apikey=YOUR_KEY)

Public commands page

Each channel’s public command list is available at:

https://chatters.streamercatalyst.com/c/<channel_login>/commands

This page needs no login and is linked by the built-in !commands command. It lists your enabled built-in commands and your enabled custom commands with their responses, minus any marked Hidden from public command list. It is on by default; the broadcaster or a Lead Mod can switch it off with Public commands page on Chatters → Bot Setup → Settings, after which the address answers Channel not found.