Skip to content

Streamer Alerts

Jump to bottom
Jerad Berhow edited this page Oct 10, 2026 · 5 revisions

Streamer Alerts

PariahBot posts an alert in your server when a streamer goes live on Twitch or YouTube, and when a YouTube channel uploads a new video.

There are two ways onto the streamer list. They work side by side, on both platforms:

Who adds it Needs the streamer role? Member required?
Self-linked The member, with /streamers link Yes, checked on every alert. Remove the role and their alerts stop straight away. Yes, the member who linked it
Admin-added An admin, with /streamers add No. The admin adding it is the permission. No. It can be a channel whose owner isn't in the server.

Instagram posts are a separate feature with their own channel. See Instagram-Alerts.

Setup has two halves: credentials on the bot's host (once per bot), then configuration in each Discord server (once per server).

Part 1: credentials on the host

Each platform is optional and turns on independently. A platform with no credentials just stays off; the bot logs it at startup, and /streamers warns about it.

Twitch

  1. Go to dev.twitch.tv/console/apps and choose Register Your Application. Your Twitch account needs two-factor authentication turned on first.
  2. Fill in the form:
    • Name: anything unique, e.g. PariahBot-YourServer
    • OAuth Redirect URLs: http://localhost. It's never used, but the form requires one.
    • Category: anything, e.g. Chat Bot
    • Client Type: Confidential. Public apps get no client secret, and the bot can't sign in without one.
  3. Open the app, copy the Client ID, then choose New Secret and copy the Client Secret.

YouTube

You need a YouTube Data API v3 key from Google Cloud. It's free and needs no billing account.

In the Google Cloud console:

  1. Create a project at console.cloud.google.com, e.g. PariahBot.
  2. APIs & Services → Library, search for YouTube Data API v3, and choose Enable.
  3. APIs & Services → Credentials → Create credentials → API key.
  4. Open the new key. Under API restrictions, choose Restrict key and tick only YouTube Data API v3. If your bot host has a fixed IP address, also add it under Application restrictions → IP addresses.

Or with the gcloud CLI, once you've signed in with gcloud auth login:

gcloud services enable youtube.googleapis.com apikeys.googleapis.com --project=YOUR_PROJECT
gcloud services api-keys create --project=YOUR_PROJECT \
  --display-name="PariahBot YouTube alerts" \
  --api-target=service=youtube.googleapis.com
# The create output includes the key's name (projects/…/keys/…). To print the key itself:
gcloud services api-keys get-key-string projects/…/locations/global/keys/… --project=YOUR_PROJECT

Add them to hom.env and restart

TWITCH_CLIENT_ID=your-client-id
TWITCH_CLIENT_SECRET=your-client-secret
YOUTUBE_API_KEY=your-api-key
sudo systemctl restart pariahbot.service
sudo journalctl -u pariahbot.service -n 30

The bot only reads hom.env at startup. If /streamers still says a platform "isn't set up on this bot's host" after you've added its values, the bot hasn't been restarted since.

When it's working, the startup log has no StreamAlerts: … not set — … alerts are disabled. line for that platform. See Configuration for the rest of hom.env.

Part 2: set up a server

The setup steps need a mod or an admin. See Server Configuration.

1. Choose where alerts post

/streamers channel channel:#live-now ping_role:@Stream-Notify
  • ping_role is optional, and is the only thing an alert ever pings. The streamer is named in the embed, where a mention doesn't notify them.
  • The bot checks up front that it can View Channel, Send Messages and Embed Links there, and refuses with the fix if not.
  • If the ping role isn't mentionable, the reply warns you. Turn on Allow anyone to @mention this role in its settings, or give the bot Mention Everyone.
  • Live alerts and upload alerts both post here.

Custom message (optional)

By default an alert's text is just the ping role. Set your own message, and the role is still pinged:

/streamers message text:{role} {name} is live on {platform}: {title}

Which posts as:

@Stream-Notify SomeStreamer is live on Twitch: Ranked grind tonight!

Placeholder Becomes
{name} The streamer or channel name
{title} The stream or video title
{url} The link
{platform} Twitch or YouTube
{role} The ping role's mention
  • Where the ping goes: where you put {role}. Without it, the ping goes at the start. With no ping role set, the message posts without a ping.
  • Only the ping role ever notifies anyone. @everyone, @here or other mentions in your message show as text but don't ping.
  • A misspelt placeholder like {titel} is refused, with the list of valid ones.
  • The reply shows a preview with sample values, so you can check it.
  • /streamers clear-message goes back to just the ping. /streamers list shows the current message. /streamers disable keeps it.
  • Up to 1,000 characters.

2. Get streamers onto the list

Option A: members link themselves. Set the streamer role, then give it to your streamers:

/setup streamer-role role:@Streamer

Each streamer then runs:

/streamers link platform:Twitch account:their_twitch_name
/streamers link platform:YouTube account:@TheirHandle

