Reference / API groups

twitch.moderation

Moderation: bans, timeouts, warnings, AutoMod, blocked terms, moderators, VIPs and Shield Mode.

Every method of twitch.moderation, with its parameters, what it returns and the token it needs.

checkAutoMod

twitch.moderation.checkAutoMod(params, options?): Promise<AutoModCheckResult[]>

Tells whether AutoMod would let messages through in a channel, without sending them. Twitch limits these checks per channel, from 5 a minute for a regular account to 30 for a partner.

Token: app or user, scope moderation:read.

Parameters

Name	Type	Description
`broadcaster_id`	`string`	Broadcaster whose AutoMod settings and blocked terms apply. Defaults to the user making the call.
`data` required	`readonly AutoModCheckMessage[]`	Messages to check, 1 to 100.

options: Request options for this call: as, token, signal, timeout, retries.

Returns

Promise<AutoModCheckResult[]>

Fields of AutoModCheckResult

Name	Type	Description
`msg_id`	`string`	The ID you gave to the message.
`is_permitted`	`boolean`	`true` when the message would go straight to chat, `false` when it would be held or blocked.

Example

const [result] = await twitch.moderation.checkAutoMod({
  data: [{ msg_id: "1", msg_text: "Hello chat" }],
});
if (!result?.is_permitted) console.log("AutoMod would hold this message");

Twitch reference

manageAutoModMessage

twitch.moderation.manageAutoModMessage(params, options?): Promise<void>

Approves or denies a message that AutoMod is holding for review.

Token: app or user, scope moderator:manage:automod.

Parameters

Name	Type	Description
`user_id`	`string`	Moderator who takes the decision. Defaults to the user making the call.
`msg_id` required	`string`	ID of the held message.
`action` required	`"ALLOW" \| "DENY"`	`"ALLOW"` releases the message to chat, `"DENY"` discards it.

options: Request options for this call: as, token, signal, timeout, retries.

Returns

Promise<void>

Example

await twitch.moderation.manageAutoModMessage({ msg_id: "836013710", action: "ALLOW" });

Twitch reference

autoModSettings

twitch.moderation.autoModSettings(params, options?): Promise<AutoModSettings>

Gets the AutoMod levels of a channel.

Token: app or user, scope moderator:read:automod_settings or moderator:manage:automod_settings.

Parameters

Name	Type	Description
`broadcaster_id` required	`string`	Broadcaster whose settings to read.
`moderator_id`	`string`	The broadcaster or one of their moderators. Defaults to the user making the call.

options: Request options for this call: as, token, signal, timeout, retries.

Returns

Promise<AutoModSettings>

Fields of AutoModSettings

Name	Type	Description
`broadcaster_id`	`string`	ID of the broadcaster.
`moderator_id`	`string`	ID of the moderator who made the call.
`overall_level`	`number \| null`	Overall level, 0 to 4. `null` when the categories were set one by one.
`disability`	`number`	Level for discrimination against disability.
`aggression`	`number`	Level for aggressive hostility.
`sexuality_sex_or_gender`	`number`	Level for discrimination based on sexuality, sex or gender.
`misogyny`	`number`	Level for discrimination against women.
`bullying`	`number`	Level for name calling and insults.
`swearing`	`number`	Level for profanity.
`race_ethnicity_or_religion`	`number`	Level for racial, ethnic or religious discrimination.
`sex_based_terms`	`number`	Level for sexual content.

Example

const settings = await twitch.moderation.autoModSettings({ broadcaster_id: "141981764" });
console.log(settings.overall_level);

Twitch reference

updateAutoModSettings

twitch.moderation.updateAutoModSettings(params, options?): Promise<AutoModSettings>

Replaces the AutoMod levels of a channel. This overwrites everything: a category you leave out goes back to 0, so send all the levels you want to keep.

Token: app or user, scope moderator:manage:automod_settings.

Parameters

Name	Type	Description
`broadcaster_id` required	`string`	Broadcaster whose settings to change.
`moderator_id`	`string`	The broadcaster or one of their moderators. Defaults to the user making the call.
`overall_level`	`number`	Overall level, 0 to 4. Twitch derives every category level from it.
`disability`	`number`	Level for discrimination against disability.
`aggression`	`number`	Level for aggressive hostility.
`sexuality_sex_or_gender`	`number`	Level for discrimination based on sexuality, sex or gender.
`misogyny`	`number`	Level for discrimination against women.
`bullying`	`number`	Level for name calling and insults.
`swearing`	`number`	Level for profanity.
`race_ethnicity_or_religion`	`number`	Level for racial, ethnic or religious discrimination.
`sex_based_terms`	`number`	Level for sexual content.

