Events

Some events will only be fired if you are logged in. If you are not familiar with event listeners, please read this.

Contents

  • Action - Received action message on channel.
  • Ban - Username has been banned on a channel.
  • Chat - Received message on channel.
  • Cheer - Username has cheered to a channel.
  • Clearchat - Chat of a channel got cleared.
  • Connected - Connected to server.
  • Connecting - Connecting to a server.
  • Disconnected - Got disconnected from server.
  • Emoteonly - Channel enabled or disabled emote-only mode.
  • Emotesets - Received the emote-sets from Twitch.
  • Followersonly - Channel enabled or disabled followers-only mode.
  • Hosted - Channel is now hosted by another broadcaster.
  • Hosting - Channel is now hosting another channel.
  • Join - Username has joined a channel.
  • Logon - Connection established, sending informations to server.
  • Message - Received a message.
  • Mod - Someone got modded on a channel.
  • Mods - Received the list of moderators of a channel.
  • Notice - Received a notice from server.
  • Part - User has left a channel.
  • Ping - Received PING from server.
  • Pong - Sent a PING request ? PONG.
  • R9kbeta - Channel enabled or disabled R9K mode.
  • Reconnect - Trying to reconnect to server.
  • Resub - Username has resubbed on a channel.
  • Roomstate - The current state of the channel.
  • Serverchange - Channel is no longer located on this cluster.
  • Slowmode - Gives you the current state of the channel.
  • Subscribers - Channel enabled or disabled subscribers-only mode.
  • Subscription - Username has subscribed to a channel.
  • Timeout - Username has been timed out on a channel.
  • Unhost - Channel ended the current hosting.
  • Unmod - Someone got unmodded on a channel.
  • Whisper - Received a whisper.

Action

Received action message on channel. (/me <message>)

Parameters:

  • channel: String - Channel name
  • userstate: Object - Userstate object
  • message: String - Message received
  • self: Boolean - Message was sent by the client
client.on("action", function (channel, userstate, message, self) {
    // Don't listen to my own messages..
    if (self) return;

    // Do your stuff.
});

According to Twitch, the userstate object is always subject to change.

{
    'badges': { 'broadcaster': '1', 'warcraft': 'horde' },
    'color': '#FFFFFF',
    'display-name': 'Schmoopiie',
    'emotes': { '25': [ '0-4' ] },
    'mod': true,
    'room-id': '58355428',
    'subscriber': false,
    'turbo': true,
    'user-id': '58355428',
    'user-type': 'mod',
    'emotes-raw': '25:0-4',
    'badges-raw': 'broadcaster/1,warcraft/horde',
    'username': 'schmoopiie',
    'message-type': 'action'
}

Ban

Username has been banned on a channel.

Parameters:

  • channel: String - Channel name
  • username: String - Username
  • reason: String - Reason of the ban can also be null
client.on("ban", function (channel, username, reason) {
    // Do your stuff.
});

Chat

Received message on channel.

Parameters:

  • channel: String - Channel name
  • userstate: Object - Userstate object
  • message: String - Message received
  • self: Boolean - Message was sent by the client
client.on("chat", function (channel, userstate, message, self) {
    // Don't listen to my own messages..
    if (self) return;

    // Do your stuff.
});

According to Twitch, the user object is always subject to change.

{
    'badges': { 'broadcaster': '1', 'warcraft': 'horde' },
    'color': '#FFFFFF',
    'display-name': 'Schmoopiie',
    'emotes': { '25': [ '0-4' ] },
    'mod': true,
    'room-id': '58355428',
    'subscriber': false,
    'turbo': true,
    'user-id': '58355428',
    'user-type': 'mod',
    'emotes-raw': '25:0-4',
    'badges-raw': 'broadcaster/1,warcraft/horde',
    'username': 'schmoopiie',
    'message-type': 'chat'
}

Cheer

Username has cheered to a channel.

Parameters:

  • channel: String - Channel name
  • userstate: Object - Userstate object
  • message: String - Message
client.on("cheer", function (channel, userstate, message) {
    // Do your stuff.
});

Note: The amount of bits the user sent is inside the userstate (userstate.bits) - Read the Twitch API documentation for more information.

Clearchat

Chat of a channel got cleared.

Parameters:

  • channel: String - Channel name
client.on("clearchat", function (channel) {
    // Do your stuff.
});

Connected

Connected to server.

Parameters:

  • address: String - Remote address
  • port: Integer - Remote port
client.on("connected", function (address, port) {
    // Do your stuff.
});

Connecting

Connecting to a server.

Parameters:

  • address: String - Remote address
  • port: Integer - Remote port
client.on("connecting", function (address, port) {
    // Do your stuff.
});

Disconnected

Got disconnected from server.

Parameters:

  • reason: String - Reason why you got disconnected
