Ads and raids

Timers post on a clock. The things on this page post on an event: an ad break starting, a raid arriving, you going offline. They are the small announcements you would otherwise type yourself while doing three other things.

All of them are Twitch only, because they ride Twitch’s ad, raid and shoutout APIs, and there is no equivalent to point at on Kick or YouTube.

The automatic messages ship off, and their settings page is still being built

Every automatic message on this page is off out of the box, deliberately: a bot that starts talking in your chat because you updated is a bot people turn off.

The honest part: the settings that turn those messages on do not have a page in Pyre yet. The engine is live, the defaults below are the real shipped defaults, and the surface to edit them is still being built.

The commands are a different story and need no waiting. !nextad and !raiders work today, and both have a real row in the Built in commands card with their own On switch and their own Live gate, as do the four !ads verbs below.

Around an ad break

Three independent messages, each with its own on switch and its own text.

Message	Fires	Default text
Upcoming	About a minute before a scheduled break	Heads up, an ad break starts in about a minute.
Start	When the break begins	Ads are running for {durationFS}. Thanks for sticking around, we will be right back.
End	When it finishes	Ads are done, welcome back.

The upcoming message comes from polling your ad schedule once a minute while you are live, and fires when the next break is 60 seconds out or less. Start and end come from Twitch telling Pyre the break began, plus its length.

The duration placeholders

Four ways to write the same number, so the line reads the way you want it to:

Placeholder	30 second break	60 second break	180 second break
{durationS}	30	60	180
{durationM}	0.5	1	3
{durationFS}	30 seconds	60 seconds	180 seconds
{durationFP}	0.5 minutes	1 minute	3 minutes

{durationFS} and {durationFP} handle their own plurals, so 1 second and 1 minute come out right without you writing two versions of the line.

They are ordinary chat messages, not pinned ones

Twitch has no public API Pyre can use to pin a countdown above chat, and the announce endpoint needs a permission Pyre does not ask for. So an ad-timer line is a plain chat message, exactly like a timer. A pinned version waits on Twitch.

!nextad

Anyone can type it, it answers once every 30 seconds per channel, and it reads the same schedule the upcoming message does:

@petra the next ad break is in about 4 minutes. You have pre-roll-free time for the next 2 min.

The pre-roll-free part only appears when Twitch reports one. With nothing scheduled it says no ad break is scheduled right now., and if the schedule cannot be read it says that too rather than guessing.

The !ads verbs

Four more verbs belong to Ad Manager, the feature that moves your ad breaks into downtime. They are the chat version of the buttons on the Stream Manager card, and each of them takes two spellings, so you can type whichever one you remember:

Verb	Also accepts	Who may type it
!ads		Anyone
!adsnow	!ads now	You, and moderators if you allow it
!adshold <minutes>	!ads hold 20	You, and moderators if you allow it
!adsresume	!ads resume	You, and moderators if you allow it

!ads is the status line, and it reads the same ledger the cockpit card does, so the two can never describe your channel differently:

@petra Next ad break in 4 min. 3 of 9 ad minutes banked this hour. 2 snoozes left.

Each part swaps for the truth of the moment. A live hold outranks everything and reads Ads are held for 12 more minutes. Off air it says You are not live right now, so Twitch has nothing scheduled. With nothing scheduled it says No ad break scheduled right now., and before Pyre has read your schedule at all, Pyre has not read your ad schedule yet. The minutes banked are always there, because they are Pyre’s own count rather than Twitch’s answer.

!adsnow starts a real break. !adshold stops Pyre picking moments for a while, and !adsresume releases it again. The bot confirms each one in a few words: running an ad break now., holding ads for 20 minutes., ad hold released.

!adshold with no number holds for 15 minutes, and the longest a single hold may ask for is 180. A number that is not a duration gets a usage line rather than a silent default, because holding somebody’s ads for a quarter of an hour they did not ask for is worse than saying nothing:

use !adshold <minutes>, for example !adshold 20. Leave the number off and Pyre holds for 15.

If Ad Manager is not armed on your channel, the fire verbs refuse instead of queueing something that would run the moment you did arm it:

Pyre is not managing ads on this channel right now. Arm it on the Ads settings page.

Letting moderators run them

The three fire verbs are yours alone out of the box. On the Ads settings page in Pyre.Stream there is one switch, Moderators may run ads with !adsnow, and Off means only you can start a break from chat. While it is off, a mod who tries gets the sentence that names the switch:

Only the broadcaster can run ads from chat. Turn on "moderators may fire" in Ads settings to change that.

!ads itself is everyone level, and like !nextad it answers at most once every 30 seconds per channel. You and an allowed mod are never throttled: asking twice for your own ad break should not be met with silence.

Even with the switch on, the break is fired with your token

Twitch’s own API takes the broadcaster’s token to start a commercial and nothing else, so there is no such thing as a moderator starting an ad on Twitch’s side. The switch is a Pyre permission: it lets a mod ask, and Pyre acts as you. That is also why this is off by default.

