Spotify integration

Connecting Spotify unlocks two layers of features:

• Read-only display commands — !song, !playlist, !nexttracks.
• Chat-driven song requests — !sr, plus mod-only playback control (!skip, !playsong, !stopsong) and a per-channel blacklist that prevents unwanted artists or keywords from making it onto the playlist.

Connecting

1. Open /settings/spotify.
2. Click Connect Spotify.
3. You're sent to Spotify's authorization page — approve the request.
4. You're redirected back. The page now shows Connected with the Spotify account name.

The OAuth scopes AveloBot 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 your stored connection is missing any of these (e.g. the bot was upgraded after you connected), the settings page shows an explicit warning and a Reconnect button — Spotify's refresh flow doesn't grant scopes added later, so a manual reconnect is the only way to update.

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 rejects writes to non-owned playlists, so !sr would 403 if this is your active playlist. Pick a playlist with the Yours chip, or create a new one in Spotify and import it.

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

Song request settings

/settings/spotify carries a Song Requests card with all per-channel options. Every field auto-saves on change — no Save button needed. A confirmation toast appears for each change.

Setting	Default	What it does
Enable song requests	on	Master switch. When off, !sr replies "Song requests are currently disabled."
Mode	Active playlist	Where requests go — see below.
Max. track length	7 min	Tracks longer than this many seconds are rejected. Empty = no limit. Range 30 s – 30 min.
Block explicit tracks	off	Reject any Spotify track flagged explicit.
Duplicate check	on	Reject a track that's already in the active playlist (playlist mode only).
Max. requests per user per stream	unlimited	Each chatter can successfully request at most this many tracks per stream session. Failed attempts (not found, blocked, etc.) don't count. The counter resets when the channel goes online (Twitch stream.online event). Empty = no limit. Range 1 – 100.

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 enqueues the track in Spotify's player queue (the same queue you'd see in the Spotify app's "Queue" view). Tracks are ephemeral: once they play, they're gone. Requires Spotify to be actively playing on a device — without an active device the queue endpoint returns 404 and the chatter sees "Could not queue track — Spotify is not playing on any device."

Blacklist

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

• Artist blacklist — type the artist name in the dialog and AveloBot resolves it to a canonical Spotify artist via search. The whole artist (including features and collaborations) is blocked. You can also paste a Spotify URL (open.spotify.com/artist/…), URI (spotify:artist:…), or bare id — the dialog handles any of those.
• Keyword blacklist — case-insensitive substring 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 "that track is blocked" (with your optional reason in parentheses if you set one). Both blacklist types respect tenant boundaries — your entries don't leak to other channels.

Chat commands

Command	Permission	Behavior
!song (alias !s)	Everyone	Posts the currently playing track.
!playlist (alias !pl)	Everyone	Shows the currently active saved playlist with a Spotify link.
!sr <input> (alias !songrequest)	Everyone	Requests a song. Input can be a Spotify track URL, URI, or Artist - Title text. Free-text searches Spotify; if no exact match, retries as a generic search.
!nexttracks (alias !queue)	Everyone	Shows the next 3 tracks. In playlist mode, the next 3 from the active playlist (skipping past the current track if it's in there). In queue mode, the live Spotify player queue.
!skip (alias !next)	Moderator	Skips to the next track.
!playsong (alias !play)	Moderator	Resumes Spotify playback.
!stopsong (aliases !stop, !pause)	Moderator	Pauses Spotify playback.

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

Disconnecting

Click Disconnect on the Spotify settings page. AveloBot deletes its tokens. To fully revoke access, also remove AveloBot at spotify.com/account/apps.

Troubleshooting

• !sr says "the active playlist isn't owned by the streamer's Spotify account" — Pick a playlist with the green Yours chip on the Playlists page, or switch the mode to Spotify queue.
• !sr says "Spotify is not playing on any device" (queue mode) — Open Spotify and start playback on any device.
• Settings page shows "Your Spotify connection is missing the scopes …" — Click Reconnect to grant the new scopes. Required after any AveloBot upgrade that adds new Spotify capabilities.
• !sr says "Spotify connection needs re-authorization" — The stored token can't be refreshed; click Reconnect.