Skip to content
StreamerCatalyst Docs

Using the Chatters API to Pick a Random VIP

The Chatters module serves as your stream’s dedicated chat bot, managing custom commands, scheduled auto-chats, regulars, and giveaways. One of its most powerful features is a public API that allows external bots—such as Nightbot, StreamElements, or Fossabot—to interact with your channel data.

In this recipe, we will walk through setting up a command that lets you instantly pick a random VIP from your chat using Nightbot.

Prerequisites

  • A StreamerCatalyst account with the Chatters module enabled (Module access by tier).
  • An external bot (like Nightbot) already integrated into your Twitch channel.

Step 1: Generate your API key

To allow an external bot to securely request data from StreamerCatalyst, you must use a unique 64-character hex API key.

  1. Open the Chatters module in your StreamerCatalyst dashboard.
  2. Navigate to Settings → API key.
  3. Copy your 64-character hex key.

[!WARNING] Keep your API key private. Anyone with this key can call the bot API on behalf of your channel.

Step 2: Configure the API request

We will use the Random chatter endpoint to select a user. Based on the Chatters — API endpoints documentation, the base URL is https://chatters.streamercatalyst.com.

To ensure the bot only picks from your VIPs, we will use the vip filter. The final URL structure for our request will look like this:

https://chatters.streamercatalyst.com/api/random?apikey=<your_api_key>&filter=vip

Step 3: Deploy the command via Nightbot

Nightbot can call StreamerCatalyst endpoints using the $(urlfetch) variable. Because the Chatters API returns plain-text strings, Nightbot can paste the result directly into your chat without any extra parsing.

To create the command, copy and paste the following line into your Twitch chat:

!addcom !randomvip A random VIP has been selected: $(urlfetch https://chatters.streamercatalyst.com/api/random?apikey=YOUR_64_CHAR_HEX_KEY&filter=vip)

Note: Replace YOUR_64_CHAR_HEX_KEY with the actual key you copied in Step 1.

How it works

  1. The Trigger: A moderator or user types !randomvip in your Twitch chat.
  2. The Fetch: Nightbot sees the $(urlfetch) command and sends a GET request to the StreamerCatalyst API.
  3. The Filtering: The Chatters module receives the request, looks at your chatters, and filters for those with vip status.
  4. The Result: The API picks one name at random and returns it as plain text (e.g., Alice).
  5. The Output: Nightbot receives the name and posts the final message to your chat:
    A random VIP has been selected: Alice

For more advanced configurations, such as picking multiple chatters or using specific formats, see the Bot integration guide.