client.on("disconnected", function (reason) {
    // Do your stuff.
});

Emoteonly

Channel enabled or disabled emote-only mode.

Parameters:

  • channel: String - Channel name
  • enabled: Boolean - Returns true if mode is enabled or false if disabled
client.on("emoteonly", function (channel, enabled) {
    // Do your stuff.
});

Emotesets

Received the emote-sets from Twitch.

Parameters:

  • sets: String - Your emote sets (always contains the default emoticons set 0)
  • obj: Object - Your emote sets with IDs and codes received from the Twitch API
client.on("emotesets", function(sets, obj) {
    // Here are the emotes I can use:
    console.log(obj);
});

Followersonly

Channel enabled or disabled followers-only mode.

Parameters:

  • channel: String - Channel name
  • enabled: Boolean - Returns true if mode is enabled or false if disabled
  • length: Integer - Length in minutes
client.on("followersonly", function (channel, enabled, length) {
    // Do your stuff.
});

Hosted

Channel is now hosted by another broadcaster. This event is fired only if you are logged in as the broadcaster.

Parameters:

  • channel: String - Channel name being hosted
  • username: String - Username hosting you
  • viewers: Integer - Viewers count
  • autohost: Boolean - Auto-hosting
client.on("hosted", function (channel, username, viewers, autohost) {
    // Do your stuff.
});

Hosting

Channel is now hosting another channel.

Parameters:

  • channel: String - Channel name that is now hosting
  • target: String - Channel being hosted
  • viewers: Integer - Viewers count
client.on("hosting", function (channel, target, viewers) {
    // Do your stuff.
});

Join

Username has joined a channel. Not available on large channels and is also sent in batch every 30-60secs.

Parameters:

  • channel: String - Channel name
  • username: String - Username who joined the channel
  • self: Boolean - Client has joined the channel
client.on("join", function (channel, username, self) {
    // Do your stuff.
});

Logon

Connection established, sending informations to server.

client.on("logon", function () {
    // Do your stuff.
});

Message

Received a message. This event is fired whenever you receive a chat, action or whisper message.

Parameters:

  • channel: String - Channel name
  • userstate: Object - Userstate object
  • message: String - Message received
  • self: Boolean - Message was sent by the client
client.on("message", function (channel, userstate, message, self) {
    // Don't listen to my own messages..
    if (self) return;

    // Handle different message types..
    switch(userstate["message-type"]) {
        case "action":
            // This is an action message..
            break;
        case "chat":
            // This is a chat message..
            break;
        case "whisper":
            // This is a whisper..
            break;
        default:
            // Something else ?
            break;
    }
});

According to Twitch, the userstate object is always subject to change.

{
    'badges': { 'broadcaster': '1', 'warcraft': 'horde' },
    'color': '#FFFFFF',
    'display-name': 'Schmoopiie',
    'emotes': { '25': [ '0-4' ] },
    'mod': true,
    'room-id': '58355428',
    'subscriber': false,
    'turbo': true,
    'user-id': '58355428',
    'user-type': 'mod',
    'emotes-raw': '25:0-4',
    'badges-raw': 'broadcaster/1,warcraft/horde',
    'username': 'schmoopiie',
    'message-type': 'action'
}

Mod

Someone got modded on a channel.

Important: It doesn’t detect if username is a new moderator, it is triggered when jtv gives the moderator status to someone on a channel. You will see a lot of mod / unmod events on a channel. When a moderator joins a channel, it will take a few seconds for jtv to give the user the moderator status. When leaving a channel, the user gets unmodded.

Parameters:

  • channel: String - Channel name
  • username: String - Username
client.on("mod", function (channel, username) {
    // Do your stuff.
});

Mods

Received the list of moderators of a channel.

Parameters:

  • channel: String - Channel name
  • mods: Array - Moderators of the channel
client.on("mods", function (channel, mods) {
    // Do your stuff.
});

Notice

Received a notice from server. The goal of these notices is to allow the users to change their language settings and still be able to know programmatically what message was sent by the server. We encourage to use the msg-id to compare these messages.

Parameters:

  • channel: String - Channel name
  • msgid: String - Message ID (See known msg-ids below)
  • message: String - Message received

