Reference / API groups
twitch.ads
Ads: run commercials, read the ad schedule, snooze the next ad.
Every method of twitch.ads, with its parameters, what it returns and the token it needs.
startCommercial
Section titled “startCommercial”twitch.ads.startCommercial(params, options?): Promise<CommercialStatus>Starts a commercial break on a channel. The broadcaster must be a partner or an affiliate and must be live. With an app token, the broadcaster must have granted the scope to your application.
Token: app or user, scope channel:edit:commercial.
Parameters
Section titled “Parameters”| Name | Type | Description |
|---|---|---|
broadcaster_id | string | Broadcaster who runs the commercial. Defaults to the user making the call. |
length required | number | Wanted length in seconds, 180 at most. The ad that is served can be a little shorter or longer. |
options: Request options for this call: as, token, signal, timeout, retries.
Returns
Section titled “Returns”Promise<CommercialStatus>
Fields of CommercialStatus
| Name | Type | Description |
|---|---|---|
length | number | Length of the commercial that was requested, in seconds. Capped at 180. |
message | string | Tells whether Twitch could serve an ad. Often an empty string. |
retry_after | number | Seconds to wait before another commercial can be started. |
Example
Section titled “Example”const { retry_after } = await twitch.ads.startCommercial({ broadcaster_id: "141981764", length: 60 });schedule
Section titled “schedule”twitch.ads.schedule(params?, options?): Promise<AdSchedule>Gets the ad schedule of a channel: next and last ad, snoozes left and remaining time without pre-rolls. With an app token, the broadcaster must have granted the scope to your application.
Token: app or user, scope channel:read:ads.
Parameters
Section titled “Parameters”| Name | Type | Description |
|---|---|---|
broadcaster_id | string | Broadcaster whose schedule to read. Defaults to the user making the call. |
options: Request options for this call: as, token, signal, timeout, retries.
Returns
Section titled “Returns”Promise<AdSchedule>
Fields of AdSchedule
| Name | Type | Description |
|---|---|---|
snooze_count | number | Number of snoozes the broadcaster has left. |
snooze_refresh_at | AdTimestamp | When the broadcaster gets one more snooze. See {@link AdTimestamp}. |
next_ad_at | AdTimestamp | When the next ad is due. Empty or 0 when none is scheduled or the channel is offline. See {@link AdTimestamp}. |
duration | number | Length of the next ad break, in seconds. |
last_ad_at | AdTimestamp | When the last ad break ran. Empty or 0 when there was none or the channel is offline. See {@link AdTimestamp}. |
preroll_free_time | number | Seconds left without pre-roll ads. 0 when pre-rolls are being shown. |
Example
Section titled “Example”const schedule = await twitch.ads.schedule({ broadcaster_id: "141981764" });console.log(schedule.next_ad_at, schedule.snooze_count);snooze
Section titled “snooze”twitch.ads.snooze(params?, options?): Promise<AdSnooze>Pushes the next automatic mid-roll ad back by five minutes, at the cost of one snooze. With an app token, the broadcaster must have granted the scope to your application.
Token: app or user, scope channel:manage:ads.
Parameters
Section titled “Parameters”| Name | Type | Description |
|---|---|---|
broadcaster_id | string | Broadcaster whose ad to push back. Defaults to the user making the call. |
options: Request options for this call: as, token, signal, timeout, retries.
Returns
Section titled “Returns”Promise<AdSnooze>
Fields of AdSnooze
| Name | Type | Description |
|---|---|---|
snooze_count | number | Number of snoozes the broadcaster has left. |
snooze_refresh_at | AdTimestamp | When the broadcaster gets one more snooze. See {@link AdTimestamp}. |
next_ad_at | AdTimestamp | New time of the next ad. See {@link AdTimestamp}. |
Example
Section titled “Example”const { next_ad_at } = await twitch.ads.snooze({ broadcaster_id: "141981764" });