Events

Everything a plugin does starts with one of these. Anything not listed here is not something a plugin can see.

on message do
  # event.user, event.text, ...
end

Every event carries event.channel, the display name of the chat it happened in.

message

Someone said something in a chat you have open. The busiest event by far - a big chat can send thousands a minute, so keep the handler short.

Field	Type
event.user	text	login name, lower case
event.name	text	display name, as shown in chat
event.text	text	the message
event.is_mod	yes/no	moderator or broadcaster
event.is_sub	yes/no	subscriber or founder
event.is_vip	yes/no	VIP
event.is_first	yes/no	their first ever message in this chat
event.is_highlight	yes/no	it mentioned you or one of your highlight words
event.colour	text	their name colour

Messages loaded as history when you join a chat do not fire this event.

timeout

Field	Type
event.user	text	who was timed out
event.seconds	number	how long for
event.by	text	which moderator, when Chattler knows
event.reason	text	the reason, when there is one

note

by and reason come from the moderation feed, which sometimes arrives a moment after the timeout itself. They can be empty even when a moderator did it. event.user and event.seconds are always there.

ban

Same as timeout without seconds.

delete

A single message was deleted.

Field	Type
event.user	text	whose message
event.text	text	what it said

automod

AutoMod held a message for review. Only fires in channels you moderate.

Field	Type
event.user	text	who sent it
event.text	text	the held message
event.category	text	bullying, blocked_term, blocked_link, and so on
event.level	number	how sure AutoMod is, 1 to 4

automod_waiting

Fires every five seconds for each held message still waiting for an answer. This is how you nudge a mod team that has missed one.

Field	Type
event.user	text	who sent it
event.text	text	the held message
event.seconds	number	how long it has been waiting
event.category	text	as above

Use cooldown here, or you will get an alert every five seconds.

automod_result

A moderator allowed or denied a held message.

Field	Type
event.user	text	whose message
event.allowed	yes/no	true allowed, false denied
event.by	text	which moderator

modaction

Any action from your mod team's live feed: bans, timeouts, deletions, warnings, blocked-term changes, shoutouts, chat-mode changes.

Field	Type
event.action	text	ban, timeout, delete, warn, raid, and so on
event.user	text	who it was aimed at, when it was aimed at someone
event.by	text	which moderator
event.reason	text	the reason, when there is one

suspicious

Someone Twitch flags as suspicious said something. Needs the suspicious-users permission - log in again once if you have never granted it.

Field	Type
event.user	text	who
event.text	text	what they said
event.status	text	restricted, monitored or none
event.types	list	ban_evader, banned_in_shared_channel, manually_added
event.bans	number	how many shared channels have banned them

sub

A subscription, resub, gift or Prime upgrade.

Field	Type
event.user	text	who
event.tier	text	1000, 2000, 3000 or Prime
event.months	number	months in a row, when they said
event.gifted	yes/no	was it a gift
event.count	number	how many were gifted

raid

Someone raided a chat you have open.

Field	Type
event.user	text	who is raiding
event.viewers	number	how many people came with them

redemption

A channel point reward was redeemed.

Field	Type
event.user	text	who redeemed it
event.reward	text	the reward name
event.cost	number	what it cost them

speed

Fires every five seconds for every chat you have open, with how fast it is going.

Field	Type
event.rate	number	messages a minute, over the last minute

tick

Fires every five seconds, once, with nothing to do with any particular chat. For housekeeping.

Field	Type
event.time	number	the time now

start

Fires once when Chattler has loaded your plugins. Good for a log("loaded") while you are working on something.