Known msg-ids:

  • already_banned: X is already banned in this room.
  • already_emote_only_on: This room is already in emote-only mode.
  • already_emote_only_off: This room is not in emote-only mode.
  • already_subs_on: This room is already in subscribers-only mode.
  • already_subs_off: This room is not in subscribers-only mode.
  • bad_ban_admin: You cannot ban admin X.
  • bad_ban_broadcaster: You cannot ban the broadcaster.
  • bad_ban_global_mod: You cannot ban global moderator X.
  • bad_ban_self: You cannot ban yourself.
  • bad_ban_staff: You cannot ban staff X.
  • bad_commercial_error: Failed to start commercial.
  • bad_host_hosting: This channel is already hosting X.
  • bad_host_rate_exceeded: Host target cannot be changed more than 3 times every half hour.
  • bad_mod_mod: X is already a moderator of this room.
  • bad_mod_banned: X is banned in this room.
  • bad_timeout_admin: You cannot timeout admin X.
  • bad_timeout_global_mod: You cannot timeout global moderator X.
  • bad_timeout_self: You cannot timeout yourself.
  • bad_timeout_staff: You cannot timeout staff X.
  • bad_unban_no_ban: X is not banned from this room.
  • bad_unmod_mod: X is not a moderator of this room.
  • ban_success: X is now banned from this room.
  • cmds_available: Commands available to you in this room (use /help for details)..
  • color_changed: Your color has been changed.
  • commercial_success: Initiating X second commercial break. Please keep in mind..
  • emote_only_on: This room is now in emote-only mode.
  • emote_only_off: This room is no longer in emote-only mode.
  • hosts_remaining: X host commands remaining this half hour.
  • host_target_went_offline: X has gone offline. Exiting host mode
  • mod_success: You have added X as a moderator of this room.
  • msg_banned: You are permanently banned from talking in channel.
  • msg_censored_broadcaster: Your message was modified for using words banned by X.
  • msg_channel_suspended: This channel has been suspended.
  • msg_duplicate: Your message was not sent because you are sending messages too quickly.
  • msg_emoteonly: This room is in emote only mode.
  • msg_ratelimit: Your message was not sent because you are sending messages too quickly.
  • msg_subsonly: This room is in subscribers only mode. To talk, purchase..
  • msg_timedout: You are banned from talking in X for Y more seconds.
  • msg_verified_email: This room requires a verified email address to chat.
  • no_help: No help available.
  • no_permission: You don’t have permission to perform that action.
  • not_hosting: No channel is currently being hosted.
  • timeout_success: X has been timed out for length seconds.
  • unban_success: X is no longer banned from this room.
  • unmod_success: You have removed X as a moderator of this room.
  • unrecognized_cmd: Unrecognized command: X
  • usage_ban: Usage: “/ban “ - Permanently prevent a user from chatting..
  • usage_clear: Usage: “/clear” - Clear chat history for all users in this room.
  • usage_color: Usage: “/color " - Change your username color. Color must be..
  • usage_commercial: Usage: “/commercial [length]” - Triggers a commercial.
  • usage_disconnect: Usage: “/disconnect” - Reconnects to chat.
  • usage_emote_only_on: Usage: “/emoteonly” - Enables emote-only mode..
  • usage_emote_only_off: Usage: “/emoteonlyoff” - Disables emote-only mode..
  • usage_help: Usage: “/help” - Lists the commands available to you in this room.
  • usage_host: Usage: “/host “ - Host another channel. Use “unhost” to unset host mode.
  • usage_me: Usage: “/me “ - Send an “emote” message in the third person.
  • usage_mod: Usage: “/mod “ - Grant mod status to a user. Use “mods” to list the..
  • usage_mods: Usage: “/mods” - Lists the moderators of this channel.
  • usage_r9k_on: Usage: “/r9kbeta” - Enables r9k mode. See http://bit.ly/bGtBDf for details.
  • usage_r9k_off: Usage: “/r9kbetaoff” - Disables r9k mode.
  • usage_slow_on: Usage: “/slow [duration]” - Enables slow mode..
  • usage_slow_off: Usage: “/slowoff” - Disables slow mode.
  • usage_subs_on: Usage: “/subscribers” - Enables subscribers-only mode..
  • usage_subs_off: Usage: “/subscribersoff” - Disables subscribers-only mode.
  • usage_timeout: Usage: “/timeout [duration]” - Temporarily prevent a user from chatting.
  • usage_unban: Usage: “/unban “ - Removes a ban on a user.
  • usage_unhost: Usage: “/unhost” - Stop hosting another channel.
  • usage_unmod: Usage: “/unmod “ - Revoke mod status from a user..
  • whisper_invalid_self: You cannot whisper to yourself.
  • whisper_limit_per_min: You are sending whispers too fast. Try again in a minute.
  • whisper_limit_per_sec: You are sending whispers too fast. Try again in a second.
  • whisper_restricted_recipient: That user’s settings prevent them from receiving this whisper.

The following msg-ids wont be returned in the notice event because they are already available as event listeners:

  • host_off: Exited hosting mode.
  • host_on: Now hosting X
  • no_mods: There are no moderators for this room.
  • r9k_off: This room is no longer in r9k mode.
  • r9k_on: This room is now in r9k mode.
  • room_mods: The moderators of this room are X
  • slow_off: This room is no longer in slow mode.
  • slow_on: This room is now in slow mode. You may send messages every X seconds.
  • subs_off: This room is no longer in subscribers-only mode.
  • subs_on: This room is now in subscribers-only mode.