Option B: admins add channels directly. No role is needed, and a member is optional:

/streamers add platform:YouTube account:@SomeChannel
/streamers add platform:Twitch account:some_streamer member:@TheirDiscordAccount

What to type for account:

Platform Accepted
Twitch The username, as in twitch.tv/<username>
YouTube An @handle, a youtube.com/@handle or youtube.com/channel/UC… link, or a bare UC… channel ID

The bot looks the channel up straight away, so a typo fails immediately instead of silently never alerting.

3. Check it

/streamers list

This shows the alert channel, the ping role, the streamer role, whether Twitch and YouTube are switched on for this bot, and every streamer on the list. Each streamer is marked streamer role or added by admin.

What gets announced

Platform Alert When
Twitch 🟣 Live Within about a minute of going live
YouTube 🔴 Live When a stream or premiere starts, usually within 2–10 minutes. A stream the bot only finds through the /live page (see below) can take up to about 15 minutes.
YouTube 🔴 New upload When a new video is published, usually within 2–10 minutes

Each alert posts once, even if the bot restarts mid-stream.

Never announced:

  • Anything posted before the channel was added. A newly added YouTube channel doesn't flood you with its back catalogue. The first alert is its next new upload or stream.
  • Scheduled YouTube streams, until they actually start.
  • The recording of a finished YouTube stream. It has the same video ID as the live stream, so it isn't announced again as an "upload".
  • A self-linked streamer who has lost the streamer role. Admin-added streamers don't need it.

Managing the list

Command Who Effect
/streamers unlink [platform] Anyone Removes your own links, for one platform or all of them. Admin-added entries for you stay, and the reply says so.
/streamers remove member:@User Admin Removes everything attached to that member, self-linked or admin-added, on both platforms.
/streamers remove account:<pick> Admin Removes one channel. Start typing and pick from the suggestions. If you type a name instead, also set platform:.
/streamers disable Admin Stops all alerts in this server. The list is kept, and /streamers channel turns alerts back on.

How self-links and admin adds interact:

  • One self-link per platform per member. Linking a new Twitch account replaces your old one.
  • Self-linking a channel an admin already added attaches it to you, and it stays admin-added, so it keeps alerting without the streamer role.
  • An admin adding a channel someone self-linked makes it admin-added. With member: it's re-attached to that member; without it, the current owner stays.

Limits, and what they cost

Both APIs are free, and neither lets you pay for more capacity.

Twitch

About 800 requests per minute per app. The bot makes one request per minute for every 100 Twitch channels, so in practice there's no limit.

YouTube: the one to watch

The YouTube Data API allows 10,000 quota units per day per Google Cloud project, resetting at midnight Pacific time. To stay well inside that, the bot:

  • reads each channel's public RSS feed to find new videos. This is free and uses no quota.
  • makes one videos.list call per 50 recent videos to check which are live. That's 1 unit per call.
  • polls every 2 minutes, because the feeds only refresh every few minutes anyway.
  • every 15 minutes, also reads each channel's /live page. This catches streams the feed can't see: 24/7 or long-running ones, and streams buried under newer uploads. The page is free to read, but it's an ordinary web page, so roughly 150–200 KB is downloaded per channel per check. A stream it finds is confirmed through the API (1 unit) before it's announced, and only once.
YouTube channels followed (whole bot) Rough units per day
~10 ~720 (7%)
~50 2,000–3,500
~100 7,000+ (near the limit)

Very busy channels cost more, because each check covers up to their 15 newest videos. Usage is visible under APIs & Services → YouTube Data API v3 → Quotas in Google Cloud. If you run out, YouTube alerts stop until midnight Pacific, Twitch keeps working, and the log shows YouTube refused the request (HTTP 403). Google offers free quota increases on application.

Known gaps

  • The /live page check isn't an official API. It's how 24/7 and long-running YouTube streams are found. If YouTube changes that page, the check quietly finds nothing, and only streams still in the channel's feed (its 15 newest videos, from the last 7 days) are announced. Streams started fresh each time are unaffected either way.
  • A 24/7 stream is announced once, when the bot first sees it, not again each day.
  • Every YouTube upload is announced, Shorts included. There's no filter yet.
  • Live and upload alerts share one channel and one ping role.

Testing it

Point /streamers channel at a private test channel with no ping role, then add a channel that uploads constantly. News channels post every 10–20 minutes:

/streamers add platform:YouTube account:@ABCNews
/streamers add platform:YouTube account:@WION

Expect the first alert within 2–10 minutes of the channel's next upload. Earlier videos are skipped by design. Remove them when you're done with /streamers remove account: and pick them from the suggestions.

To test YouTube live alerts, start a short public live stream on your own channel. Unlisted and private streams don't appear in the feed. For Twitch, self-link or add any channel that's live right now; the alert should arrive within a minute.

If something doesn't post, see Troubleshooting.

Clone this wiki locally