/twitch-bot

Easily create chat bots for Twitch.tv

Primary LanguageJavaScriptMIT LicenseMIT

twitch-bot CircleCI

Easily create chat bots for Twitch.tv

Install

Install via NPM

$ npm install twitch-bot

Example

const TwitchBot = require('twitch-bot')

const Bot = new TwitchBot({
  username: 'Kappa_Bot',
  oauth: 'oauth:dwiaj91j1KKona9j9d1420',
  channel: 'twitch'
})

Bot.on('join', () => {

  Bot.on('message', chatter => {
    if(chatter.message === '!test') {
      Bot.say('Command executed! PogChamp')
    }
  })
})

Bot.on('error', err => {
  console.log(err)
})

Index

Events

join - ()

This event is emitted when a connection has been made to the the channel

Usage

Bot.on('join', () => ... )

message - (chatter: Object)

Emitted when a PRIVSMSG event is sent over IRC. Chatter object attributes can be found on the Twitch developers site

Usage

Bot.on('message', chatter => ... )

Example Response

{ color: '#3C78FD',
  display_name: 'kritzware',
  emotes: '88:18-25',
  id: 'c5ee7248-3cea-43f5-ae44-2916d9a1325a',
  mod: true,
  room_id: 44667418,
  sent_ts: 1501541672959,
  subscriber: true,
  tmi_sent_ts: 1501541673368,
  turbo: false,
  user_id: 44667418,
  user_type: 'mod',
  badges: { broadcaster: 1, subscriber: 0 },
  channel: '#kritzware',
  message: 'This is a message PogChamp',
  username: 'Kritzware' }

timeout - (event: Object)

Emitted when a user is timed out in the chat. The ban_reason attribute is null when no reason message is used.

Chat Trigger

kritzware: "/timeout {user} {duration} {reason}"

Usage

Bot.on('timeout', event => ... )

Example Response

{ ban_duration: 10, // seconds
  ban_reason: 'Using a banned word',
  room_id: 44667418,
  target_user_id: 37798112,
  tmi_sent_ts: 1503346029068,
  type: 'timeout',
  channel: '#kritzware',
  target_username: 'blarev' }

ban - (event: Object)

Emitted when a user is permanently banned from the chat. The ban_reason attribute is null when no reason message is used.

Usage

Bot.on('ban', event => ... )

Chat Trigger

kritzware: "/ban {user} {reason}"

Example Response

{ ban_reason: 'Using a banned word',
  room_id: 44667418,
  target_user_id: 37798112,
  tmi_sent_ts: 1503346078025,
  type: 'ban',
  channel: '#kritzware',
  target_username: 'blarev' }

error - (err: Object)

Emitted when any errors occurs in the Twitch IRC channel, or when attempting to connect to a channel.

Error types

Login authentication failed

This error occurs when either your twitch username or oauth are incorrect/invalid.

Response:

{ message: 'Login authentication failed' }
Improperly formatted auth

This error occurs when your oauth password is not formatted correctly. The valid format should be "oauth:your-oauth-password-123".

Response:

{ message: 'Improperly formatted auth' }

Usage

Bot.on('error', err => ... )

Example Response

{ message: 'Some error happened in the IRC channel' }

close - ()

This event is emitted when the irc connection is destroyed via the Bot.close() method.

Usage

Bot.on('close', () => {
  console.log('closed bot irc connection')
})

Methods

say(message: String, err: Callback)

Send a message in the currently connected Twitch channel. An optional callback is provided for validating if the message was sent correctly.

Example

Bot.say('This is a message')

Bot.say('Pretend this message is over 500 characters', err => {
  sent: false,
  message: 'Exceeded PRIVMSG character limit (500)'
  ts: '2017-08-13T16:38:54.989Z'
})

timeout(username: String, duration: int, reason: String)

Timeout a user from the chat. Default duration is 600 seconds. Optional reason message.

Example

Bot.timeout('kritzware', 10)
// "kritzware was timed out for 10 seconds"

Bot.timeout('kritzware', 5, 'Using a banned word')
// "kritzware was timed out for 5 seconds, reason: 'Using a banned word'"

Bot.on('message', chatter => {
  if(chatter.message === 'xD') Bot.timeout(chatter.username, 10)
})

ban(username: String, reason: String)

Permanently ban a user from the chat. Optional reason message.

Example

Bot.ban('kritzware')
// "kritzware is now banned from the room"

Bot.timeout('kritzware', 'Using a banned word')
// "kritzware is now banned from the room, reason: 'Using a banned word'"

Bot.on('message', chatter => {
  if(chatter.message === 'Ban me!') Bot.ban(chatter.username)
})

close()

Closes the Twitch irc connection. Bot will be removed from the Twitch channel AND the irc server.

Example

Bot.close()

Running Tests

Running the test suite requires at least two twitch accounts, one moderator account and one normal account. The channel used must be the same - This is so timeout/ban methods can be tested with the mod account. Using these two accounts, set the following environment variables:

TWITCHBOT_USERNAME=mod_username
TWITCHBOT_OAUTH=oauth:mod-oauth-token
TWITCHBOT_CHANNEL=mod_channel
TWITCHBOT_USERNAME_NON_MOD=non_mod_username
TWITCHBOT_OAUTH_NON_MOD=oauth:non-mod-oauth-token
TWITCHBOT_CHANNEL_NON_MOD=mod_channel

To run the tests (powered with Mocha), use the following command:

yarn test