{"id":17062020,"url":"https://github.com/brh55/botkit-discord","last_synced_at":"2025-10-16T15:07:53.161Z","repository":{"id":40585161,"uuid":"159723759","full_name":"brh55/botkit-discord","owner":"brh55","description":"🤖👾 A Botkit connector for Discord with support for text, voice, attachments, embedded messages, and more.","archived":false,"fork":false,"pushed_at":"2023-03-02T14:20:58.000Z","size":1195,"stargazers_count":37,"open_issues_count":17,"forks_count":8,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-04T08:51:17.449Z","etag":null,"topics":["botkit","botkit-connector","botkit-discord","chatbots","discord","discord-botkit","discord-js","nodejs-discord"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/brh55.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null},"funding":{"github":["brh55"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2018-11-29T20:31:24.000Z","updated_at":"2025-02-22T01:08:08.000Z","dependencies_parsed_at":"2024-02-01T20:08:12.521Z","dependency_job_id":null,"html_url":"https://github.com/brh55/botkit-discord","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/brh55/botkit-discord","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brh55%2Fbotkit-discord","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brh55%2Fbotkit-discord/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brh55%2Fbotkit-discord/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brh55%2Fbotkit-discord/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brh55","download_url":"https://codeload.github.com/brh55/botkit-discord/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brh55%2Fbotkit-discord/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279208705,"owners_count":26126647,"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","status":"online","status_checked_at":"2025-10-16T02:00:06.019Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["botkit","botkit-connector","botkit-discord","chatbots","discord","discord-botkit","discord-js","nodejs-discord"],"created_at":"2024-10-14T10:48:58.485Z","updated_at":"2025-10-16T15:07:53.106Z","avatar_url":"https://github.com/brh55.png","language":"JavaScript","funding_links":["https://github.com/sponsors/brh55"],"categories":[],"sub_categories":[],"readme":"# botkit-discord\n\n\u003e 🤖👾 A Botkit connector for Discord with support for text, voice, attachments, embedded messages, and more.\n\n[![Travis (.org)](https://img.shields.io/travis/brh55/botkit-discord.svg?style=flat-square)](https://travis-ci.org/brh55/botkit-discord) [![Coveralls branch](https://img.shields.io/coveralls/brh55/botkit-discord/master.svg?style=flat-square)](https://coveralls.io/github/brh55/botkit-discord) [![npm badge](https://img.shields.io/npm/dt/botkit-discord.svg?style=flat-square)](https://www.npmjs.com/package/botkit-discord)\n\n\nThis Botkit platform connector is intended to be used for Discord. Underneath the hood, this connector is utilizing [discord.js](https://github.com/discordjs/discord.js). Currently the connector supports the following features:\n\n- **Text:** DM Channel, Group DM Channel, Guild Text Message\n- **Voice:** Audio Playback and Joining Audio Channels\n- **Embedded Messages:** Visually rich messages\n- **File attachments:** Attach files to be downloaded by receiver\n- **Various Notifications:** Presences, Guild Member Add/Remove/Update, Guild Role Changes, Channel Add/Delete/Create\n\n![Example Gif](http://g.recordit.co/WzQ3XkJm5A.gif)\n\n## Install\n*Note: Minimum Node Requirement 8+, Recommended 10, and \u003e=10.10.0 if you use audio.*\n\n`$ npm install botkit-discord`\n\n## Basic Usage\n```javascript\nconst BotkitDiscord = require('botkit-discord');\nconst config = {\n    token: '**' // Discord bot token\n}\n\nconst discordBot = BotkitDiscord(config);\n\ndiscordBot.hears('hello','direct_message',(bot, message) =\u003e {\n    bot.reply(message, 'how goes there :)!');\n});\n\ndiscordBot.hears('.*', 'direct_mention', (bot, message) =\u003e {\n    bot.reply(message, 'leave me to be please.');\n});\n```\n\n## Advance Usage\n```javascript\nconst BotkitDiscord = require('botkit-discord');\nconst config = {\n    token: '**' // Discord bot token\n}\n\n// Let's join the user's voice channel if we receive a \"b!play\"\n// play a song and leave, get rating from user, and save result\n// if no rating is stored, we can end conversation\ndiscordBot.hears('b!play', 'ambient', async (bot, message) =\u003e {\n\ttry {\n\t\tconst connection = await bot.api.joinVoiceChannel();\n\t\tconst dispatcher = connection.playFile('/Users/brh55/Music/funny.mp3');\n\t\tdispatcher.setVolume(0.5)\n\t\tdispatcher.on('end', () =\u003e {\n\t\t\tbot.createConversation(message, (err, convo) =\u003e {\n\t\t\t\tconvo.addQuestion('How would rate that from a scale of 0 to 5?', (response, convo) =\u003e {\n\t\t\t\t\tconst numberRating = response.text.match(/[0-5]/g);\n\t\t\t\t\tif (numberRating.length \u003c 1) {\n\t\t\t\t\t\tconvo.say('Uhh... not a valid rating, try again later!');\n\t\t\t\t\t\tconvo.next();\n\t\t\t\t\t}\n\t\t\t\t\tconvo.say('Oh wow! Thanks for letting me know!');\n\t\t\t\t\tdb.save(message.member.id, numberRating[0]);\n\t\t\t\t\tconvo.next();\n\t\t\t\t});\n\t\t\t});\n\t\t\t// Leave at the end of the channel\n\t\t\tbot.api.leaveVoiceChannel();\n\t\t});\n\t} catch (e) {\n\t\t// If the user is not in a voice channel, tell them to join one\n\t\tbot.reply('Dude are you in voice channel?');\n\t});\n});\n```\n\n### Configuration\n  | Attribute   | Description                                                  | Type                     |\n  | ----------- | ------------------------------------------------------------ | ------------------------ |\n  | token       | Discord bot token                                            | String                   |\n  | replyToSelf | Enable the bot to reply to itself, by default this is turned off, but there may be circumstances when you want to allow that. | Boolean (Default: false) |\n\n### Example Projects\n- [Magic-8 Ball](https://github.com/brh55/discord-magic-8-ball)\n- [Pokedex Audio Discord Bot](https://github.com/brh55/pokedex-discord-bot) - Allows users to search for Pokemon through a Pokedex bot and plays the audio description in a voice channel. Read the [written tutorial](https://medium.com/@HimBrandon/discord-pok%C3%A9dex-chatbot-tutorial-part-1-b003b7decb5e)\n- [Glitch Examples](https://glitch.com/@glitch/discord)\n    - [Starter Kit for Glitch](https://glitch.com/~starter-discord) - Quickly deploy a Discord bot with easy to follow step-by-step instructions\n    - [Gritty Bot](https://glitch.com/~grittybot) - Using Giphy and sports API integration to provide fun and witty interactions\n    - [Bizbot](https://glitch.com/~bizbot-discord) - Uses Google Sheets to customize your bot, providing a easy way to allow people to contribute stuff to your bot without giving them access to the code\n\nRefer to [Botkit documentation](https://botkit.ai/docs/) to utilize all of the other Botkit features.\n\n## Events\nWhen you want your bot to respond to particular events that may be relevant, you can use the `.on` method.\n\n```javascript\ndiscordBot.on(EVENT_NAME, event =\u003e {\n    // do stuff\n});\n```\n\n### Incoming Events\n\n| Event          | Description                                                  |\n| -------------- | ------------------------------------------------------------ |\n| ambient        | a channel the bot is in has a new message                    |\n| direct_message | the bot received a direct message from a user                |\n| direct_mention | the bot was addressed directly in a channel (\"@bot hello\")   |\n| mention        | the bot was mentioned by someone in a message (\"hello @bot\") |\n\n ### Bot Activity Events\n\n| Event      | Description                             |\n| ---------- | --------------------------------------- |\n| disconnect | Bot has disconnected or failed to login |\n| ready      | Bot is connected                        |\n\n### Discord.js Events\n\nAlong with standard events, all Discord.js events have been migrated for your use. Please refer to the [docs](https://discord.js.org/#/docs/main/stable/class/Client?scrollTo=e-channelCreate) for usage.\n\nServer Greeting Referenced in [Docs](https://github.com/discordjs/discord.js/blob/stable/docs/examples/greeting.js)\n\n```js\ndiscordBot.on('guildMemberAdd', member =\u003e {\n  const channel = member.guild.channels.find(ch =\u003e ch.name === 'member-log');\n  if (!channel) return;\n  channel.send(`Welcome to the server, ${member}`);\n});\n```\n\n- \"channelCreate\"\n- \"channelDelete\"\n- \"channelPinsUpdate\"\n- \"channelUpdate\"\n- \"clientUserGuildSettingsUpdate\"\n- \"clientUserSettingsUpdate\"\n- \"debug\"\n- \"disconnect\"\n- \"emojiCreate\"\n- \"emojiDelete\"\n- \"emojiUpdate\"\n- \"error\"\n- \"guildBanAdd\"\n- \"guildBanRemove\"\n- \"guildCreate\"\n- \"guildDelete\"\n- \"guildMemberAdd\"\n- \"guildMemberAvailable\"\n- \"guildMemberRemove\"\n- \"guildMembersChunk\"\n- \"guildMemberSpeaking\"\n- \"guildMemberUpdate\"\n- \"guildUnavailable\"\n- \"guildUpdate\"\n- \"message\"\n- \"messageDelete\"\n- \"messageDeleteBulk\"\n- \"messageReactionAdd\"\n- \"messageReactionRemove\"\n- \"messageReactionRemoveAll\"\n- \"messageUpdate\"\n- \"presenceUpdate\"\n- \"rateLimit\"\n- \"ready\"\n- \"reconnecting\"\n- \"resume\"\n- \"roleCreate\"\n- \"roleDelete\"\n- \"roleUpdate\"\n- \"typingStart\"\n- \"typingStop\"\n- \"userNoteUpdate\"\n- \"userUpdate\"\n- \"voiceStateUpdate\"\n- \"warn\"\n\n## Audio/Voice Functionalities\nThis connector utilizes the built-in [`discord.js` audio functionality](https://discord.js.org/#/docs/main/stable/topics/voice), but requires additional steps to work properly:\n\n1. First install a desired audio enconder either `node-opus` or `opusscript` (discord.js recommends `node-opus` for performance reasons, but `opusscript` works for development purposes)\n    - `npm install node-opus` - *Requires \u003e= 10.10.0 Node*\n    - `npm install opusscript`\n2. Next install FFMPEG, you can choose any of the following methods:\n    1. (Mac) Install through homebrew: `brew update \u0026\u0026 brew install ffmpeg`\n    2. (Linux) Install through `apt update \u0026\u0026 apt install ffmpeg`\n    3. (All) [Download and install](https://ffmpeg.org/download.html) the binaries manually through the FFMPEG site\n\nFor convenience, you'll be able to use the voice functionality if the sender of the message is already in a voice channel. This will be available in the `.api` properties of the bot object passed as a parameter in the event handler.\n\n- `joinVoiceChannel()`\n- `leaveVoiceChannel()`\n\nExample Usage:\n```js\ndiscordBot.hears('!audio', 'ambient', (bot, message) =\u003e {\n    if (!bot.api.joinVoiceChannel) {\n       return bot.reply(message, 'I would if you were in a voice channel!');\n    }\n\n    bot.api.joinVoiceChannel().then(connection =\u003e {\n\t// Absolute path to local mp3 file\n        dispatcher = connection.playFile('/Users/jdoe1/projects/music-bot/assets/song.mp3')\n\tdispatcher.setVolume(0.5)\n\tdispatcher.on('end', () =\u003e {\n\t\tbot.api.leaveVoiceChannel();\n\t\tdispatcher.destroy();\n\t});\n     }).catch(err =\u003e {\n        console.log(`Failed to play audio: ${err}`);\n     });\n})\n```\n\n## Embeds\nTo use embeds, it's preferred to use the Discord.js RichEmbed builder, `discordBot.RichEmbed()`.\n\n![image](https://user-images.githubusercontent.com/6020066/55299068-0dc35780-53e6-11e9-9828-8676119e56a7.png)\n\n\n```js\ndiscordBot.hears('!rpg', ['direct_message', 'ambient'], (bot, message) =\u003e {\n\tconst embed = new discordBot.RichEmbed()\n\tembed.setAuthor(\n\t\t\"Quick RPG Stats\",\n\t\t\"https://rpglink.com/icon/here\"\n\t);\n\n\tembed.addField(\"Power Level 👊\", \"Equivalent to a Goblin Archer 🏹\");\n\tembed.addField(\"Skills Acquired 🥕\", \"🏹 Archery, 🍳 Cooking\");\n\tembed.setColor('GREEN');\n\tbot.reply(message, embed)\n});\n\n```\n\n## Atachments\nIt's recommended to use the attachment helper, `discordBot.Attachment`:\n\n![image](https://user-images.githubusercontent.com/6020066/55299122-4fec9900-53e6-11e9-9f8c-f4d235ff15a7.png)\n\n```js\ndiscordBot.hears('!file', ['direct_message', 'ambient'], (bot, message) =\u003e {\n\tconst attachment = new discordBot.Attachment('./temp.js', \"Awesome Script!\")\n\tbot.reply(message, attachment)\n});\n```\n\nHere is an example from the Pokedex Bot:\n\n![image](https://user-images.githubusercontent.com/6020066/65992753-af366f00-e444-11e9-918d-54f5502b6a8b.png)\n\n**Sample Code:**\n```js\nconst embed = new controller.RichEmbed();\nembed.setAuthor(\n\t\"Pokedex\",\n\t\"https://icon-library.net/images/pokedex-icon/pokedex-icon-15.jpg\" // Grabbing this icon from icon-library\n);\nembed.setTitle(formatName(result.name));\nembed.setDescription(`**No. ${result.id}** \\n **${result.types[0].type.name}**`);\nembed.setThumbnail(result.sprites.front_default);\nembed.addField(\"Weight\", formatWeight(result.weight));\nembed.addField(\"Height\", formatHeight(result.height));\nembed.setColor(\"GREEN\");\nembed.addField(\"Description\", result.description);\n\nbot.reply(message, embed);\n```\n\n## License\n\nⒸ MIT [Brandon Him / brh55](http://github.com/brh55)\n\nPlease let me know if you plan on forking or would like professional support. Open-source is a hobby, but it would be great as a full-time gig :)\n\nThis wouldn't be possible without all the tremendous effort and contributors behind [discord.js](https://github.com/discordjs/discord.js).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrh55%2Fbotkit-discord","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrh55%2Fbotkit-discord","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrh55%2Fbotkit-discord/lists"}