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.

Getting your API key

1. Open Chatters in the StreamerCatalyst dashboard.
2. Go to Settings → API key.
3. Copy the 64-character hex key shown. If you need to rotate it, click Regenerate.

Keep your API key private. Anyone with it can call the bot API on behalf of your channel.

Base URL

All bot API endpoints are on:

https://chatters.streamercatalyst.com

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>&format=<template>

Parameter	Description
apikey	Your 64-char hex API key (required)
filter	Optional chatter filter (see Filter values)
n	Number of chatters to return, 1–10 (default: 1)
format	Format string with {0}, {1}, … placeholders replacing names

Example response:

StreamerName

Example with n=3:

Alice, Bob, Carol

FMK (Marry/Kill picker)

Returns exactly three random chatters formatted as a comparison.

GET /api/fmk?apikey=<key>

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

Example response:

Alice vs Bob vs Carol

Requires at least three chatters. Returns an error string if the stream has fewer.

Chatter list

Returns the full chatter list as plain text (comma-separated) 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)
format	Pass json to receive a JSON array instead of plain text

Example plain-text response:

Alice, Bob, Carol, Dave

Filter values

Filters are comma-separated tokens. Combine them to narrow the chatter pool — for example sub,not_follower returns subscribers who are not followers.

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

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 param is absent or not recognised
Channel not found or disabled	The Chatters module is disabled for this channel
Channel tokens expired — broadcaster must re-authenticate	The broadcaster’s Twitch OAuth has expired; they need to re-connect on the dashboard
No chatters found — is the stream live?	The stream is offline or the chatter list is empty
No chatters found matching filter	The filter returned zero results
Not enough chatters for FMK	Fewer than three chatters in the live chatter list

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)

StreamElements setup

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

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

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 is unauthenticated and can be linked from your !commands command. The broadcaster must enable Public commands page in Chatters settings for the page to be visible.