client.on("notice", function (channel, msgid, message) {
    // Do your stuff.
});

Part

User has left a channel.

Parameters:

  • channel: String - Channel name
  • username: String - Username who left the channel
  • self: Boolean - Client has left the channel
client.on("part", function (channel, username, self) {
    // Do your stuff.
});

Ping

Received PING from server.

client.on("ping", function () {
    // Do your stuff.
});

Pong

Sent a PING request ? PONG.

Parameters:

  • latency: Float - Current latency
client.on("pong", function (latency) {
    // Do your stuff.
});

R9kbeta

Channel enabled or disabled R9K mode.

Parameters:

  • channel: String - Channel name
  • enabled: Boolean - Returns true if mode is enabled or false if disabled
client.on("r9kbeta", function (channel, enabled) {
    // Do your stuff.
});

Reconnect

Trying to reconnect to server.

client.on("reconnect", function () {
    // Do your stuff.
});

Resub

Username has resubbed on a channel.

Parameters:

  • channel: String - Channel name
  • username: String - Username
  • months: Integer - How many months
  • message: String - Custom message
  • userstate: Object - Userstate
  • methods: Object - Resub methods and plan (such as Prime)
client.on("resub", function (channel, username, months, message, userstate, methods) {
    // Do your stuff.
});

Roomstate

Triggered upon joining a channel. Gives you the current state of the channel.

Parameters:

  • channel: String - Channel name
  • state: Object - Current state of the channel
client.on("roomstate", function (channel, state) {
    // Do your stuff.
});

According to Twitch, the state object is always subject to change.

{
    'broadcaster-lang': null,
    'r9k': false,
    'slow': false,
    'subs-only': false,
    'channel': '#schmoopiie'
}

Serverchange

Channel is no longer located on this cluster. Read more

Parameters:

  • channel: String - Channel name
client.on("serverchange", function (channel) {
    // Do your stuff.
});

Slowmode

Channel enabled or disabled slow mode.

Parameters:

  • channel: String - Channel name
  • enabled: Boolean - Returns true if mode is enabled or false if disabled
  • length: Integer - Slow length value
client.on("slowmode", function (channel, enabled, length) {
    // Do your stuff.
});

Subscribers

Channel enabled or disabled subscribers-only mode.

Parameters:

  • channel: String - Channel name
  • enabled: Boolean - Returns true if mode is enabled or false if disabled
client.on("subscribers", function (channel, enabled) {
    // Do your stuff.
});

Subscription

Username has subscribed to a channel.

Parameters:

  • channel: String - Channel name
  • username: String - Username
  • method: Object - Methods and plan used to subscribe
  • message: String - Custom message
  • userstate: Object - Userstate
client.on("subscription", function (channel, username, method, message, userstate) {
    // Do your stuff.
});

Timeout

Username has been timed out on a channel.

Parameters:

  • channel: String - Channel name
  • username: String - Username
  • reason: String - Reason of the timeout can also be null
  • duration: Integer - Duration of the timeout
client.on("timeout", function (channel, username, reason, duration) {
    // Do your stuff.
});

Unhost

Channel ended the current hosting.

Parameters:

  • channel: String - Channel name
  • viewers: Integer - Viewer count
client.on("unhost", function (channel, viewers) {
    // Do your stuff.
});

Unmod

Someone got unmodded on a channel.

Important: It doesn’t detect if username got removed from moderators list. You will see a lot of mod / unmod events on a channel. When a moderator joins a channel, it will take a few seconds for jtv to give the user the moderator status. When leaving a channel, the user gets unmodded.

Parameters:

  • channel: String - Channel name
  • username: String - Username
client.on("unmod", function (channel, username) {
    // Do your stuff.
});

Whisper

Received a whisper. You won’t receive whispers from ignored users.

Parameters:

  • from: String - Username who sent the message
  • userstate: Object - Userstate object
  • message: String - Message received
  • self: Boolean - Message was sent by the client
client.on("whisper", function (from, userstate, message, self) {
    // Don't listen to my own messages..
    if (self) return;

    // Do your stuff.
});

According to Twitch, the userstate object is always subject to change.

{
    'badges': null,
    'color': '#FFFFFF',
    'display-name': 'Schmoopiie',
    'emotes': { '25': [ '0-4' ] },
    'message-id': '123',
    'thread-id': '1234567_12345678',
    'turbo': true,
    'user-id': '58355428',
    'user-type': null,
    'badges-raw': null,
    'emotes-raw': '25:0-4',
    'username': 'schmoopiie',
    'message-type': 'whisper'
}