search

CyaOnDaNet / plex_discord_role_management

A discord bot that synchronizes with Tautulli and Sonarr to deliver tailored notifications.
MIT License
22 stars 6 forks source link

readme

alt text Plex-Discord Role Management and Notifier Bot

Pre-Installation Steps

  1. Make sure you have Tautulli and Sonarr setup.
  2. Get a Discord Bot Token. To do that go here: https://discordapp.com/developers/applications/me
    1. Log in or create an account
    2. Click New Application
    3. Fill in an Application Name and click create.
    4. This will bring you to the General Information section, enter in a description and upload an app icon if you want.
    5. Go to the Bot section in the settings sidebar. Next to Build-A-Bot, click the Add Bot button.
      • Scroll down to the Privileged Gateway Intents section.
      • Check the box for SERVER MEMBERS INTENT
      • Check the box for PRESENCE INTENT <- (Optional Step! The bot does not use this yet but if you enable it now and I use it later you won't have to worry.)
      • Click Save Changes on the bottom of the page.
    6. At the top of the Bot section in the settings sidebar, click the button that says Click to Reveal Token. Copy this and keep it safe for later, this is your Bot Token.
  3. Once you have created your bot, you'll need to authorize your bot on a server you have administrative access to. For documentation, you can read: https://discordapp.com/developers/docs/topics/oauth2#bots. The steps are as follows:
    1. Go to https://discordapp.com/api/oauth2/authorize?client_id=[CLIENT_ID]&permissions=8&scope=bot where [CLIENT_ID] is the Discord App Client ID found under the OAuth2 section in the settings sidebar
    2. Select Add a bot to a server and select the server to add it to
    3. Click Authorize
    4. You should now see your bot in your server listed as Offline

Important Note for existing users who upgrade from bot v1.x.x to v2.0.0 and higher.

With discord.js v12, privileged gateway intents for server members were introduced. What this means for you is that the @Watching role will no longer work until you edit your bot to have the server members intent. The instructions to do so are below:

  1. Login to the Discord Developer Portal
  2. Go to Applications in the sidebar.
  3. Find this bot and click on it.
  4. Click on Bot under the settings sidebar.
  5. Look for the Privileged Gateway Intents section.
  6. Check the box for SERVER MEMBERS INTENT
  7. Check the box for PRESENCE INTENT <- (Optional Step! The bot does not use this yet but if you enable it now and I use it later you won't have to worry.)
  8. Click Save Changes on the bottom of the page.
  9. Restart the bot to ensure changes take effect.

Important Note about Configuration

If you have changed your webroot of Sonarr or Tautulli, leave the sonarr_port and or tautulli_port fields blank. Specify the entire base URL in the ip section instead. So for example, if you normally access Tautulli at http://192.168.0.101:8181/tautulli/home instead of the default http://192.168.0.101:8181/home, enter 192.168.0.101:8181/tautulli as the tautulli_ip and leave the tautulli_port field blank. Also, if you access Sonarr or Tautulli with TLS encryption, specify https:// in the beginning of the ip field.

Important Note about Images

If you want to have images included in your Discord notifications, image hosting must be enabled in Tautulli. Go to Settings > 3rd Party APIs and select an option from the Image Host drop down. 

Normal Installation

  1. Install Node.js: https://nodejs.org/
  2. Clone the repo or download a zip and unpackage it.
  3. Navigate to the root folder and in the console, type npm install
    • You should see packages beginning to install
  4. Make a copy of config/config.example.json and save it as config.json in the same config directory.
  5. Take your bot token from the Pre-Installation section and enter it into config/config.json.
  6. Inside the config/config.json file, replace the placeholders with your Tautulli and Sonarr information. The node_hook_ip and node_hook_port are referring to the machine running this bot so tautulli knows where to send webhooks. The node_hook_port can be any available open port.
  7. Once you have the config set up correctly, it is time to bring your bot Online. Navigate to the root of the app (where index.js is located) and in your console, type node index.js
    • This will start your server. The console will need to be running for the bot to run.

If I am missing any steps, feel free to reach out or open an issue/bug in the Issues for this repository.

Docker Installation

docker run -d \
  --name='plex_discord_role_management' \
  -e TZ=<timezone> \
  -e 'botToken'='YOUR_DISCORD_BOT_TOKEN' \
  -e 'defaultPrefix'='!' \
  -e 'node_hook_ip'='THE_IP_ADDRESS_OF_THE_HOST_MACHINE' \
  -e 'node_hook_port'='YOUR_HOST_PORT' \
  -e 'tautulli_ip'='YOUR_TAUTULLI_IP_ADDRESS' \
  -e 'tautulli_port'='YOUR_TAUTULLI_PORT' \
  -e 'tautulli_api_key'='YOUR_TAUTULLI_API_KEY' \
  -e 'sonarr_ip'='YOUR_SONARR_IP_ADDRESS' \
  -e 'sonarr_port'='YOUR_SONARR_PORT' \
  -e 'sonarr_api_key'='YOUR_SONARR_API_KEY' \
  -e 'sonarr_ip_2'='OPTIONAL_ADDITIONAL_SONARR_IP_ADDRESS' \
  -e 'sonarr_port_2'='OPTIONAL_ADDITIONAL_SONARR_PORT' \
  -e 'sonarr_api_key_2'='OPTIONAL_ADDITIONAL_SONARR_API_KEY' \
  -e 'sonarr_ip_3'='OPTIONAL_ADDITIONAL_SONARR_IP_ADDRESS' \
  -e 'sonarr_port_3'='OPTIONAL_ADDITIONAL_SONARR_PORT' \
  -e 'sonarr_api_key_3'='OPTIONAL_ADDITIONAL_SONARR_API_KEY' \
  -e 'DEBUG_MODE'='0' \
  -p 'YOUR_HOST_PORT:3000/tcp' \
  -v '/PATH/TO/YOUR/HOST/APPDATA':'/app/config':'rw'   \
  cyaondanet/plex_discord_role_management:latest

Usage

  1. This bot allows a mentionable Role to be set as a watching role for users. It gets auto-assigned during playback and removed when playback ends. This is useful for other notifications, like if you need to reboot the Plex server you can ping @watching so they know it's not a problem on their end. To use this feature, the Discord account must be linked to the plex username with !link @DiscordUser PlexUsername.

  2. The second usage for this bot is getting relevant recently added notifications. All recently added movies and TV shows are filtered through the bot to add their respective @mentions and then sent in the specified channel. A user chooses their respective notification settings by clicking on emojis and receiving a react-role from the bot. A library can be excluded with the !notifications library command, like with a 4k library that most or all of the other users don't have access to.

Getting Started

  1. After all cofiguration settings have been applied, the bot has been invited to the server, and the bot is online with no errors in the console; you are ready to configure its discord settings. First off, if you want to change the prefix, do it with !bot prefix newprefix where newprefix is the actual new prefix.

  2. In some sort of Admin only channel, do all the following stuff until the last step. We want to run !link @DiscordUser PlexUsername for every user in the server, you can verify the settings with !linklist and use !unlink @DiscordUser to unlink someone. If you don't know the exact spelling of someone's plex username, the command !users will pull a list for you. Now create a Watching Role in Discord and make sure the Mentionable box is ticked. Run this command with the Role you just created !role @WatchingRole. If you want to see if its working, run !notify and setup the logchannel to get a log of the auto-assigning of the role. Run !notify again if you want to disable logging.

  3. Run the !notifications edit command to setup some notification preferences now. If you have any custom Discord Roles you would like to be React-Roles (so users can opt in and out of them) use the !notifications custom add @mentionedRole Optional Description command. Run !notifications library to exclude any Plex libraries from recently added notifications.

  4. Test the Sonarr connection and generate the database with !notifications preview. A database with all shows on Sonarr was just created but only continuing (airing) shows automatically received a discord Role. Now you can edit this list with !notifications exclude show or !notifications include show. You can even group or ungroup common shows with !notifications group New Group Name for Shows [show1] [show2] [etc.] and !notifications ungroup [show1] [show2] [etc.]. You can re-call !notifications preview to see your changes and once you are satisfied with this list you can continue onto the final step.

  5. Finally, you should setup a #notifications channel and a #notifications_settings channel in Discord. In the channel permissions, non-Admin users should be able to read these messages but not be able to send anything. Also, default server notification settings should be set to @mentions only so people are not spammed by #notifications but rather only get notifications on things they want. Use !notify in the desired #notifications channel and select the emoji option corresponding with Content Notifications to set the bots recently added notification alerts to go to the current channel. Head over to #notification_settings channel and type !notifications list to generate all the React-Role embeds. You are now done, and people can receive show specific notifications in your Discord Server!

Discord Bot Commands

To Do: