TwurpleAuthenticationGetting dataExamplesFAQMigration

ChatClient

An interface to Twitch chat.

Overview

Constructor

new ChatClient(config)

Creates a new Twitch chat client.

ParameterTypeRequiredDefaultDescription
configChatClientOptions<complex>see below
config.authIntentsstring[]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.authProviderAuthProvidernone

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.channelsResolvableValue<string[]>none

Channels to join after connecting.

May also be a function (sync or async) that returns a list of channels.

config.connectionOptionsWebSocketConnectionOptionsnone

The connection options for a WebSocket connection.

If not using WebSockets, this is ignored.

config.hostNamestringnone

Custom hostname for connecting to chat.

config.isAlwaysModbooleannone

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.legacyScopesbooleannone

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.loggerPartial<LoggerOptions>none

Options to pass to the logger.

config.readOnlybooleannone

Whether to request a token with only read permission.

Ignored if legacyScopes is true.

config.rejoinChannelsOnReconnectbooleannone

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.requestMembershipEventsbooleannone

Whether to receive JOIN and PART messages from Twitch chat.

config.sslbooleannone

Whether to connect securely using SSL.

You should not disable this except for debugging purposes.

config.webSocketbooleannone

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.

ParameterTypeDescription
channelstring

The channel the action was sent to.

userstring

The user that sent the action.

textstring

The action text.

msgChatMessage

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.

ParameterTypeDescription
channelstring

The channel the announcement was sent to.

userstring

The user that sent the announcement.

announcementInfoChatAnnouncementInfo

Additional information about the announcement.

msgUserNotice

The full message object containing all message and user information.

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

Fires when authentication fails.

ParameterTypeDescription
textstring

The message text.

retryCountnumber

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.

ParameterTypeDescription
channelstring

The channel the user is banned from.

userstring

The banned user.

msgClearChat

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.

ParameterTypeDescription
channelstring

The channel where the bits badge was upgraded.

userstring

The user that has upgraded their bits badge.

upgradeInfoChatBitsBadgeUpgradeInfonone
msgUserNotice

The full message object containing all message and user information.

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

Fires when the chat of a channel is cleared.

ParameterTypeDescription
channelstring

The channel whose chat is cleared.

msgClearChat

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.

ParameterTypeDescription
channelstring

The channel where the gift was forwarded.

userstring

The user that forwarded the gift.

forwardInfoChatCommunityPayForwardInfo

Additional information about the gift.

msgUserNotice

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.

ParameterTypeDescription
channelstring

The channel that was subscribed to.

userstring

The gifting user.

subInfoChatCommunitySubInfo

Additional information about the community subscription.

msgUserNotice

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.

ParameterTypeDescription
manuallyboolean

Whether the disconnect was requested by the user.

reasonError

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.

ParameterTypeDescription
channelstring

The channel where emote-only mode is being toggled.

enabledboolean

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.

ParameterTypeDescription
channelstring

The channel where followers-only mode is being toggled.

enabledboolean

Whether followers-only mode is being enabled. If false, it's being disabled.

delaynumber

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.

ParameterTypeDescription
channelstring

The channel where the subscription was upgraded.

userstring

The user that upgraded their subscription.

subInfoChatSubGiftUpgradeInfo

Additional information about the subscription upgrade.

msgUserNotice

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.

ParameterTypeDescription
channelstring

The channel that is being joined.

userstring

The user that joined.

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

Fires when you fail to join a channel.

ParameterTypeDescription
channelstring

The channel that you tried to join.

reasonstring

The reason for the failure.

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

Fires when a user sends a message to a channel.

ParameterTypeDescription
channelstring

The channel the message was sent to.

userstring

The user that sent the message.

textstring

The message text.

msgChatMessage

The full message object containing all message and user information.

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

Fires when sending a message fails.

ParameterTypeDescription
channelstring

The channel that rejected the message.

reasonstring

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.

ParameterTypeDescription
channelstring

The channel that was attempted to send to.

textstring

The message text.

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

Fires when a single message is removed from a channel.

ParameterTypeDescription
channelstring

The channel where the message was removed.

messageIdstring

The ID of the message that was removed.

msgClearMsg

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.

ParameterTypeDescription
channelstring

The channel that a command without sufficient permissions was executed on.

textstring

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.

