ChatClient

An interface to Twitch chat.

Overview

Constructor

new ChatClient(config)

Creates a new Twitch chat client.

Parameter	Type	Default	Description
config	ChatClientOptions	<complex>	see below
config.authIntents	string[]	none	The intents to use to query the auth provider. The "chat" intent will always be queried last, after the ones you give here.
config.authProvider	AuthProvider	none	The authentication provider to use for getting the chat credentials. If you don't pass this, the chat client will connect anonymously.
config.botLevel	TwitchBotLevel A Twitch bot level, i.e. whether you're connecting as a known or verified bot. Aliased type: "none" \| "known" \| "verified"	none	Your bot level, i.e. whether you're a known or verified bot. This defaults to 'none', which limits your messages to the standard rate limit.
config.channels	ResolvableValue<string[]>	none	Channels to join after connecting. May also be a function (sync or async) that returns a list of channels.
config.connectionOptions	WebSocketConnectionOptions	none	The connection options for a WebSocket connection. If not using WebSockets, this is ignored.
config.hostName	string	none	Custom hostname for connecting to chat.
config.isAlwaysMod	boolean	none	Whether you're guaranteed to be a mod in all joined channels. This raises the rate limit and lifts the one-second-between-messages rule, but if your bot is not a mod in one of the channels, it subjects you to messages possibly silently not being delivered and your bot possibly getting banned.
config.legacyScopes	boolean	none	Whether to request a token with the old chat permission scope. If you're not sure whether this is necessary, just try leaving this off, and if it doesn't work, turn it on and try again.
config.logger	Partial<LoggerOptions>	none	Options to pass to the logger.
config.readOnly	boolean	none	Whether to request a token with only read permission. Ignored if `legacyScopes` is `true`.
config.rejoinChannelsOnReconnect	boolean	none	Whether to rejoin the channels the client had joined when a reconnect occurs. This means that the `channels` option will only be resolved on the initial connection.
config.requestMembershipEvents	boolean	none	Whether to receive JOIN and PART messages from Twitch chat.
config.ssl	boolean	none	Whether to connect securely using SSL. You should not disable this except for debugging purposes.
config.webSocket	boolean	none	Whether to use a WebSocket to connect to chat.

Events

onAction((channel, user, text, msg) => { /* ... */ })

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

Parameter	Type	Description
channel	string	The channel the action was sent to.
user	string	The user that sent the action.
text	string	The action text.
msg	ChatMessage	The full message object containing all message and user information.

onAnnouncement((channel, user, announcementInfo, msg) => { /* ... */ })

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

Parameter	Type	Description
channel	string	The channel the announcement was sent to.
user	string	The user that sent the announcement.
announcementInfo	ChatAnnouncementInfo	Additional information about the announcement.
msg	UserNotice	The full message object containing all message and user information.

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((channel, user, msg) => { /* ... */ })

Fires when a user is permanently banned from a channel.

Parameter	Type	Description
channel	string	The channel the user is banned from.
user	string	The banned user.
msg	ClearChat	The full message object containing all message and user information.

onBitsBadgeUpgrade((channel, user, upgradeInfo, msg) => { /* ... */ })

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

Parameter	Type	Description
channel	string	The channel where the bits badge was upgraded.
user	string	The user that has upgraded their bits badge.
upgradeInfo	ChatBitsBadgeUpgradeInfo	none
msg	UserNotice	The full message object containing all message and user information.

onChatClear((channel, msg) => { /* ... */ })

Fires when the chat of a channel is cleared.

Parameter	Type	Description
channel	string	The channel whose chat is cleared.
msg	ClearChat	The full message object containing all message and user information.

onCommunityPayForward((channel, user, forwardInfo, msg) => { /* ... */ })

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

Parameter	Type	Description
channel	string	The channel where the gift was forwarded.
user	string	The user that forwarded the gift.
forwardInfo	ChatCommunityPayForwardInfo	Additional information about the gift.
msg	UserNotice	The full message object containing all message and user information.

onCommunitySub((channel, user, subInfo, msg) => { /* ... */ })

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 Sub gift spam.

