YouTube Connector
The YouTube module and connector provide:
- A notification service that watches YouTube channels and users upload new videos (or update their titles and descriptions) and posts to one or more of the webhooks configured in your Discord server.
Note
A separate set of lookup commands (searching for a channel, a video, or videos matching a search string, or posting a search result's link) was retired with no replacement.
A YouTube channel identifier can be:
- The channel ID, usually the
XXXXXXpart of the YouTube URLhttps://www.youtube.com/channel/XXXXXXXXXXXXXXXXXXXXXXXX. - The channel's name (or handle), usually the
YYYYYYpart of the YouTube URLhttps://www.youtube.com/YYYYYYYYYY(sometimes prepended with a@). - The channel's display name, usually the name you see above the username of the YouTube user on the channel's home page.
See also
A step-by-step walkthrough: Configuring a Social Connector.
YouTube Notifications
See also
The connector posts through Discord webhooks, so you need to know how they work. See this official guide for an introduction.
By default each notification is posted with the YouTube channel name as author and the YouTube channel thumbnail as the Discord profile picture. You can customize these settings and others for each stream.
The YouTube video URL goes to Discord, and the video preview uses Discord's own parsing of YouTube content.
Managing YouTube notifications
You add, edit, remove and list YouTube notification services from your server's YouTube page on this dashboard; there is no Discord command for it any more.
When you add a notification service you pick the YouTube channel and the channel to post to, and the dashboard creates the Discord webhook for you (this needs GiselleBot to have "Manage Webhooks" permission in that channel). The customization options below are fields on the service's form.
Customization options
NSFW handling
YouTube marks some videos as "age-restricted content". The module treats those videos as "NSFW" in the notifications stream.
The NSFW setting has 3 modes:
- censor posts a NSFW URL wrapped in
< >angle brackets, which stops Discord from auto-embedding it. - skip drops NSFW-flagged items.
- only posts NSFW-flagged items and skips everything else, uncensored. Use it for a second, NSFW-only stream alongside a clean one.
Default: false (both SFW and NSFW items are posted uncensored), or censor if the NSFW option is enabled without picking a specific mode.
Keyword filtering
Adds a whitelist filter. If the video title contains first word and/or (see below) second word, the notification goes to the webhook; otherwise it is ignored. Enter a comma-separated list on the YouTube page's Filter Words field, case-insensitive - a multi-word phrase is just its own comma-separated entry, no quoting needed.
The filter works on partial words (e.g. "announce" will work on both "announcement" and "announced").
Default: No filter
Filter match mode
Sets how the whitelist behaves when it has more than 1 word.
ANDwill only allow YouTube videos whose title contains all of the filtered words.ORwill allow YouTube videos whose title contains at least one of the filtered words.
Default: OR
Include vs. exclude filtering
Sets whether the filter includes or excludes the words.
- Include will only allow YouTube videos whose title contains the filtered word(s).
- Exclude will only allow YouTube videos whose title does not contain the filtered word(s).
Combined with the filter match mode, this lets the connector include a video when at least one filter item matches in its title (OR) or all do (AND), or exclude on the same logic: post when all items are absent from the title (AND) or when at least one is absent (OR).
Default: Include
Note
Include takes priority over Exclude, but the form only lets you pick one.
Custom header message
Sets the message template used when notifications are posted. Custom headers take at most 1024 characters.
Custom headers are plain text. For a formatted card, fill in the Embed Header fields on the feed's page instead: title, description, colour, image, thumbnail, footer and author. When any of them is set, the item is posted as an embed instead of plain text.
Placeholders (such as %title% or %author%) work in every embed field, and a title containing quotes or special characters is posted exactly as written. The old "embed JSON" syntax that broke on special characters is no longer needed or documented. If a feed still carries an old JSON header, its page shows the saved value with a note and the embed fields to replace it.
Custom headers support these dynamic tags, replaced at run time:
- %title%: the YouTube video title.
- %channel%: the YouTube channel name.
- %duration%: the YouTube video duration.
- %timestamp% or %timestamp_utc%: the video upload time in UTC, with format
YYYY-MM-DD HH:mm:ss (UTC). - %timestamp_iso%: the video upload time in UTC, as an ISO8601 string.
- %timestamp_pst%: the video upload time in PST, with format
YYYY-MM-DD HH:mm:ss (PST). - %url%: the YouTube video URL. See below for more info.
Timestamp tags accept a custom time zone. Replace the utc part with either:
A different valid IANA time zone identifier (e.g. America/New_York, Europe/London).
An UTC offset in the form
[UTC/GMT](+/-)(hours)[:][minutes], for example:- %timestamp_Europe/London%
- %timestamp_America/Los_Angeles%
- %timestamp_Japan%
- %timestamp_PST8PDT%
- %timestamp_+0800%
- %timestamp_-10:30%
- %timestamp_UTC+2%
Without %url%, the YouTube video URL is appended after every header on a new line, and Discord renders it.
If the %url% parameter is used, the default URL will not be appended to the custom header.
Four more placeholders are replaced with their value when it is available and deleted when it is not:
- %description%: the video description, if present and not empty (truncated at 1024 characters).
- %short_description%: a shorter version of the video description, if present and not empty (truncated at 256 characters).
- %tags%: a space-delimited list of the video's tags, if at least one tag is applied. Each tag is surrounded by
``characters. - %thumbnail%: the direct URL of the video thumbnail, unless the thumbnail is absent (this should not happen, but might for unknown reasons).
Default: %channel% just %video_status% a video! followed by the video Title, Description, Duration and Tags
Custom webhook name
Sets a custom username on the webhook when notifications are posted. Custom usernames take at most 32 characters.
Default: Notifications are posted by a webhook named after the YouTube channel
Keep the webhook's default username
Removes any custom name from the webhook. The real webhook name (the one you assigned when creating the webhook in Discord) will be used.
Default: false (Custom or automated names will be applied)
Keep the webhook's default avatar
Removes any custom avatar from the webhook. The real webhook avatar (the one you assigned when creating the webhook in Discord) will be used.
Default: false (Automated avatars will be applied)
Permissions needed on the dashboard: Manage Webhooks (server-side)
Editing a notification service
Editing a service on the YouTube page replaces all of its customization options with what you set in the edit form. It is not a partial update, so check its current settings before you change them.
Removing a notification service
Removing a service on the YouTube page stops it and removes its link to the server webhook.
Listing notification services
The YouTube page lists every notification service currently linked to a webhook in the server.