options: Request options for this call: as, token, signal, timeout, retries.

Returns

Promise<AutoModSettings>

Fields of AutoModSettings

Name	Type	Description
`broadcaster_id`	`string`	ID of the broadcaster.
`moderator_id`	`string`	ID of the moderator who made the call.
`overall_level`	`number \| null`	Overall level, 0 to 4. `null` when the categories were set one by one.
`disability`	`number`	Level for discrimination against disability.
`aggression`	`number`	Level for aggressive hostility.
`sexuality_sex_or_gender`	`number`	Level for discrimination based on sexuality, sex or gender.
`misogyny`	`number`	Level for discrimination against women.
`bullying`	`number`	Level for name calling and insults.
`swearing`	`number`	Level for profanity.
`race_ethnicity_or_religion`	`number`	Level for racial, ethnic or religious discrimination.
`sex_based_terms`	`number`	Level for sexual content.

Example

await twitch.moderation.updateAutoModSettings({ broadcaster_id: "141981764", overall_level: 3 });
await twitch.moderation.updateAutoModSettings({ broadcaster_id: "141981764", swearing: 2, bullying: 4 });

Twitch reference

bans

twitch.moderation.bans(params?, options?): Paginator<BannedUser>

Lists the users who are banned or timed out in a channel.

Token: app or user, scope moderation:read or moderator:manage:banned_users.

Parameters

Name	Type	Description
`broadcaster_id`	`string`	Broadcaster whose bans to list. Defaults to the user making the call.
`user_id`	`string \| readonly string[]`	Only these users, when they are banned or timed out. Up to 100 IDs.
`first`	`number`	Items per page, 1 to 100. Twitch defaults to 20.
`after`	`string`	Cursor of the next page.
`before`	`string`	Cursor of the previous page.

options: Request options for this call: as, token, signal, timeout, retries.

Returns

Paginator<BannedUser>

Fields of BannedUser

Name	Type	Description
`user_id`	`string`	ID of the banned user.
`user_login`	`string`	Login name of the banned user.
`user_name`	`string`	Display name of the banned user.
`expires_at`	`string`	When the timeout ends, as an RFC 3339 timestamp. An empty string for a permanent ban.
`created_at`	`string`	When the ban or timeout was set, as an RFC 3339 timestamp.
`reason`	`string`	Reason given by the moderator. An empty string when there is none.
`moderator_id`	`string`	ID of the moderator who set the ban or timeout.
`moderator_login`	`string`	Login name of that moderator.
`moderator_name`	`string`	Display name of that moderator.

Example

for await (const banned of twitch.moderation.bans()) {
  console.log(banned.user_login, banned.expires_at || "permanent");
}

Twitch reference

ban

twitch.moderation.ban(params, options?): Promise<UserBan>

Bans a user from a channel’s chat. A timeout is a ban with a duration: give the number of seconds and the user is let back in afterwards. Calling it again on a timed out user changes the duration or turns the timeout into a ban, but a banned user has to be unbanned before a timeout can be set.

Token: app or user, scope moderator:manage:banned_users.

Parameters

Name	Type	Description
`broadcaster_id` required	`string`	Broadcaster whose chat the user is removed from.
`moderator_id`	`string`	The broadcaster or one of their moderators. Defaults to the user making the call.
`user_id` required	`string`	ID of the user to ban or time out.
`duration`	`number`	Length of the timeout in seconds, 1 to 1209600 (two weeks). Leave it out for a permanent ban.
`reason`	`string`	Reason shown to the user and the other moderators, 500 characters at most.

options: Request options for this call: as, token, signal, timeout, retries.

Returns

Promise<UserBan>

Fields of UserBan

Name	Type	Description
`broadcaster_id`	`string`	ID of the broadcaster whose chat the user was removed from.
`moderator_id`	`string`	ID of the moderator who set it.
`user_id`	`string`	ID of the banned user.
`created_at`	`string`	When it was set, as an RFC 3339 timestamp.
`end_time`	`string \| null`	When the timeout ends, as an RFC 3339 timestamp. `null` for a permanent ban.