Parameter	Type	Description
channel	string	The channel that was subscribed to.
user	string	The gifting user.
subInfo	ChatCommunitySubInfo	Additional information about the community subscription.
msg	UserNotice	The full message object containing all message and user information.

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.

onEmoteOnly((channel, enabled) => { /* ... */ })

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

Parameter	Type	Description
channel	string	The channel where emote-only mode is being toggled.
enabled	boolean	Whether emote-only mode is being enabled. If false, it's being disabled.

onFollowersOnly((channel, enabled, delay) => { /* ... */ })

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

Parameter	Type	Description
channel	string	The channel where followers-only mode is being toggled.
enabled	boolean	Whether followers-only mode is being enabled. If false, it's being disabled.
delay	number	The time (in minutes) a user needs to follow the channel to be able to talk. Only available when `enabled === true`.

onGiftPaidUpgrade((channel, user, subInfo, msg) => { /* ... */ })

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

Parameter	Type	Description
channel	string	The channel where the subscription was upgraded.
user	string	The user that upgraded their subscription.
subInfo	ChatSubGiftUpgradeInfo	Additional information about the subscription upgrade.
msg	UserNotice	The full message object containing all message and user information.

onJoin((channel, user) => { /* ... */ })

Fires when a user joins a channel.

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

Please note that unless you enabled the requestMembershipEvents option, this will only react to your own joins.

Parameter	Type	Description
channel	string	The channel that is being joined.
user	string	The user that joined.

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

Fires when you fail to join a channel.

Parameter	Type	Description
channel	string	The channel that you tried to join.
reason	string	The reason for the failure.

onMessage((channel, user, text, msg) => { /* ... */ })

Fires when a user sends a message to a channel.

Parameter	Type	Description
channel	string	The channel the message was sent to.
user	string	The user that sent the message.
text	string	The message text.
msg	ChatMessage	The full message object containing all message and user information.

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)

onMessageRatelimit((channel, text) => { /* ... */ })

Fires when a message you tried to send gets rejected by the ratelimiter.

Parameter	Type	Description
channel	string	The channel that was attempted to send to.
text	string	The message text.

onMessageRemove((channel, messageId, msg) => { /* ... */ })

Fires when a single message is removed from a channel.

Parameter	Type	Description
channel	string	The channel where the message was removed.
messageId	string	The ID of the message that was removed.
msg	ClearMsg	The full message object containing all message and user information. This is not the message that was removed. The text of the message is available using `msg.params.message` though.

onNoPermission((channel, text) => { /* ... */ })

Fires when you tried to execute a command you don't have sufficient permission for.

Parameter	Type	Description
channel	string	The channel that a command without sufficient permissions was executed on.
text	string	The message text.

onPart((channel, user) => { /* ... */ })

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

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

Please note that unless you enabled the requestMembershipEvents option, this will only react to your own parts.

Parameter	Type	Description
channel	string	The channel that is being left.
user	string	The user that left.

onPrimeCommunityGift((channel, user, subInfo, msg) => { /* ... */ })

Fires when a user gifts a Twitch Prime benefit to the channel.

Parameter	Type	Description
channel	string	The channel where the benefit was gifted.
user	string	The user that received the gift. WARNING: This is a display name and thus will not work as an identifier for the API (login) in some cases.
subInfo	ChatPrimeCommunityGiftInfo	Additional information about the gift.
msg	UserNotice	The full message object containing all message and user information.

onPrimePaidUpgrade((channel, user, subInfo, msg) => { /* ... */ })

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

Parameter	Type	Description
channel	string	The channel where the subscription was upgraded.
user	string	The user that upgraded their subscription.
subInfo	ChatSubUpgradeInfo	Additional information about the subscription upgrade.
msg	UserNotice	The full message object containing all message and user information.

onRaid((channel, user, raidInfo, msg) => { /* ... */ })

Fires when a user raids a channel.

Parameter	Type	Description
channel	string	The channel that was raided.
user	string	The user that has raided the channel.
raidInfo	ChatRaidInfo	Additional information about the raid.
msg	UserNotice	The full message object containing all message and user information.

onRaidCancel((channel, msg) => { /* ... */ })

Fires when a user cancels a raid.

Parameter	Type	Description
channel	string	The channel where the raid was cancelled.
msg	UserNotice	The full message object containing all message and user information.

