Bot

Twitch chatbots made easy.

Overview

Properties

Constructor

new Bot(config)

Creates a new bot.

Parameter	Type	Required	Default	Description
config	BotConfig		none	The configuration for the bot.

Events

onAction((event) => { /* ... */ })

Fires when a user sends an action (/me) to a channel.

Parameter	Type	Description
event	MessageEvent	The event object.

onAnnouncement((event) => { /* ... */ })

Fires when a user sends an announcement (/announce) to a channel.

Parameter	Type	Description
event	AnnouncementEvent	The event object.

onAuthenticationFailure((text, retryCount) => { /* ... */ })

Fires when authentication fails.

Parameter	Type	Description
text	string	The message text.
retryCount	number	The number of authentication attempts, including this one, that failed in the current attempt to connect. Resets when authentication succeeds.

onAuthenticationSuccess(() => { /* ... */ })

Fires when authentication succeeds.

onBan((event) => { /* ... */ })

Fires when a user is permanently banned from a channel.

Parameter	Type	Description
event	BanEvent	The event object.

onBitsBadgeUpgrade((event) => { /* ... */ })

Fires when a user upgrades their bits badge in a channel.

Parameter	Type	Description
event	BitsBadgeUpgradeEvent	The event object.

onChatClear((event) => { /* ... */ })

Fires when the chat of a channel is cleared.

Parameter	Type	Description
event	ChatClearEvent	The event object.

onCommunityPayForward((event) => { /* ... */ })

Fires when a user pays forward a subscription that was gifted to them to the community.

Parameter	Type	Description
event	CommunityPayForwardEvent	The event object.

onCommunitySub((event) => { /* ... */ })

Fires when a user gifts random subscriptions to the community of a channel.

Community subs also fire multiple onSubGift events. To prevent alert spam, check the example on how to handle sub gift spam.

Parameter	Type	Description
event	CommunitySubEvent	The event object.

onConnect(() => { /* ... */ })

Fires when the client successfully connects to the chat server.

onDisconnect((manually, reason) => { /* ... */ })

Fires when the client disconnects from the chat server.

Parameter	Type	Description
manually	boolean	Whether the disconnect was requested by the user.
reason	Error	The error that caused the disconnect, or `undefined` if there was no error.

onEmoteOnlyToggle((event) => { /* ... */ })

Fires when emote-only mode is toggled in a channel.

Parameter	Type	Description
event	EmoteOnlyToggleEvent	The event object.

onFollowersOnlyToggle((event) => { /* ... */ })

Fires when followers-only mode is toggled in a channel.

Parameter	Type	Description
event	FollowersOnlyToggleEvent	The event object.

onGiftPaidUpgrade((event) => { /* ... */ })

Fires when a user upgrades their gift subscription to a paid subscription in a channel.

Parameter	Type	Description
event	GiftPaidUpgradeEvent	The event object.

onJoin((event) => { /* ... */ })

Fires when a user joins a channel.

The join/leave events are cached by the Twitch chat server and will be batched and sent every 30-60 seconds.

Please note that if you have not enabled the requestMembershipEvents option or the channel has more than 1000 connected chatters, this will only react to your own joins.

Parameter	Type	Description
event	JoinEvent	The event object.

onJoinFailure((event) => { /* ... */ })

Fires when you fail to join a channel.

Parameter	Type	Description
event	JoinFailureEvent	The event object.

onLeave((event) => { /* ... */ })

Fires when a user leaves ("parts") a channel.

The join/leave events are cached by the Twitch chat server and will be batched and sent every 30-60 seconds.

Please note that if you have not enabled the requestMembershipEvents option or the channel has more than 1000 connected chatters, this will only react to your own leaves.

Parameter	Type	Description
event	LeaveEvent	The event object.

onMessage((event) => { /* ... */ })

Fires when a user sends a message to a channel.

Parameter	Type	Description
event	MessageEvent	The event object.

onMessageFailed((channel, reason) => { /* ... */ })

Fires when sending a message fails.

Parameter	Type	Description
channel	string	The channel that rejected the message.
reason	string	The reason for the failure, e.g. you're banned (msg_banned)

onMessageRemove((event) => { /* ... */ })

Fires when a single message is removed from a channel.

Parameter	Type	Description
event	MessageRemoveEvent	The event object.

onPrimePaidUpgrade((event) => { /* ... */ })

Fires when a user upgrades their Prime subscription to a paid subscription in a channel.

Parameter	Type	Description
event	PrimePaidUpgradeEvent	The event object.

onRaid((event) => { /* ... */ })

Fires when a user raids a channel.

Parameter	Type	Description
event	RaidEvent	The event object.

onRaidCancel((event) => { /* ... */ })

Fires when a user cancels a raid.

Parameter	Type	Description
event	RaidCancelEvent	The event object.

onResub((event) => { /* ... */ })

Fires when a user resubscribes to a channel.

Parameter	Type	Description
event	SubEvent	The event object.

onSlowModeToggle((event) => { /* ... */ })

Fires when slow mode is toggled in a channel.

Parameter	Type	Description
event	SlowModeToggleEvent	The event object.

onStandardPayForward((event) => { /* ... */ })

Fires when a user pays forward a subscription that was gifted to them to a specific user.

Parameter	Type	Description
event	StandardPayForwardEvent	The event object.

onSub((event) => { /* ... */ })