Example

await twitch.moderation.ban({ broadcaster_id: "141981764", user_id: "9876", reason: "Spam" });
const timeout = await twitch.moderation.ban({ broadcaster_id: "141981764", user_id: "9876", duration: 600 });
console.log(timeout.end_time);

Twitch reference

unban

twitch.moderation.unban(params, options?): Promise<void>

Lifts the ban or the timeout of a user.

Token: app or user, scope moderator:manage:banned_users.

Parameters

Name	Type	Description
`broadcaster_id` required	`string`	Broadcaster whose chat the user is banned from.
`moderator_id`	`string`	The broadcaster or one of their moderators. Defaults to the user making the call.
`user_id` required	`string`	ID of the user to unban.

options: Request options for this call: as, token, signal, timeout, retries.

Returns

Promise<void>

Example

await twitch.moderation.unban({ broadcaster_id: "141981764", user_id: "9876" });

Twitch reference

unbanRequests

twitch.moderation.unbanRequests(params, options?): Paginator<UnbanRequest>

Lists the unban requests of a channel that are in a given state.

Token: user, scope moderator:read:unban_requests or moderator:manage:unban_requests.

Parameters

Name	Type	Description
`broadcaster_id` required	`string`	Broadcaster whose channel received the requests.
`moderator_id`	`string`	The broadcaster or one of their moderators. Defaults to the user making the call.
`status` required	`UnbanRequestStatus`	Only requests in this state.
`user_id`	`string`	Only requests written by this user.
`first`	`number`	Items per page.
`after`	`string`	Cursor of the next page.

options: Request options for this call: as, token, signal, timeout, retries.

Returns

Paginator<UnbanRequest>

Fields of UnbanRequest

Name	Type	Description
`id`	`string`	ID of the request.
`broadcaster_id`	`string`	ID of the broadcaster who received the request.
`broadcaster_login`	`string`	Login name of the broadcaster.
`broadcaster_name`	`string`	Display name of the broadcaster.
`moderator_id`	`string`	ID of the moderator who approved or denied the request.
`moderator_login`	`string`	Login name of that moderator.
`moderator_name`	`string`	Display name of that moderator.
`user_id`	`string`	ID of the banned user who wrote the request.
`user_login`	`string`	Login name of that user.
`user_name`	`string`	Display name of that user.
`text`	`string`	Message written by the user.
`status`	`UnbanRequestStatus`	Where the request stands.
`created_at`	`string`	When the request was sent, as an RFC 3339 timestamp.
`resolved_at`	`string \| null`	When the request was approved or denied, as an RFC 3339 timestamp. `null` while it is open.
`resolution_text`	`string \| null`	Answer written by the moderator. `null` while the request is open.

Example

const pending = await twitch.moderation.unbanRequests({ broadcaster_id: "141981764", status: "pending" }).all();

Twitch reference

resolveUnbanRequest

twitch.moderation.resolveUnbanRequest(params, options?): Promise<UnbanRequest>

Approves or denies an unban request. Approving it unbans the user.

Token: user, scope moderator:manage:unban_requests.

Parameters

Name	Type	Description
`broadcaster_id` required	`string`	Broadcaster whose channel received the request.
`moderator_id`	`string`	The broadcaster or one of their moderators. Defaults to the user making the call.
`unban_request_id` required	`string`	ID of the request to resolve.
`status` required	`"approved" \| "denied"`	The decision.
`resolution_text`	`string`	Answer shown to the user, 500 characters at most.

options: Request options for this call: as, token, signal, timeout, retries.

Returns

Promise<UnbanRequest>

Fields of UnbanRequest

Name	Type	Description
`id`	`string`	ID of the request.
`broadcaster_id`	`string`	ID of the broadcaster who received the request.
`broadcaster_login`	`string`	Login name of the broadcaster.
`broadcaster_name`	`string`	Display name of the broadcaster.
`moderator_id`	`string`	ID of the moderator who approved or denied the request.
`moderator_login`	`string`	Login name of that moderator.
`moderator_name`	`string`	Display name of that moderator.
`user_id`	`string`	ID of the banned user who wrote the request.
`user_login`	`string`	Login name of that user.
`user_name`	`string`	Display name of that user.
`text`	`string`	Message written by the user.
`status`	`UnbanRequestStatus`	Where the request stands.
`created_at`	`string`	When the request was sent, as an RFC 3339 timestamp.
`resolved_at`	`string \| null`	When the request was approved or denied, as an RFC 3339 timestamp. `null` while it is open.
`resolution_text`	`string \| null`	Answer written by the moderator. `null` while the request is open.