onResub((channel, user, subInfo, msg) => { /* ... */ })

Fires when a user resubscribes to a channel.

Parameter	Type	Description
channel	string	The channel that was resubscribed to.
user	string	The resubscribing user.
subInfo	ChatSubInfo	Additional information about the resubscription.
msg	UserNotice	The full message object containing all message and user information.

onRewardGift((channel, user, rewardGiftInfo, msg) => { /* ... */ })

Fires when a user gifts rewards during a special event.

Parameter	Type	Description
channel	string	The channel where the rewards were gifted.
user	string	The user that gifted the rewards.
rewardGiftInfo	ChatRewardGiftInfo	Additional information about the reward gift.
msg	UserNotice	The full message object containing all message and user information.

onRitual((channel, user, ritualInfo, msg) => { /* ... */ })

Fires when a user performs a "ritual" in a channel.

Parameter	Type	Description
channel	string	The channel where the ritual was performed.
user	string	The user that has performed the ritual.
ritualInfo	ChatRitualInfo	Additional information about the ritual.
msg	UserNotice	The full message object containing all message and user information.

onSlow((channel, enabled, delay) => { /* ... */ })

Fires when slow mode is toggled in a channel.

Parameter	Type	Description
channel	string	The channel where slow mode is being toggled.
enabled	boolean	Whether slow mode is being enabled. If false, it's being disabled.
delay	number	The time (in seconds) a user has to wait between sending messages. Only set when enabling slow mode.

onStandardPayForward((channel, user, forwardInfo, msg) => { /* ... */ })

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

Parameter	Type	Description
channel	string	The channel where the gift was forwarded.
user	string	The user that forwarded the gift.
forwardInfo	ChatStandardPayForwardInfo	Additional information about the gift.
msg	UserNotice	The full message object containing all message and user information.

onSub((channel, user, subInfo, msg) => { /* ... */ })

Fires when a user subscribes to a channel.

Parameter	Type	Description
channel	string	The channel that was subscribed to.
user	string	The subscribing user.
subInfo	ChatSubInfo	Additional information about the subscription.
msg	UserNotice	The full message object containing all message and user information.

onSubExtend((channel, user, subInfo, msg) => { /* ... */ })

Fires when a user extends their subscription using a Sub Token.

Parameter	Type	Description
channel	string	The channel where the subscription was extended.
user	string	The user that extended their subscription.
subInfo	ChatSubExtendInfo	Additional information about the subscription extension.
msg	UserNotice	The full message object containing all message and user information.

onSubGift((channel, user, subInfo, msg) => { /* ... */ })

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 Sub gift spam.

Parameter	Type	Description
channel	string	The channel that was subscribed to.
user	string	The user that the subscription was gifted to. The gifting user is defined in `subInfo.gifter`.
subInfo	ChatSubGiftInfo	Additional information about the subscription.
msg	UserNotice	The full message object containing all message and user information.

onSubsOnly((channel, enabled) => { /* ... */ })

Fires when sub only mode is toggled in a channel.

Parameter	Type	Description
channel	string	The channel where sub only mode is being toggled.
enabled	boolean	Whether sub only mode is being enabled. If false, it's being disabled.

onTimeout((channel, user, duration, msg) => { /* ... */ })

Fires when a user is timed out from a channel.

Parameter	Type	Description
channel	string	The channel the user is timed out from.
user	string	The timed out user.
duration	number	The duration of the timeout, in seconds.
msg	ClearChat	The full message object containing all message and user information.

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

Fires when fetching a token fails.

Parameter	Type	Description
error	Error	The error that was thrown.

onUniqueChat((channel, enabled) => { /* ... */ })

Fires when unique chat mode is toggled in a channel.

Parameter	Type	Description
channel	string	The channel where unique chat mode is being toggled.
enabled	boolean	Whether unique chat mode is being enabled. If false, it's being disabled.

onWhisper((user, text, msg) => { /* ... */ })

Fires when receiving a whisper from another user.

Parameter	Type	Description
user	string	The user that sent the whisper.
text	string	The message text.
msg	Whisper	The full message object containing all message and user information.

Properties

currentChannels

Type: string[]

