Spotify integration

Connecting Spotify gives streamion.bot access to your Spotify session and enables two groups of features:

• Read-only display commands — !song, !playlist, !nexttracks.
• Chat-driven song requests — !sr, along with moderator-only playback control (!skip, !playsong, !stopsong) and a per-channel blacklist that prevents unwanted artists or keywords from being added to the playlist.

Spotify is one of two music providers streamion.bot supports; the second is YouTube Music. You can have both connected at once, but only the active provider (selected on Settings → Music) receives chat commands at any given time.

Connecting

1. Open /settings/music. The page shows two cards — Spotify and YouTube Music — side by side.
2. On the Spotify card, click Connect Spotify.
3. You are redirected to Spotify's authorization page; approve the request.
4. You are redirected back. The Spotify card now shows Connected along with the account name.
5. If Spotify should be the source for chat commands, select Spotify as the active provider at the top of the page.

The OAuth scopes (the individual permissions Spotify is asked to grant) streamion.bot requests are: user-read-currently-playing, user-read-playback-state, user-modify-playback-state, playlist-read-private, playlist-read-collaborative, playlist-modify-public, playlist-modify-private. If a stored connection is missing any of these (typically because new scopes were added in a later streamion.bot release), the card shows an explicit warning and a Reconnect button. Spotify's automatic token refresh never adds scopes that were granted later, so a manual reconnect is the only way to update the set.

Use your own Spotify app (Pro)

By default, streamion.bot connects Spotify through its own shared Spotify application. With streamion.bot Pro you can instead connect through your own Spotify developer app — useful when the shared app's user list is full, or if you want independent rate-limit capacity. Nothing about the chat commands or song-request behaviour changes; only the underlying Spotify connection does.

Set it up on Settings → Music (Owner / Admin only), in the Custom Spotify app (Pro) section:

1. Create an app in the Spotify Developer Dashboard (or reuse an existing one) and copy its Client ID and Client Secret.
2. In your Spotify app's settings, add the Redirect URI exactly as shown on the streamion.bot page.
3. In the app's User Management, add yourself with the email address of the Spotify account you'll connect. While the app is in development mode, Spotify only lets accounts on this list authorize it — without this entry, connecting fails.
4. Paste the Client ID and Client Secret into streamion.bot and click Save.
5. Click Connect Spotify (or Reconnect) so the connection switches to your app.

The Client Secret is stored encrypted and is never shown again — when editing later, leave it blank to keep the stored one. To go back to the shared app, click Remove and reconnect Spotify afterwards. If your Pro access ends while a custom app is set, your app keeps working until you remove it.

Playlists page

The Playlists page (/playlists) is where you decide which playlist song requests land in.

• Saved playlists (top table) — playlists you've imported from your Spotify library. Exactly one can be Active at a time. Song requests in playlist mode go into the active one.
• Your Spotify playlists (bottom table) — fresh from your Spotify library. Click Refresh to load it.

Each playlist row shows an ownership chip:

• 🟢 Yours — the playlist is owned by your Spotify account. !sr can add tracks to it.
• 🟡 Following / Not yours — you only follow this playlist (e.g. a Spotify-curated or community playlist). Spotify does not allow other users to add tracks to a playlist they do not own, so !sr would be rejected if this is your active playlist. Pick a playlist with the Yours chip instead, or create a new one in Spotify and import it.

Other actions: View tracks, Activate / Deactivate, Delete (removes from streamion.bot, not from Spotify).

Song request settings

/settings/music carries a Song Requests · Spotify card with all per-channel options while Spotify is the active provider and the connection is healthy. Every field auto-saves on change; no Save button is required, and a short confirmation appears for each change.

Modes

• Active playlist — !sr appends the track to the playlist marked Active on the Playlists page. Requires the playlist to be owned by your Spotify account.
• Spotify queue — !sr adds the track to Spotify's player queue (the same queue you'd see in the Spotify app's "Queue" view). Tracks are temporary: once they have played, they are gone. Requires Spotify to be actively playing on a device — without an active device the chatter sees "Could not queue track — no active device."

Channel-point song requests

As an alternative (or addition) to the !sr command, viewers can request songs by redeeming a Twitch channel-point reward. streamion.bot creates and manages the reward for you, and redeemed requests run through the exact same pipeline as !sr — your length cap, explicit filter, duplicate check, per-user limit, and blacklist all apply.

Set it up on Settings → Music (/settings/music), in the Song requests via channel points card:

• Enable channel-point song requests — creates the reward on your channel (and removes it when you turn the feature off).
• Reward name — the reward's title in Twitch's channel-point menu (default Song Request, up to 45 characters).
• Channel-point cost — what viewers pay to redeem it (default 500).

When a viewer redeems it, they type a song name or a track link into the reward's text box. On success the request is added and the redemption is fulfilled; if it fails (no match, blocked, limit reached, …) the redemption is refunded automatically. When you enable the feature, streamion.bot asks whether to also disable !sr so songs can only come via channel points — choose Keep both to leave the chat command working too.

This needs a Twitch permission that was added recently, so reconnect your broadcaster account on the Channel page to grant it — the card shows a reconnect prompt until you do.

Blacklist

/settings/spotify/blacklist lets you block artists or keywords from being requested.

• Artist blacklist — type the artist name in the dialog and streamion.bot looks it up on Spotify to identify the exact artist. The whole artist (including features and collaborations) is blocked. You can also paste a Spotify URL (open.spotify.com/artist/…), URI (spotify:artist:…), or the bare artist ID — the dialog accepts any of those.
• Keyword blacklist — case-insensitive match against the track name and every artist name. Useful for blanket bans like "baby shark" or "christmas".

When !sr blocks a track, the chatter gets "@username that track is blocked" (with your optional reason in parentheses if you set one). Blacklist entries belong to your workspace only — they don't leak to other channels.

Chat commands

All defaults (triggers, aliases, permissions, cooldowns) can be overridden per channel on the Commands page.

Disconnecting

Click Disconnect on the Spotify card on /settings/music. streamion.bot deletes its tokens and removes the stored connection. To fully revoke access on Spotify's side as well, remove streamion.bot at spotify.com/account/apps.

Troubleshooting

• !sr says "The active playlist isn't owned by the streamer, so tracks can't be added to it" — Pick a playlist with the green Yours chip on the Playlists page, or switch the mode to Spotify queue.
• !sr says "no active device" (queue mode) — Open Spotify and start playback on any device.
• Spotify card shows "Missing scopes: …" — Click Reconnect to grant the new scopes. Required after any streamion.bot upgrade that adds new Spotify capabilities.
• !sr says "Spotify connection needs re-authorization" — The stored token can't be refreshed; click Reconnect.