{"id":13758392,"url":"https://github.com/kritzware/twitch-bot","last_synced_at":"2025-04-09T08:13:03.072Z","repository":{"id":42654003,"uuid":"98824827","full_name":"kritzware/twitch-bot","owner":"kritzware","description":"🤖 Easily create chat bots for Twitch.tv ","archived":false,"fork":false,"pushed_at":"2023-01-11T07:49:01.000Z","size":450,"stargazers_count":149,"open_issues_count":18,"forks_count":36,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-10-30T08:53:23.008Z","etag":null,"topics":["chatbot","irc","javascript","kappa","nodejs","twitch","twitchbot"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/twitch-bot","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kritzware.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-07-30T21:06:38.000Z","updated_at":"2024-10-27T19:35:18.000Z","dependencies_parsed_at":"2023-02-09T02:15:15.516Z","dependency_job_id":null,"html_url":"https://github.com/kritzware/twitch-bot","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kritzware%2Ftwitch-bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kritzware%2Ftwitch-bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kritzware%2Ftwitch-bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kritzware%2Ftwitch-bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kritzware","download_url":"https://codeload.github.com/kritzware/twitch-bot/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247999864,"owners_count":21031046,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chatbot","irc","javascript","kappa","nodejs","twitch","twitchbot"],"created_at":"2024-08-03T13:00:29.258Z","updated_at":"2025-04-09T08:13:03.053Z","avatar_url":"https://github.com/kritzware.png","language":"JavaScript","readme":"# twitch-bot [![CircleCI](https://circleci.com/gh/kritzware/twitch-bot.svg?style=svg\u0026circle-token=3d338af28058e84dde13bee88751a50f55aefab3)](https://circleci.com/gh/kritzware/twitch-bot)\nEasily create chat bots for Twitch.tv\n\n## Install\nInstall via NPM\n```\n$ npm install twitch-bot\n```\n\n## Example\n```javascript\nconst TwitchBot = require('twitch-bot')\n\nconst Bot = new TwitchBot({\n  username: 'Kappa_Bot',\n  oauth: 'oauth:dwiaj91j1KKona9j9d1420',\n  channels: ['twitch']\n})\n\nBot.on('join', channel =\u003e {\n  console.log(`Joined channel: ${channel}`)\n})\n\nBot.on('error', err =\u003e {\n  console.log(err)\n})\n\nBot.on('message', chatter =\u003e {\n  if(chatter.message === '!test') {\n    Bot.say('Command executed! PogChamp')\n  }\n})\n\n```\n\n## Index\n- [Events](https://github.com/kritzware/twitch-bot#events)\n  - [`connected`](https://github.com/kritzware/twitch-bot#connected---)\n  - [`join`](https://github.com/kritzware/twitch-bot#join---)\n  - [`part`](https://github.com/kritzware/twitch-bot#part---)\n  - [`message`](https://github.com/kritzware/twitch-bot#message---chatter-object)\n  - [`timeout`](https://github.com/kritzware/twitch-bot#timeout---event-object)\n  - [`subscription`](https://github.com/kritzware/twitch-bot#subscription---event-object)\n  - [`ban`](https://github.com/kritzware/twitch-bot#ban---event-object)\n  - [`error`](https://github.com/kritzware/twitch-bot#error---err-object)\n  - [`close`](https://github.com/kritzware/twitch-bot#close---)\n- [Methods](https://github.com/kritzware/twitch-bot#methods)\n  - [`join()`](https://github.com/kritzware/twitch-bot#join-channelname--string))\n  - [`part()`](https://github.com/kritzware/twitch-bot#part-channelname--string)  \n  - [`say()`](https://github.com/kritzware/twitch-bot#saymessage-string-err-callback)\n  - [`timeout()`](https://github.com/kritzware/twitch-bot#timeoutusername-string-duration-int-reason-string)\n  - [`ban()`](https://github.com/kritzware/twitch-bot#banusername-string-reason-string)\n  - [`close()`](https://github.com/kritzware/twitch-bot#close)\n- [Tests](https://github.com/kritzware/twitch-bot#running-tests)\n\n## Events\n### `connected - ()`\nThis event is emitted when the bot has connected to the IRC server.\n#### Usage\n```javascript\nBot.on('connected', () =\u003e ... )\n```\n\n### `join - ()`\nThis event is emitted when a channel has been joined successfully.\n#### Usage\n```javascript\nBot.on('join', channel =\u003e ... )\n```\n\n### `part - ()`\nThis event is emitted when a channel has been left successfully.\n#### Usage\n```javascript\nBot.on('part', channel =\u003e ... )\n```\n\n\n### `message - (chatter: Object)`\nEmitted when a `PRIVSMSG` event is sent over IRC. Chatter object attributes can be found on the [Twitch developers site](https://dev.twitch.tv/docs/v5/guides/irc/#privmsg-twitch-tags)\n\n#### Usage\n```javascript\nBot.on('message', chatter =\u003e ... )\n```\n\n#### Example Response\n```javascript\n{ color: '#3C78FD',\n  display_name: 'kritzware',\n  emotes: '88:18-25',\n  id: 'c5ee7248-3cea-43f5-ae44-2916d9a1325a',\n  mod: true,\n  room_id: 44667418,\n  sent_ts: 1501541672959,\n  subscriber: true,\n  tmi_sent_ts: 1501541673368,\n  turbo: false,\n  user_id: 44667418,\n  user_type: 'mod',\n  badges: { broadcaster: 1, subscriber: 0 },\n  channel: '#kritzware',\n  message: 'This is a message PogChamp',\n  username: 'Kritzware' }\n  ```\n\n### `timeout - (event: Object)`\nEmitted when a user is timed out in the chat. The `ban_reason` attribute is `null` when no reason message is used.\n\n#### Chat Trigger\n```javascript\nkritzware: \"/timeout {user} {duration} {reason}\"\n```\n\n#### Usage\n```javascript\nBot.on('timeout', event =\u003e ... )\n```\n\n#### Example Response\n```javascript\n{ ban_duration: 10, // seconds\n  ban_reason: 'Using a banned word',\n  room_id: 44667418,\n  target_user_id: 37798112,\n  tmi_sent_ts: 1503346029068,\n  type: 'timeout',\n  channel: '#kritzware',\n  target_username: 'blarev' }\n```\n\n### `subscription - (event: Object)`\nEmitted when a user subscribes to a channel and chooses to share the subscription in chat.\n\n#### Usage\n```javascript\nBot.on('subscription', event =\u003e ... )\n```\n\n#### Example Response\n```javascript\n{\n  \"badges\": {\n   \"broadcaster\": 1,\n   \"staff\": 1,\n   \"turbo\": 1\n  },\n  \"channel\": \"#dallas\",\n  \"color\": \"#008000\",\n  \"display_name\": \"ronni\",\n  \"emotes\": null,\n  \"id\": \"db25007f-7a18-43eb-9379-80131e44d633\",\n  \"login\": \"ronni\",\n  \"message\": \"Great stream -- keep it up!\", // null if no message given\n  \"mod\": 0,\n  \"msg_id\": \"resub\",\n  \"msg_param_months\": 6,\n  \"msg_param_sub_plan\": \"Prime\",\n  \"msg_param_sub_plan_name\": \"Prime\",\n  \"room_id\": 1337,\n  \"subscriber\": 1,\n  \"system_msg\": \"ronni has subscribed for 6 months!\",\n  \"tmi_sent_ts\": 1507246572675,\n  \"turbo\": 1,\n  \"user_id\": 1337,\n  \"user_type\": \"staff\"\n}\n```\n\n### `ban - (event: Object)`\nEmitted when a user is permanently banned from the chat. The `ban_reason` attribute is `null` when no reason message is used.\n\n#### Usage\n```javascript\nBot.on('ban', event =\u003e ... )\n```\n\n#### Chat Trigger\n```javascript\nkritzware: \"/ban {user} {reason}\"\n```\n\n#### Example Response\n```javascript\n{ ban_reason: 'Using a banned word',\n  room_id: 44667418,\n  target_user_id: 37798112,\n  tmi_sent_ts: 1503346078025,\n  type: 'ban',\n  channel: '#kritzware',\n  target_username: 'blarev' }\n```\n\n### `error - (err: Object)`\nEmitted when any errors occurs in the Twitch IRC channel, or when attempting to connect to a channel.\n\n#### Error types\n##### `Login authentication failed`\nThis error occurs when either your twitch username or oauth are incorrect/invalid.\n\nResponse:\n```javscript\n{ message: 'Login authentication failed' }\n```\n\n##### `Improperly formatted auth`\nThis error occurs when your oauth password is not formatted correctly. The valid format should be `\"oauth:your-oauth-password-123\"`.\n\nResponse:\n```javscript\n{ message: 'Improperly formatted auth' }\n```\n\n##### `Your message was not sent because you are sending messages too quickly`\nThis error occurs when a message fails to send due to sending messages too quickly. You can avoid this by making the bot a moderator in the channel, if applicable/allowed.\n\nResponse:\n```javascript\n{ message: 'Your message was not sent because you are sending messages too quickly' }\n```\n\n#### Usage\n```javascript\nBot.on('error', err =\u003e ... )\n```\n\n#### Example Response\n```javascript\n{ message: 'Some error happened in the IRC channel' }\n```\n\n### `close - ()`\nThis event is emitted when the irc connection is destroyed via the `Bot.close()` method.\n#### Usage\n```javascript\nBot.on('close', () =\u003e {\n  console.log('closed bot irc connection')\n})\n```\n\n## Methods\n### `join(channel: String)`\nAttempts to join a channel. If successful, emits the 'join' event.\n\n#### Example\n```javascript\nBot.on('join', channel =\u003e {\n  console.log(`Bot joined ${channel}`)\n})\nBot.join('channel2')\n```\n\n### `part(channel: String)`\nAttempts to part from a channel. If successful, emits the 'part' event.\n\n#### Example\n```javascript\nBot.on('part', channel =\u003e {\n  console.log(`Bot left ${channel}`)\n})\nBot.part('channel2')\n```\n\n### `say(message: String, channel: []Channel, err: Callback)`\nSend a message in the currently connected Twitch channel. `channels` parameter not needed when connected to a single channel. An optional callback is provided for validating if the message was sent correctly.\n\n#### Example\n```javascript\nBot.say('This is a message')\n\nBot.say('Pretend this message is over 500 characters', err =\u003e {\n  sent: false,\n  message: 'Exceeded PRIVMSG character limit (500)'\n  ts: '2017-08-13T16:38:54.989Z'\n})\n\n// If connected to multiple channels\nBot.say('message to #channel1', 'channel1')\nBot.say('message to #channel2', 'channel2')\n```\n\n### `timeout(username: String, channel: []Channel, duration: int, reason: String)`\nTimeout a user from the chat. `channels` parameter not needed when connected to a single channel. Default `duration` is 600 seconds. Optional `reason` message.\n\n#### Example\n```javascript\nBot.timeout('kritzware', 10)\n// \"kritzware was timed out for 10 seconds\"\n\nBot.timeout('kritzware', 5, 'Using a banned word')\n// \"kritzware was timed out for 5 seconds, reason: 'Using a banned word'\"\n\nBot.on('message', chatter =\u003e {\n  if(chatter.message === 'xD') Bot.timeout(chatter.username, 10)\n})\n```\n\n### `ban(username: String, reason: String)`\nPermanently ban a user from the chat. `channels` parameter not needed when connected to a single channel. Optional `reason` message.\n\n#### Example\n```javascript\nBot.ban('kritzware')\n// \"kritzware is now banned from the room\"\n\nBot.timeout('kritzware', 'Using a banned word')\n// \"kritzware is now banned from the room, reason: 'Using a banned word'\"\n\nBot.on('message', chatter =\u003e {\n  if(chatter.message === 'Ban me!') Bot.ban(chatter.username)\n})\n```\n\n### `close()`\nCloses the Twitch irc connection. Bot will be removed from the Twitch channel AND the irc server.\n\n#### Example\n```javascript\nBot.close()\n```\n\n## Running Tests\nRunning 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:\n```javascript\nTWITCHBOT_USERNAME=mod_username\nTWITCHBOT_OAUTH=oauth:mod-oauth-token\nTWITCHBOT_CHANNEL=mod_channel\nTWITCHBOT_USERNAME_NON_MOD=non_mod_username\nTWITCHBOT_OAUTH_NON_MOD=oauth:non-mod-oauth-token\nTWITCHBOT_CHANNEL_NON_MOD=mod_channel\n```\nTo run the tests (powered with [Mocha](https://mochajs.org/)), use the following command:\n```bash\nyarn test\n```\n","funding_links":[],"categories":["Libraries"],"sub_categories":["JavaScript (Node.js)"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkritzware%2Ftwitch-bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkritzware%2Ftwitch-bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkritzware%2Ftwitch-bot/lists"}