Example

const request = await twitch.moderation.resolveUnbanRequest({
  broadcaster_id: "141981764",
  unban_request_id: "92af127c-7326-4483-a52b-b0da0be61c01",
  status: "approved",
  resolution_text: "Welcome back.",
});

Twitch reference

blockedTerms

twitch.moderation.blockedTerms(params, options?): Paginator<BlockedTerm>

Lists the blocked terms of a channel, newest first. Private terms are not included.

Token: app or user, scope moderator:read:blocked_terms or moderator:manage:blocked_terms.

Parameters

Name	Type	Description
`broadcaster_id` required	`string`	Broadcaster who owns the list.
`moderator_id`	`string`	The broadcaster or one of their moderators. Defaults to the user making the call.
`first`	`number`	Items per page, 1 to 100. Twitch defaults to 20.
`after`	`string`	Cursor of the next page.

options: Request options for this call: as, token, signal, timeout, retries.

Returns

Paginator<BlockedTerm>

Fields of BlockedTerm

Name	Type	Description
`broadcaster_id`	`string`	ID of the broadcaster who owns the list.
`moderator_id`	`string`	ID of the moderator who blocked the term.
`id`	`string`	ID of the blocked term.
`text`	`string`	The blocked word or phrase.
`created_at`	`string`	When the term was blocked, as an RFC 3339 timestamp.
`updated_at`	`string`	When the term last changed, as an RFC 3339 timestamp. Moves each time AutoMod denies it again.
`expires_at`	`string \| null`	When the block ends, as an RFC 3339 timestamp. `null` for a term added by hand or blocked for good by AutoMod.

Example

const terms = await twitch.moderation.blockedTerms({ broadcaster_id: "141981764" }).all();

Twitch reference

addBlockedTerm

twitch.moderation.addBlockedTerm(params, options?): Promise<BlockedTerm>

Blocks a word or phrase in a channel’s chat. When the term is already blocked, the existing entry is returned.

Token: app or user, scope moderator:manage:blocked_terms.

Parameters

Name	Type	Description
`broadcaster_id` required	`string`	Broadcaster who owns the list.
`moderator_id`	`string`	The broadcaster or one of their moderators. Defaults to the user making the call.
`text` required	`string`	Word or phrase to block, 2 to 500 characters. A `` at the start or the end of a word works as a wildcard, as in `"foo"`.

options: Request options for this call: as, token, signal, timeout, retries.

Returns

Promise<BlockedTerm>

Fields of BlockedTerm

Name	Type	Description
`broadcaster_id`	`string`	ID of the broadcaster who owns the list.
`moderator_id`	`string`	ID of the moderator who blocked the term.
`id`	`string`	ID of the blocked term.
`text`	`string`	The blocked word or phrase.
`created_at`	`string`	When the term was blocked, as an RFC 3339 timestamp.
`updated_at`	`string`	When the term last changed, as an RFC 3339 timestamp. Moves each time AutoMod denies it again.
`expires_at`	`string \| null`	When the block ends, as an RFC 3339 timestamp. `null` for a term added by hand or blocked for good by AutoMod.

Example

const term = await twitch.moderation.addBlockedTerm({ broadcaster_id: "141981764", text: "spoil*" });

Twitch reference

removeBlockedTerm

twitch.moderation.removeBlockedTerm(params, options?): Promise<void>

Removes a term from a channel’s blocked terms. An ID that does not exist is not an error.

Token: app or user, scope moderator:manage:blocked_terms.

Parameters

Name	Type	Description
`broadcaster_id` required	`string`	Broadcaster who owns the list.
`moderator_id`	`string`	The broadcaster or one of their moderators. Defaults to the user making the call.
`id` required	`string`	ID of the blocked term to remove.

options: Request options for this call: as, token, signal, timeout, retries.

Returns

Promise<void>