The channels the client is currently in.

irc

Type: IrcClient

The underlying IRC client. Use sparingly.

isConnected

Type: boolean

Whether the chat client is currently connected.

isConnecting

Type: boolean

Whether the chat client is currently connecting.

Methods

action(channel, text, rateLimiterOptions)

async

Sends an action message (/me) to a channel.

Parameter	Type	Default	Description
channel	string	none	The channel to send the message to.
text	string	none	The message to send.
rateLimiterOptions	RateLimiterRequestOptions	none	Options to pass to the rate limiter.

Return type: void

connect()

Connects to the chat server.

Return type: void

join(channel)

async

Joins a channel.

Parameter	Type	Required	Default	Description
channel	string		none	The channel to join.

Return type: void

part(channel)

Leaves a channel ("part" in IRC terms).

Parameter	Type	Required	Default	Description
channel	string		none	The channel to leave.

Return type: void

quit()

Disconnects from the chat server.

Return type: void

reconnect()

Reconnects to the chat server.

Return type: void

say(channel, text, attributes, rateLimiterOptions)

async

Sends a regular chat message to a channel.

Parameter	Type	Default	Description
channel	string	none	The channel to send the message to.
text	string	none	The message to send.
attributes	ChatSayMessageAttributes	<complex>	The attributes to add to the message.
rateLimiterOptions	RateLimiterRequestOptions	none	Options to pass to the rate limiter.

Return type: void

Classes

Functions

Interfaces

Type aliases

ChatClient

Overview

Events

Properties

Methods

Constructor

new ChatClient(config)

Events

onAction((channel, user, text, msg) => { /* ... */ })

onAnnouncement((channel, user, announcementInfo, msg) => { /* ... */ })

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

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

onBan((channel, user, msg) => { /* ... */ })

onBitsBadgeUpgrade((channel, user, upgradeInfo, msg) => { /* ... */ })

onChatClear((channel, msg) => { /* ... */ })

onCommunityPayForward((channel, user, forwardInfo, msg) => { /* ... */ })

onCommunitySub((channel, user, subInfo, msg) => { /* ... */ })

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

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

onEmoteOnly((channel, enabled) => { /* ... */ })

onFollowersOnly((channel, enabled, delay) => { /* ... */ })

onGiftPaidUpgrade((channel, user, subInfo, msg) => { /* ... */ })

onJoin((channel, user) => { /* ... */ })

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

onMessage((channel, user, text, msg) => { /* ... */ })

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

onMessageRatelimit((channel, text) => { /* ... */ })

onMessageRemove((channel, messageId, msg) => { /* ... */ })

onNoPermission((channel, text) => { /* ... */ })

onPart((channel, user) => { /* ... */ })

onPrimeCommunityGift((channel, user, subInfo, msg) => { /* ... */ })

onPrimePaidUpgrade((channel, user, subInfo, msg) => { /* ... */ })

onRaid((channel, user, raidInfo, msg) => { /* ... */ })

onRaidCancel((channel, msg) => { /* ... */ })

onResub((channel, user, subInfo, msg) => { /* ... */ })

onRewardGift((channel, user, rewardGiftInfo, msg) => { /* ... */ })

onRitual((channel, user, ritualInfo, msg) => { /* ... */ })

onSlow((channel, enabled, delay) => { /* ... */ })

onStandardPayForward((channel, user, forwardInfo, msg) => { /* ... */ })

onSub((channel, user, subInfo, msg) => { /* ... */ })

onSubExtend((channel, user, subInfo, msg) => { /* ... */ })

onSubGift((channel, user, subInfo, msg) => { /* ... */ })

onSubsOnly((channel, enabled) => { /* ... */ })

onTimeout((channel, user, duration, msg) => { /* ... */ })

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

onUniqueChat((channel, enabled) => { /* ... */ })

onWhisper((user, text, msg) => { /* ... */ })

Properties

currentChannels

Type: string[]

irc

Type: IrcClient

isConnected

Type: boolean

isConnecting

Type: boolean

Methods

action(channel, text, rateLimiterOptions)

connect()

join(channel)

part(channel)

quit()

reconnect()

say(channel, text, attributes, rateLimiterOptions)