Fires when a user subscribes to a channel.

Parameter	Type	Description
event	SubEvent	The event object.

onSubGift((event) => { /* ... */ })

Fires when a user gifts a subscription to a channel to another user.

Community subs also fire multiple onSubGift events. To prevent alert spam, check the example on how to handle sub gift spam.

Parameter	Type	Description
event	SubGiftEvent	The event object.

onSubsOnlyToggle((event) => { /* ... */ })

Fires when sub only mode is toggled in a channel.

Parameter	Type	Description
event	SubsOnlyToggleEvent	The event object.

onTimeout((event) => { /* ... */ })

Fires when a user is timed out from a channel.

Parameter	Type	Description
event	BanEvent	The event object.

onTokenFetchFailure((error) => { /* ... */ })

Fires when fetching a token fails.

Parameter	Type	Description
error	Error	The error that was thrown.

onUniqueChatToggle((event) => { /* ... */ })

Fires when unique chat mode is toggled in a channel.

Parameter	Type	Description
event	UniqueChatToggleEvent	The event object.

onWhisper((event) => { /* ... */ })

Fires when receiving a whisper from another user.

Parameter	Type	Description
event	WhisperEvent	The event object.

Properties

api

Type: ApiClient

Direct access to the underlying API client. Use at your own risk.

chat

Type: ChatClient

Direct access to the underlying chat client. Use at your own risk.

Parameter	Type	Required	Default	Description
channelName	string		none	The name of the channel to send the action to.
text	string		none	The text to send.

Parameter	Type	Required	Default	Description
channel	UserIdResolvable A user ID or a user or channel object. This is not a user name. Please use HelixUserApi#getUserByName to fetch a user object by name. Aliased type: string \| number \| UserIdResolvableType		none	The channel to give the user VIP status in.
user	UserIdResolvable A user ID or a user or channel object. This is not a user name. Please use HelixUserApi#getUserByName to fetch a user object by name. Aliased type: string \| number \| UserIdResolvableType		none	The user to give VIP status.

Parameter	Type	Required	Default	Description
targetName	string		none	The name of the user to send the whisper message to.
text	string		none	The text to send.

Parameter	Type	Required	Default	Description
target	UserIdResolvable A user ID or a user or channel object. This is not a user name. Please use HelixUserApi#getUserByName to fetch a user object by name. Aliased type: string \| number \| UserIdResolvableType		none	The user to send the whisper message to.
text	string		none	The text to send.

Core functionality

Events

Functions

Interfaces

Type aliases

Bot

Overview

Events

Properties

Methods

Constructor

new Bot(config)

Events

onAction((event) => { /* ... */ })

onAnnouncement((event) => { /* ... */ })

onAuthenticationFailure((text, retryCount) => { /* ... */ })

onAuthenticationSuccess(() => { /* ... */ })

onBan((event) => { /* ... */ })

onBitsBadgeUpgrade((event) => { /* ... */ })

onChatClear((event) => { /* ... */ })

onCommunityPayForward((event) => { /* ... */ })

onCommunitySub((event) => { /* ... */ })

onConnect(() => { /* ... */ })

onDisconnect((manually, reason) => { /* ... */ })

onEmoteOnlyToggle((event) => { /* ... */ })

onFollowersOnlyToggle((event) => { /* ... */ })

onGiftPaidUpgrade((event) => { /* ... */ })

onJoin((event) => { /* ... */ })

onJoinFailure((event) => { /* ... */ })

onLeave((event) => { /* ... */ })

onMessage((event) => { /* ... */ })

onMessageFailed((channel, reason) => { /* ... */ })

onMessageRemove((event) => { /* ... */ })

onPrimePaidUpgrade((event) => { /* ... */ })

onRaid((event) => { /* ... */ })

onRaidCancel((event) => { /* ... */ })

onResub((event) => { /* ... */ })

onSlowModeToggle((event) => { /* ... */ })

onStandardPayForward((event) => { /* ... */ })

onSub((event) => { /* ... */ })

onSubGift((event) => { /* ... */ })

onSubsOnlyToggle((event) => { /* ... */ })

onTimeout((event) => { /* ... */ })

onTokenFetchFailure((error) => { /* ... */ })

onUniqueChatToggle((event) => { /* ... */ })

onWhisper((event) => { /* ... */ })

Properties

api

Type: ApiClient

chat

Type: ChatClient

Methods

action(channelName, text)

addVip(channelName, userName)

addVipByIds(channel, user)

announce(channelName, text, color)

announceById(channel, text, color)

ban(channelName, userName, reason)

banByIds(channel, user, reason)

changeColor(color)

clear(channelName)

clearById(channel)

deleteMessage(channelName, message)

deleteMessageById(channel, message)

disableEmoteOnly(channelName)

disableEmoteOnlyById(channel)

disableFollowersOnly(channelName)

disableFollowersOnlyById(channel)

disableSlowMode(channelName)

disableSlowModeById(channel)

disableSubsOnly(channelName)

disableSubsOnlyById(channel)

disableUniqueChat(channelName)

disableUniqueChatById(channel)

enableEmoteOnly(channelName)

enableEmoteOnlyById(channel)

enableFollowersOnly(channelName, minFollowTime)

enableFollowersOnlyById(channel, minFollowTime)

enableSlowMode(channelName, delayBetweenMessages)

enableSlowModeById(channel, delayBetweenMessages)