Example

await twitch.moderation.removeBlockedTerm({ broadcaster_id: "141981764", id: term.id });

Twitch reference

deleteMessages

twitch.moderation.deleteMessages(params, options?): Promise<void>

Removes one message from a channel’s chat, or every message when no message_id is given.

Token: app or user, scope moderator:manage:chat_messages.

Parameters

Name	Type	Description
`broadcaster_id` required	`string`	Broadcaster who owns the chat room.
`moderator_id`	`string`	The broadcaster or one of their moderators. Defaults to the user making the call.
`message_id`	`string`	ID of the message to remove. It must be less than 6 hours old and written by neither the broadcaster nor a moderator. Leave it out to clear the chat.

options: Request options for this call: as, token, signal, timeout, retries.

Returns

Promise<void>

Example

await twitch.moderation.deleteMessages({ broadcaster_id: "141981764", message_id: "abc-123-def" });
await twitch.moderation.deleteMessages({ broadcaster_id: "141981764" });

Twitch reference

moderatedChannels

twitch.moderation.moderatedChannels(params?, options?): Paginator<ModeratedChannel>

Lists the channels in which a user is a moderator.

Token: app or user, scope user:read:moderated_channels.

Parameters

Name	Type	Description
`user_id`	`string`	User whose moderated channels to list. Defaults to the user making the call.
`first`	`number`	Items per page, 1 to 100. Twitch defaults to 20.
`after`	`string`	Cursor of the next page.

options: Request options for this call: as, token, signal, timeout, retries.

Returns

Paginator<ModeratedChannel>

Fields of ModeratedChannel

Name	Type	Description
`broadcaster_id`	`string`	ID of the channel’s broadcaster.
`broadcaster_login`	`string`	Login name of the broadcaster.
`broadcaster_name`	`string`	Display name of the broadcaster.

Example

for await (const channel of twitch.moderation.moderatedChannels()) {
  console.log(channel.broadcaster_login);
}

Twitch reference

moderators

twitch.moderation.moderators(params?, options?): Paginator<ChannelModerator>

Lists the moderators of a channel.

Token: user, scope moderation:read or channel:manage:moderators.

Parameters

Name	Type	Description
`broadcaster_id`	`string`	Broadcaster whose moderators to list. Defaults to the user making the call.
`user_id`	`string \| readonly string[]`	Only these users, when they are moderators. Up to 100 IDs.
`first`	`number`	Items per page, 1 to 100. Twitch defaults to 20.
`after`	`string`	Cursor of the next page.

options: Request options for this call: as, token, signal, timeout, retries.

Returns

Paginator<ChannelModerator>

Fields of ChannelModerator

Name	Type	Description
`user_id`	`string`	ID of the moderator.
`user_login`	`string`	Login name of the moderator.
`user_name`	`string`	Display name of the moderator.

Example

const mods = await twitch.moderation.moderators().all();

Twitch reference

addModerator

twitch.moderation.addModerator(params, options?): Promise<void>

Makes a user a moderator of the channel. A VIP has to lose that status first. Twitch allows 10 additions per 10 seconds.

Token: user, scope channel:manage:moderators.

Parameters

Name	Type	Description
`broadcaster_id`	`string`	Broadcaster who owns the chat room. Defaults to the user making the call.
`user_id` required	`string`	ID of the user to make a moderator.

options: Request options for this call: as, token, signal, timeout, retries.

Returns

Promise<void>

Example

await twitch.moderation.addModerator({ user_id: "9876" });

Twitch reference

removeModerator

twitch.moderation.removeModerator(params, options?): Promise<void>

Takes the moderator role away from a user. Twitch allows 10 removals per 10 seconds.

Token: user, scope channel:manage:moderators.

Parameters

Name	Type	Description
`broadcaster_id`	`string`	Broadcaster who owns the chat room. Defaults to the user making the call.
`user_id` required	`string`	ID of the moderator to remove.

options: Request options for this call: as, token, signal, timeout, retries.

Returns

Promise<void>

Example

await twitch.moderation.removeModerator({ user_id: "9876" });

Twitch reference

vips

twitch.moderation.vips(params?, options?): Paginator<ChannelVip>

Lists the VIPs of a channel.

Token: user, scope channel:read:vips or channel:manage:vips.

Parameters