ParameterTypeDescription
channelstring

The channel that is being left.

userstring

The user that left.

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

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

ParameterTypeDescription
channelstring

The channel where the benefit was gifted.

userstring

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.

subInfoChatPrimeCommunityGiftInfo

Additional information about the gift.

msgUserNotice

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.

ParameterTypeDescription
channelstring

The channel where the subscription was upgraded.

userstring

The user that upgraded their subscription.

subInfoChatSubUpgradeInfo

Additional information about the subscription upgrade.

msgUserNotice

The full message object containing all message and user information.

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

Fires when a user raids a channel.

ParameterTypeDescription
channelstring

The channel that was raided.

userstring

The user that has raided the channel.

raidInfoChatRaidInfo

Additional information about the raid.

msgUserNotice

The full message object containing all message and user information.

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

Fires when a user cancels a raid.

ParameterTypeDescription
channelstring

The channel where the raid was cancelled.

msgUserNotice

The full message object containing all message and user information.

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

Fires when a user resubscribes to a channel.

ParameterTypeDescription
channelstring

The channel that was resubscribed to.

userstring

The resubscribing user.

subInfoChatSubInfo

Additional information about the resubscription.

msgUserNotice

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.

ParameterTypeDescription
channelstring

The channel where the rewards were gifted.

userstring

The user that gifted the rewards.

rewardGiftInfoChatRewardGiftInfo

Additional information about the reward gift.

msgUserNotice

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.

ParameterTypeDescription
channelstring

The channel where the ritual was performed.

userstring

The user that has performed the ritual.

ritualInfoChatRitualInfo

Additional information about the ritual.

msgUserNotice

The full message object containing all message and user information.

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

Fires when slow mode is toggled in a channel.

ParameterTypeDescription
channelstring

The channel where slow mode is being toggled.

enabledboolean

Whether slow mode is being enabled. If false, it's being disabled.

delaynumber

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.

ParameterTypeDescription
channelstring

The channel where the gift was forwarded.

userstring

The user that forwarded the gift.

forwardInfoChatStandardPayForwardInfo

Additional information about the gift.

msgUserNotice

The full message object containing all message and user information.

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

Fires when a user subscribes to a channel.

ParameterTypeDescription
channelstring

The channel that was subscribed to.

userstring

The subscribing user.

subInfoChatSubInfo

Additional information about the subscription.

msgUserNotice

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.

ParameterTypeDescription
channelstring

The channel where the subscription was extended.

userstring

The user that extended their subscription.

subInfoChatSubExtendInfo

Additional information about the subscription extension.

msgUserNotice

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.

ParameterTypeDescription
channelstring

The channel that was subscribed to.

userstring

The user that the subscription was gifted to. The gifting user is defined in subInfo.gifter.

subInfoChatSubGiftInfo

Additional information about the subscription.

msgUserNotice

The full message object containing all message and user information.

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

Fires when sub only mode is toggled in a channel.

ParameterTypeDescription
channelstring

The channel where sub only mode is being toggled.

enabledboolean

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.

ParameterTypeDescription
channelstring

The channel the user is timed out from.

userstring

The timed out user.

durationnumber

The duration of the timeout, in seconds.

msgClearChat

The full message object containing all message and user information.

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

Fires when fetching a token fails.

ParameterTypeDescription
errorError

The error that was thrown.

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

Fires when unique chat mode is toggled in a channel.

ParameterTypeDescription
channelstring

The channel where unique chat mode is being toggled.

enabledboolean

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.

ParameterTypeDescription
userstring

The user that sent the whisper.

textstring

The message text.

msgWhisper

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.

ParameterTypeRequiredDefaultDescription
channelstringnone

The channel to send the message to.

textstringnone

The message to send.

rateLimiterOptionsRateLimiterRequestOptionsnone

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.

ParameterTypeRequiredDefaultDescription
channelstringnone

The channel to join.

Return type: void

part(channel)

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

ParameterTypeRequiredDefaultDescription
channelstringnone

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.

ParameterTypeRequiredDefaultDescription
channelstringnone

The channel to send the message to.

textstringnone

The message to send.

attributesChatSayMessageAttributes<complex>

The attributes to add to the message.

rateLimiterOptionsRateLimiterRequestOptionsnone

Options to pass to the rate limiter.

Return type: void