!nextad and Ad Manager are two different features

They sit next to each other on this page and in the same Ads group on the Built in commands card, and they are not the same thing.

!nextad belongs to the ad timer messages above. It reads Twitch’s schedule and answers a question. It changes nothing, it schedules nothing, and it works whether or not Ad Manager exists.

The four !ads verbs belong to Ad Manager, the scheduling half. They read and change what Pyre is doing with your hour.

The switches are separate all the way down: each of the five commands has its own row with its own On switch and its own Live gate, and Ad Manager itself has an arm switch of its own that none of these touch. Turning !nextad off does not turn Ad Manager off, and turning Ad Manager off does not silence !nextad.

Snoozing an ad for a raid

The worst possible moment for an ad break is thirty seconds after a hundred new people arrive. With this on, an incoming raid makes Pyre check your schedule, and if the next break is five minutes out or less it spends one of your snoozes and tells chat:

A raid is here, so I snoozed the next ad break to keep the party going.

Twitch gives you a limited number of snoozes that refill over time. If you have none left, Twitch refuses and nothing happens, which is the right outcome: nothing else in your stream changes.

Shouting out the channels that raid you

An incoming raid can fire Twitch’s own shoutout and a chat line of your own, each on its own switch, so you can have either or both.

The settings, with the defaults they ship with:

Setting	Default	What it does
Minimum viewers	2	Raids smaller than this are ignored
Delay	5 seconds	How long to wait after the raid lands
Twitch shoutout	On	Fires the platform’s own shoutout
Custom message	Off	Posts your line in chat
Allowlist mode	Off	On, only raiders you wrote a message for get shouted out

The default line is:

Go give {username} some love at {url} — they were last streaming {category}.

and you can use any of {username}, {url}, {title}, {category} and {viewers}.

Per raider and per team

You can write a specific message for a specific channel, and a message for a whole Twitch team. Pyre resolves them in that order: a message written for that raider wins, then a message written for a team they are on, then your default line. If you have no team messages at all, Pyre does not ask Twitch about teams, so you pay nothing for a feature you are not using.

Allowlist mode turns the same data into a guest list. With it on, only the raiders who have a message of their own (or a team message) are shouted out at all. It is the setting for a channel that wants shoutouts for its friends and silence for everyone else.

Shoutouts are paced on purpose

Twitch allows two shoutouts a minute and one per target per hour, so Pyre queues them rather than firing them all at once. Three channels raiding together get three shoutouts, about half a minute apart, instead of one shoutout and two errors.

After you raid out, and !raiders

Two more, on the other side of a raid.

The post-raid message fires when you raid somebody else, so the viewers who did not travel know where everyone went. It ships off, and its default is:

We are raiding {username}! Get over to {url} and say hi.

!raiders is a viewer command that thanks everyone who raided you this stream:

@petra thank you to this stream's raiders: alice, bob and carol.

The list is per stream and resets when you go live, so it is a thank-you at the end of a session rather than a running history. With nothing in it, the bot says no raids so far this stream. Like !nextad, it answers once every 30 seconds per channel.

Both commands have a row in the Built in commands card

!nextad and !raiders are ordinary built in commands, listed under the Ads and Raids groups of the Built in commands card with their own On switch and their own Live gate. Turn one off and the bot behaves as though the command does not exist, silently, the same as a disabled custom command. Set its live gate to Off while live and it answers only when you are offline, which for these two is mostly a way to keep them out of a busy stream.

Going offline, and going live again

Two checks bracket your stream. Both ship off, both are Twitch only, and both live with the protection settings rather than here.

Offline lockdown turns Shield Mode on a while after your stream ends, which is the window where a chat with nobody watching it gets found. The delay is yours, from 0 to 3600 seconds, and it starts at five minutes. Going live again before it fires cancels it. It never touches your Shield Mode profile settings, and it never turns Shield back off again.

The go-live check reads your chat settings when you go live and tells you, in your own chat, if something restrictive is still on from last time:

Heads up. Your chat still has followers-only mode and Shield Mode on from before. Turn it off if you did not mean to leave it on.

It looks at followers-only, subscribers-only, emote-only, slow mode and Shield Mode, and it names exactly the ones that are on.

The warning is a warning, never a fix

The go-live check changes nothing. A followers-only chat may be precisely what you meant, and quietly undoing it would be worse than saying nothing. This is also the check that catches the previous feature’s own work: an offline lockdown turns Shield Mode on and nothing turns it off, so without the reminder you could stream to a shielded chat and never know why it was quiet.

Related

• Ad Manager for the feature the four !ads verbs drive.
• Timers for messages on a clock rather than on an event.
• Protection for Shield Mode, lockdowns and the panic button.
• Commands for the Built in commands card, where !nextad and !raiders are listed.