Name	Type	Description
`broadcaster_id`	`string`	Broadcaster whose VIPs to list. Defaults to the user making the call.
`user_id`	`string \| readonly string[]`	Only these users, when they are VIPs. Up to 100 IDs.
`first`	`number`	Items per page, 1 to 100. Twitch defaults to 20.
`after`	`string`	Cursor of the next page.

options: Request options for this call: as, token, signal, timeout, retries.

Returns

Paginator<ChannelVip>

Fields of ChannelVip

Name	Type	Description
`user_id`	`string`	ID of the VIP.
`user_name`	`string`	Display name of the VIP.
`user_login`	`string`	Login name of the VIP.

Example

const vips = await twitch.moderation.vips().all();

Twitch reference

addVip

twitch.moderation.addVip(params, options?): Promise<void>

Makes a user a VIP of the channel. A moderator has to lose that role first, and the channel needs a free VIP slot. Twitch allows 10 additions per 10 seconds.

Token: user, scope channel:manage:vips.

Parameters

Name	Type	Description
`broadcaster_id`	`string`	Broadcaster who grants the status. Defaults to the user making the call.
`user_id` required	`string`	ID of the user to make a VIP.

options: Request options for this call: as, token, signal, timeout, retries.

Returns

Promise<void>

Example

await twitch.moderation.addVip({ user_id: "9876" });

Twitch reference

removeVip

twitch.moderation.removeVip(params, options?): Promise<void>

Takes the VIP status away from a user. A VIP can also give up their own status: pass the channel in broadcaster_id and make the call as that VIP. Twitch allows 10 removals per 10 seconds.

Token: user, scope channel:manage:vips.

Parameters

Name	Type	Description
`broadcaster_id`	`string`	Broadcaster of the channel where the user is a VIP. Defaults to the user making the call.
`user_id` required	`string`	ID of the VIP to remove.

options: Request options for this call: as, token, signal, timeout, retries.

Returns

Promise<void>

Example

await twitch.moderation.removeVip({ user_id: "9876" });
await twitch.moderation.removeVip({ broadcaster_id: "141981764", user_id: "9876" }, { as: "9876" });

Twitch reference

updateShieldMode

twitch.moderation.updateShieldMode(params, options?): Promise<ShieldModeStatus>

Turns Shield Mode on or off in a channel. While it is on, the stricter chat rules the broadcaster prepared for it apply.

Token: app or user, scope moderator:manage:shield_mode.

Parameters

Name	Type	Description
`broadcaster_id` required	`string`	Broadcaster whose Shield Mode to switch.
`moderator_id`	`string`	The broadcaster or one of their moderators. Defaults to the user making the call.
`is_active` required	`boolean`	`true` turns Shield Mode on, `false` turns it off.

options: Request options for this call: as, token, signal, timeout, retries.

Returns

Promise<ShieldModeStatus>

Fields of ShieldModeStatus

Name	Type	Description
`is_active`	`boolean`	Whether Shield Mode is on.
`moderator_id`	`string`	ID of the moderator who last turned it on. An empty string when it was never on.
`moderator_login`	`string`	Login name of that moderator. An empty string when it was never on.
`moderator_name`	`string`	Display name of that moderator. An empty string when it was never on.
`last_activated_at`	`string`	When it was last turned on, as an RFC 3339 timestamp. An empty string when it was never on.

Example

const status = await twitch.moderation.updateShieldMode({ broadcaster_id: "141981764", is_active: true });

Twitch reference

shieldMode

twitch.moderation.shieldMode(params, options?): Promise<ShieldModeStatus>

Tells whether Shield Mode is on in a channel and who turned it on last.

Token: app or user, scope moderator:read:shield_mode or moderator:manage:shield_mode.

Parameters

Name	Type	Description
`broadcaster_id` required	`string`	Broadcaster whose Shield Mode to read.
`moderator_id`	`string`	The broadcaster or one of their moderators. Defaults to the user making the call.

options: Request options for this call: as, token, signal, timeout, retries.

Returns

Promise<ShieldModeStatus>

Fields of ShieldModeStatus

