Bots

Stream Bounty works with bots in both directions. Your bot can tell Stream Bounty to do something, by requesting a URL. And Stream Bounty can tell your bot what is happening in the game, over a websocket or a webhook.

Everything here is under Bot Integration in the extension’s configuration. There are videos of setting this up in our Discord.

Your API key

Every URL on this page includes your API key, which is what proves a request comes from you. Treat it like a password: anyone who has it can call events in your games.

If you think someone else has your key, regenerate it in Bot Integration. The old key and every URL that used it stop working, so update your bot with the new ones.

Calling events from your bot

Your bot calls an event by sending an HTTP POST request to that event’s URL. Any bot that can make a web request can do it; check your bot’s documentation if you’re not sure.

POST https://api.stream-bounty.com/games/events/{channelId}/{API_KEY}/{EVENT_ID}/call

You don’t build these by hand. Bot Integration lists the URL for every event in your sets, ready to copy.

To take a call back, send the same request with /uncall on the end in place of /call:

POST https://api.stream-bounty.com/games/events/{channelId}/{API_KEY}/{EVENT_ID}/uncall

Special commands

Three more URLs act on the game as a whole:

Command	URL ends with	What it does
Call Random	/games/events/{channelId}/{API_KEY}/callrandom	Calls a random uncalled event or number
Call All	/games/events/{channelId}/{API_KEY}/callall	Calls every uncalled event or number
Start Vote	/games/voting/{channelId}/{API_KEY}/start	Starts a voting round

For example, in JavaScript:

fetch("https://api.stream-bounty.com/games/events/{channelId}/{API_KEY}/callrandom", {
  method: "POST"
});

Hearing from Stream Bounty

Stream Bounty can send your bot a message when something happens in a game. Use it to play a sound, post in chat or change your overlay. There are two ways to receive the messages.

WebSockets (recommended)

Copy your WebSocket URL from Bot Integration and connect to it. This suits Streamlabs, Nightbot, custom bots and most platforms.

const ws = new WebSocket("your WebSocket URL");
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log("Received event:", data);
};

A websocket receives every type of message, and reconnects by itself if the connection drops.

Webhooks

With a webhook, Stream Bounty sends each message to a URL of yours as an HTTP POST request. This suits MixItUp and custom web services.

1. Enter your webhook URL in Bot Integration and set it.
2. Stream Bounty sends a confirmation code to that URL. Enter the code to confirm the URL is yours.
3. Choose which types of message you want to receive.
4. Use the test buttons to send an example of each, and see what your bot gets.

The messages

Every message is JSON, and its type field says what happened.

type	Sent when	Also contains
GAME_STARTED	A game starts	events, isSubOnly, randomCallOnly, bingoPatterns, gameMode, triggeredBy
EVENT_CALLED	An event or number is called	displayNumber, eventId, eventName, calledLabel, gameMode, trigger, triggeredBy
EVENT_UNCALLED	A call is taken back	displayNumber, eventId, eventName, uncalledLabel, gameMode, trigger, triggeredBy
ALL_EVENTS_CALLED	Everything left is called at once	trigger, triggeredBy
PLAYER_JOINED	A player joins	playerName, playerId
BINGO_REGISTERED	A player gets bingo	rank, playerName, playerId
EXTRA_CARD_WITH_BITS	A player gets an extra card	playerName, playerId, bits
VOTE_STARTED	A voting round starts	trigger, triggeredBy
EXTRA_VOTE_WITH_BITS	A player casts an extra vote	playerName, playerId, bits
VOTE_ENDED	A voting round ends
GAME_ENDED	The game ends	triggeredBy

An example, sent when event 12 is called:

{
  "displayNumber": 12,
  "eventId": "429975024",
  "eventName": "Got Raided",
  "calledLabel": "12 - Got Raided",
  "gameMode": "BingoWithEvents",
  "trigger": "Manual",
  "triggeredBy": "140296272",
  "type": "EVENT_CALLED"
}

Bot Integration shows a full example of each message.