Name	Type	Description
`is_active`	`boolean`	Whether Shield Mode is on.
`moderator_id`	`string`	ID of the moderator who last turned it on. An empty string when it was never on.
`moderator_login`	`string`	Login name of that moderator. An empty string when it was never on.
`moderator_name`	`string`	Display name of that moderator. An empty string when it was never on.
`last_activated_at`	`string`	When it was last turned on, as an RFC 3339 timestamp. An empty string when it was never on.

Example

const { is_active } = await twitch.moderation.shieldMode({ broadcaster_id: "141981764" });

Twitch reference

warn

twitch.moderation.warn(params, options?): Promise<UserWarning>

Sends a warning to a chat user, who cannot chat again until they acknowledge it. A new warning replaces a pending one.

Token: app or user, scope moderator:manage:warnings.

Parameters

Name	Type	Description
`broadcaster_id` required	`string`	Broadcaster of the channel the warning applies to.
`moderator_id`	`string`	The broadcaster or one of their moderators. Defaults to the user making the call.
`user_id` required	`string`	ID of the user to warn.
`reason` required	`string`	Why the user is warned, 500 characters at most.

options: Request options for this call: as, token, signal, timeout, retries.

Returns

Promise<UserWarning>

Fields of UserWarning

Name	Type	Description
`broadcaster_id`	`string`	ID of the broadcaster of the channel the warning applies to.
`user_id`	`string`	ID of the warned user.
`moderator_id`	`string`	ID of the moderator who sent the warning.
`reason`	`string`	Reason given with the warning.

Example

await twitch.moderation.warn({ broadcaster_id: "141981764", user_id: "9876", reason: "Keep it friendly." });

Twitch reference

addSuspiciousStatus

twitch.moderation.addSuspiciousStatus(params, options?): Promise<SuspiciousUser>

Flags a chatter as suspicious in a channel, either to keep an eye on them or to restrict their messages.

Token: app or user, scope moderator:manage:suspicious_users.

Parameters

Name	Type	Description
`broadcaster_id` required	`string`	Broadcaster of the channel the status applies to.
`moderator_id`	`string`	Moderator who sets the status. Defaults to the user making the call.
`user_id` required	`string`	ID of the chatter to flag.
`status` required	`"ACTIVE_MONITORING" \| "RESTRICTED"`	`"ACTIVE_MONITORING"` watches the user, `"RESTRICTED"` also hides their messages from chat.

options: Request options for this call: as, token, signal, timeout, retries.

Returns

Promise<SuspiciousUser>

Fields of SuspiciousUser

Name	Type	Description
`user_id`	`string`	ID of the chatter.
`broadcaster_id`	`string`	ID of the broadcaster of the channel.
`moderator_id`	`string`	ID of the moderator who last changed the status.
`updated_at`	`string`	When the status last changed, as an RFC 3339 timestamp.
`status`	`SuspiciousUserStatus`	Current treatment. `"NO_TREATMENT"` once the status has been removed.
`types`	`SuspiciousUserType[]`	Reasons the user is considered suspicious.

Example

const flagged = await twitch.moderation.addSuspiciousStatus({
  broadcaster_id: "141981764",
  user_id: "9876",
  status: "RESTRICTED",
});

Twitch reference

removeSuspiciousStatus

twitch.moderation.removeSuspiciousStatus(params, options?): Promise<SuspiciousUser>

Clears the suspicious status of a chatter in a channel.

Token: app or user, scope moderator:manage:suspicious_users.

Parameters

Name	Type	Description
`broadcaster_id` required	`string`	Broadcaster of the channel the status applies to.
`moderator_id`	`string`	Moderator who removes the status. Defaults to the user making the call.
`user_id` required	`string`	ID of the chatter to clear.

options: Request options for this call: as, token, signal, timeout, retries.

Returns

Promise<SuspiciousUser>

Fields of SuspiciousUser

Name	Type	Description
`user_id`	`string`	ID of the chatter.
`broadcaster_id`	`string`	ID of the broadcaster of the channel.
`moderator_id`	`string`	ID of the moderator who last changed the status.
`updated_at`	`string`	When the status last changed, as an RFC 3339 timestamp.
`status`	`SuspiciousUserStatus`	Current treatment. `"NO_TREATMENT"` once the status has been removed.
`types`	`SuspiciousUserType[]`	Reasons the user is considered suspicious.

Example

await twitch.moderation.removeSuspiciousStatus({ broadcaster_id: "141981764", user_id: "9876" });

Twitch reference