Welcome to CouchBot’s documentation!¶
Overview¶
You’ve seen other bots like this I’m sure - Have Discord server, setup bot, bot announces when you go live. But do other bots have loose springs? Maybe a nacho cheese stain or two? And what is that smell..?? Yes, that is unique.
Getting Started¶
Quick Start
You can jump straight into the Requirements
CouchBot’s main feature set includes:
- Stream Announcing (across all major streaming platforms)
- Role Hoisting
- Greeting/Welcome Message (fully configurable)
- Custom Live Messages (Twitch, Youtube, Picarto, Steam, Trovo, Glimesh & Theta.tv)
- Beautiful Embeds
- VOD Publishing
- Seperate announcements for owners!
- Automatic Twitch announcements when going live
- Can configure the offline message or delete the announcement once finished!
Platforms Supported¶
Let your Discord community know when you go live! Want to let your friends know when you publish a new YouTube Video? Want to make a list of your favorite streamers, and get notified when they go live? CouchBot does that too!
In order to have CouchBot in your server, you should follow these instructions;
- Sign up to CouchBot on Patreon
- Link Patreon to your Discord account.
- Join the Support Server to whitelist your active servers.
Note
You must have the Manage Server permission to invite CouchBot to a server.
Patreon Commands¶
In order to have CouchBot stay on your server, you will need to sign up to Patreon and Whitelist your server. Click here to see how to get your ServerID. To do this follow the guide below;
Note
These commands are applicable only to people who have an active Patreon subscription.
| Name | Example | Usage |
| patreon | !cb patreon |
Shows you allowance and servers added. |
| patreon addserver | !cb patreon addserver 123456789 |
Adds a server to your account. |
| patreon removeserver | !cb patreon removeserver 123456789 |
Removes a server from your account. |
The command(s) below is only applicable to specific Patreon tiers;
| Name | Example | Usage |
| ping | !cb ping Look at my cool ping! |
Sets your ping response to « Look at my cool ping! » |
Example Setup¶
In these scenarios, we have already followed the Basic Configuration and have the correct Permission structure.
We will use MattTheDev as the streamer account and #notification as the Discord channel to announce in.
Scenario 1¶
Scenario 1
Announcing only the Server Owner going Live with an everyone ping.
A lot of people just want a bot to announce them going live. CouchBot can do this! We start by allowing the bot to announce live streams then adding our creator. We then tell the bot to ping the everyone role and allow it to do so.
!cb allow live
!cb twitch MattTheDev #notification "The Dev is going live @everyone"
Scenario 2¶
Scenario 2
Announcing people automatically without adding individually.
Rather than adding people manually one by one, you can have the bot automatically pick up people in your server. This drastically reduces the setup time and eases the setup process for you. First, you allow the bot to push live announcements then set the default channel. Then tell it to find anyone with the streaming status and your done!
Prudence
The streamer has to have the status « Streaming » to be automatically announced.
!cb allow live
!cb channel live #notification
!cb allow livediscovery all
Scenario 3¶
Scenario 3
Automatically announce a specific role going live
Let’s say you want anyone with the role VIP to be automatically announced. To do this, you would allow the bot to push Live and tell it the channel it should be posting in. All that’s left to do is tell it what role it should announce as live!
Prudence
The streamer has to have the status « Streaming » to be automatically announced.
!cb allow live
!cb channel live #notification
!cb allow livediscovery role @VIP
Scenario 4¶
Scenario 4
Owner announced separately from anyone else
Some servers may with to have the owner or other « VIP » types announced seperatly from the rest. To accomplish this we allow live then add the streamers as needed specifiying the channel they should be announced in.
!cb allow live
!cb twitch MattTheDev #ownerchannel
!cb twitch Jaymei #otherchannel
Scenario 5¶
Scenario 5
YouTube VOD and Live announcements to different channels
We start by allowing the bot to push both live and published content. As the commands are a toggle it will respond with the new setting. We then add the youtube channel using it’s « ChannelID » and specify the channel it should post to along with whether we want it to be Live or VOD. It is also possible to leave blank for them to go the the same channel or use the argument « both ».
!cb allow live
!cb allow published
!cb youtube UC123456 #livechannel live
!cb youtube UC123456 #publishedchannel vod
Scenario 6¶
Scenario 6
Owner announced separately from anyone else mentioning different groups with custom messages.
You want to notify @everyone when you go live. You want to notify @Streamer when others go live. The third command would use the default live announcement message.
!cb twitch MattTheDev #BigNotification "@everyone CouchBot creator **MattTheDev** is now online!"
!cb twitch Jaymei #notification "@Streamer Another custom message!"
!cb twitch EmElle #notification
Messages¶
You may wish to configure some custom messages with CouchBot to let your server know your live or maybe just to greet a new user. The following commands will show you how!
Scenario 1
Setup hello and goodbye messages
Note
You can use the arguments %USER% and %RANDOMUSER%
!cb allow greetings
!cb allow goodbyes
!cb channel greetings #channel-name
!cb channel goodbyes #channel-name
!cb message greeting "Your Custom Greeting Message"
!cb message goodbye "Your Custom Goodbye Message"
Scenario 2
Custom going live message
So you feel like putting something a bit more personable in the messages for your server? You can use the following;
Note
You can use the arguments %TITLE%, %GAME%, %CHANNEL% or %URL%
!cb message live "Your Custom Live Message"
!cb message published "Your Custom VOD Message"
Basic Configuration¶
Assign Admins¶
Note
These commands are toggled, if you want to remove a person/group from the list, run the command again.
In order for people to manually add and remove content creators to the bot, they must be on the Approved Admin List. They can either be added by role or by individual user, see examples below on how to configure this;
| Name | Example | Usage |
|---|---|---|
| admin | !cb admin @MattTheDev#0001 |
Adds an individual to admin. |
| admin | !cb admin @Developers |
Adds a role to administrate the bot. |
| admin list | !cb admin list |
Provides a list of the configured bot admins |
Allowed Settings¶
In order to run the bot effectively, you must tell it what you wish it to do. An example of this can be to announce published videos only or to greet people joining your server. Some of these settings are necessary for other areas to function such as the Allow Live/Published command.
Live & Published¶
Prudence
If you fail to set either of these the bot will announce no-one.
Use the following commands to configure whether the bot should announce live and/or published content. If you choose not to enable either of these then the bot will in effect, not announce anything.
Note
The following variables are available to use in the Live and Published messages.
%TITLE% - Name of the Stream
%GAME% - Not working for YouTube
%CHANNEL% - Channel Name
%URL% - Full URL of the Stream
| Name | Example | Usage |
|---|---|---|
| allow live | !cb allow live |
Toggles allowing stream announces for live streamers. |
| message live | !cb message live "Your Custom Live Message" |
Changes your live message for the server. |
| Name | Example | Usage |
|---|---|---|
| allow published | !cb allow published |
Toggles allowing published videos to be announced. |
| message published | !cb message published "Your Custom VOD Message" |
Changes your VOD message for the server. |
Greetings & Goodbyes¶
These commands allow you to enable the greeting/goodbye function of CouchBot, this will trigger when people join/leave your server.
Note
The following variables are available to use in this location.
%USER%
%RANDOMUSER%
| Name | Example | Usage |
|---|---|---|
| allow greetings | !cb allow greetings |
Toggle allowing greetings when a member joins the server. |
| channel greetings | !cb channel greetings #discord-channel |
Sets the greeting channel. |
| message greeting | !cb message greeting "Your Custom Greeting Message" |
Changes your greeting message for the server. |
| Name | Example | Usage |
|---|---|---|
| allow goodbyes | !cb allow goodbyes |
Toggle allowing goodbyes when a member leaves the server. |
| channel goodbyes | !cb channel goodbyes #discord-channel |
Sets the goodbye channel. |
| message goodbye | !cb message goodbye "Your Custom Goodbye Message" |
Changes your goodbye message for the server. |
Miscellaneous Settings¶
There are a few other settings available within CouchBot to allow a more customised and cleaner setup.
The following settings change the apperance of the embed message;
| Name | Example | Usage |
|---|---|---|
| allow thumbnails | !cb allow thumbnails |
Adds an image to the bottom of the embed from the stream. |
Twitch Setup¶
Prudence
Please ensure you have read through the Basic Config before moving to this section This avoids issues such as the bot not announcing anyone.
Twitch is by far the most popular streaming platform in the world at the time of this writing. Being the market leader, it has some integrations which make announcing in Discord much easier to setup en mass.
Live Discovery¶
Danger
This requires that there is No Custom Status set and the person streaming has the « Purple Dot »
CouchBot has the ability to automatically discover people in your Discord server that are streaming to Twitch. This is done via the purple « Streaming » indicator on a persons profile when they stream using OBS or similar triggering Streamer Mode on Discord.
The following table shows the only steps needed to configure this for immediate use in your server;
| Name | Example | Usage |
|---|---|---|
| channel live | !cb channel live #discord-channel |
This channel will be where Discovery announcements go. |
| allow livediscovery | !cb allow livediscovery all |
Allows the automatic announcing of people with the status of “Streaming”. |
You can also limit the people that will be announced using assigned roles or you can switch this feature off completely;
| Name | Example | Usage |
|---|---|---|
| allow livediscovery | !cb allow livediscovery none |
Prevents the automatic announcing of people with the status of “Streaming”. |
| allow livediscovery | !cb allow livediscovery role @Streamer |
Allows the automatic announcing of people with the status of “Streaming” and the role of @Streamer. |
Finally, Live Discovery also allows you to assign a « Live Now » type role to creators allowing you to hoist them to show current live users in your server. The role will only be added when they are Live then Removed when they are finished automatically. The command for this feature is as follows;
| Name | Example | Usage |
|---|---|---|
| role live | !cb role live @RoleTheyGet |
The role that gets assigned to a person when they go live. |
Manually Add Creator(s)¶
Manually adding creators allows a fine grained level of control over who is announed in your server and allows things such as custom announcements and channels to be selected giving much more options on who should be announced and where. This is particularly useful on a creators server where they may want to use @here to announce when they are live but not for anyone else.
For more information on custom messages please see Custom Announcements
Important
To remove a creator, run the command again!
| Name | Example | Usage |
|---|---|---|
| twitch | !cb twitch MattTheDev #discord-channel |
Adds a creator be announced |
YouTube Setup¶
Prudence
Please ensure you have read through the Basic Config before moving to this section This avoids issues such as the bot not announcing anyone.
YouTube has the unique ability to indefinently store your Live Streams to VOD as well as upload your own content without the need to be Live at all. CouchBot, in turn, will allow you to announce Live, VOD and/or both to your Discord servers!
Important
To remove a creator, run the command again!
Prudence
To get your YouTube Channel ID see this guide.
It’s 24 characters long and starts with UC.
Alternatvely, use the !cb ytidlookup command.
Live Streaming¶
Unlike other platforms, YouTube uses a Channel ID as the unique identifier for links and as such you need to know this when adding a creator to CouchBot.
| Name | Example | Usage |
|---|---|---|
| youtube | !cb youtube UC1VkELEdx28lgBg_MBkfcwQ #discord-channel live |
Adds a creator to your list to announce when Live. |
| youtube | !cb youtube UC1VkELEdx28lgBg_MBkfcwQ #discord-channel both |
Adds a creator to your list to announce when Live and/or Published. |
Published Videos¶
YouTube is known for it’s Video content moreso than the Live content it also offers. To announce when a creator has uploaded a video you would use the following command;
| Name | Example | Usage |
|---|---|---|
| youtube | !cb youtube UC1VkELEdx28lgBg_MBkfcwQ #discord-channel vod |
Adds a creator to your list to announce when a video is published. |
| youtube | !cb youtube UC1VkELEdx28lgBg_MBkfcwQ #discord-channel both |
Adds a creator to your list to announce when Live and/or Published. |
Other Platforms¶
Prudence
Please ensure you have read through the Basic Config before moving to this section This avoids issues such as the bot not announcing anyone.
Whilst the main platforms of Twitch and YouTube have dominated the market, there are other platforms that cater to more specialist topics and subjects and as we are able, we will add them to our supported platform list.
Important
To remove a creator, run the command again!
Picarto¶
Catering almost exclusively to artists, Picarto found a market that it could build from and has a loyal viewerbase and streamers that love being there.
| Name | Example | Usage |
|---|---|---|
| picarto | !cb picarto MattTheDev #discord-channel |
Adds a creator to your list to announce when Live. |
Mobcrush¶
Catering almost exclusively to mobile gaming, Mobcrush found a market that it could build from and has a loyal viewerbase and streamers that love being there.
| Name | Example | Usage |
|---|---|---|
| mobcrush | !cb mobcrush MattTheDev #discord-channel |
Adds a creator to your list to announce when Live. |
Piczel¶
An art streaming website with free multistreams, free recordings and timelapses, an art gallery and more.
| Name | Example | Usage |
|---|---|---|
| piczel | !cb piczel MattTheDev #discord-channel |
Adds a creator to your list to announce when Live. |
Trovo¶
Trovo is an interactive live streaming platform, live since March 2020.
| Name | Example | Usage |
|---|---|---|
| trovo | !cb trovo MattTheDev #discord-channel |
Adds a creator to your list to announce when Live. |
Glimesh¶
Glimesh is a next generation streaming platform built by the community, for the community.
| Name | Example | Usage |
|---|---|---|
| glimesh | !cb glimesh MattTheDev #discord-channel |
Adds a creator to your list to announce when Live. |
Theta.tv¶
Theta.tv is the next generation Esports entertainment platform on blockchain which features 24/7 live streaming content from top games like Fortnite, League of Legends, CSGO, and more.
| Name | Example | Usage |
|---|---|---|
| theta | !cb theta MattTheDev #discord-channel |
Adds a creator to your list to announce when Live. |
Custom Announcements¶
Prudence
Please ensure you have read through the Basic Config before moving to this section This avoids issues such as the bot not announcing anyone.
A common request was to allow different creators to be announced in different channels with different role ping settings. Whilst we could theoretically do this it was decided to partly bring this into play within CouchBot. Rather than hardcode in additional commands for pinging people, we allow you to edit the message when someone goes live allowing you to ping whatever role/person you choose.
The format for this is the same across all streaming platform that CouchBot announces.
When adding a creator you would specify the custom message at the same time;
e.g. !cb twitch MattTheDev #discord-channel "The Developer of **CouchBot** has gone live!"
Editing the message is as simple as running the command again with the new message to be announced.
Note
The following variables are available to use in the Live and Published messages.
%TITLE% - Name of the Stream
%GAME% - Not working for YouTube
%CHANNEL% - Channel Name
%URL% - Full URL of the Stream
Advanced Messages Setup¶
Prudence
If you are looking to setup messages per creator then follow the instructions in the Custom Announcements section.
Use the following commands to configure custom message options and test them.
Note
The following variables are available to use in the Live and Published messages.
%TITLE% - Name of the Stream
%GAME% - Not working for YouTube
%CHANNEL% - Channel Name
%URL% - Full URL of the Stream
Note
The following variables are available to use in the Greetings and Goodbye messages.
%USER%
%RANDOMUSER%
| Name | Example | Usage |
| message live | !cb message live "Your Custom Live Message" |
Changes your live message for the server. |
| message published | !cb message published "Your Custom VOD Message" |
Changes your VOD message for the server. |
| message offline | !cb message offline "Your Custom Offline Message" |
Changes your offline message for the server. |
| message greeting | !cb message greeting "Your Custom Greeting Message" |
Changes your greeting message for the server. |
| message goodbye | !cb message goodbye "Your Custom Goodbye Message" |
Changes your goodbye message for the server. |
If you want to reset your greetings and messages (or not change them) to the default ones, use the following commands;
| Name | Example | Usage |
| message live | !cb message live clear |
Resets your live message for the server. |
| message published | !cb message published clear |
Resets your VOD message for the server. |
| message offline | !cb message offline clear |
Resets your offline message for the server. |
| message greeting | !cb message greeting clear |
Resets your greeting message for the server. |
| message goodbye | !cb message goodbye clear |
Resets your goodbye message for the server. |
| message offline | !cb message offline "" |
Leaves the original announcement post without changes. |
To have the message outside of the embed blank, use the following;
| Name | Example | Usage |
| message live | !cb message live empty |
Remove message outside of embed on live stream announcement. |
| message published | !cb message published empty |
Remove message outside of embed on published announcement. |
If you want to test your messages, use the following commands;
| Name | Example | Usage |
| test live | !cb test live #DiscordChannel |
Tests your live message for the server. |
| test published | !cb test published #DiscordChannel |
Tests your VOD message for the server. |
| test greeting | !cb test greeting |
Tests your greeting message for the server. |
| test goodbye | !cb test goodbye |
Tests your goodbye message for the server. |
Role Assignment¶
CouchBot is capible of assigning roles based on specific criteria such as a user joining the server or typing a phrase in Discord. This provides opportunities such as typing « I Love Streams » to get pinged when a creator goes live etc.
Prudence
If you are assigning roles, make sure the bot is above the role it is supposed to assign.
If you want Discord users to be assigned a role when they join your Discord server then the following commands will do this for you.
| Name | Example | Usage |
|---|---|---|
| role join | !cb role join @RoleName |
Assigns a role when people join your server. |
| role join reset | !cb role join reset |
Reset the server join role to nothing. |
For a typed phrase to assign roles that can be done by the users themselves, see below;
| Name | Example | Usage |
|---|---|---|
| role add | !cb role add "CouchMe" [add/remove] @RoleTheyGet |
Adds/Removes a role when someone types « CouchMe » |
| role remove | !cb role remove "CouchMe" |
Removes the command « CouchMe » |
Reaction Roles are also available to use should you find that easier to implement on your server;
Note
This can scale up to a maximum or FOUR reaction roles.
| Name | Example | Usage |
|---|---|---|
| rm | !cb rm @Streamer :thumbsup: Please react to get the Streamer role! |
Adds/Removes a role when someone adds a reaction to the :thumbsup: emoji. » |
| rm | !cb rm @Streamer :thumbsup: @Announcements :loudspeaker: Please react to get the desired role! |
Adds/Removes a role when someone adds a reaction to the :thumbsup: emoji. » |
The final role option available is tied to Twitch only and assigns the person who is live an additional role only when they are live. Please see Twitch Info for further information on this role.
Games & Teams¶
Note
These commands are toggled, if you want to remove something from the list, run the command again.
CouchBot can alert you when members of a specific stream team have gone live. For developers, we even have the game announcmenet feature allowing anyone playing a particular game to be announced.
If you have a game or want to announce a game, then use the following settings.
| Name | Example | Usage |
|---|---|---|
| game | !cb game "Last Epoch" #discord-channel |
Toggles adding a game to the creators list. |
| game list | !cb game list |
Displays a list of added games. |
If you have a team or want to announce a team, then use the following settings. An example is the sutv channel on Twitch.
| Name | Example | Usage |
|---|---|---|
| team | !cb team twitch sutv #discord-channel |
Toggles adding a team to the creators list. |
| team list | !cb team list |
Displays a list of added teams. |
Filtering¶
Note
These commands are toggled, if you want to remove something from the list, run the command again.
CouchBot has the ability to filter announcements to specific games, stream titles. This will only allow items mentioned on this list to be announced regardless of what creators you may have added. An example being if someone played Destiny 2 they would never be announced in the following examples.
| Name | Example | Usage |
|---|---|---|
| filter game | !cb filter game twitch "World of*" |
Creates a Game Filter on Twitch for any games starting with « World of » |
| filter title | !cb filter title twitch "World of*" |
Creates a Stream Title Filter on Twitch for any titles starting with « World of » |
| filter list | !cb filter list |
Displays a list of the current applicable filters. |
Utilities¶
Custom Commands¶
Custom commands allow a versatile way for you to have the bot respond to different terms. This could be used to advertise your Twitter, display your Discord invite or have the bot ping someone!
| Name | Example | Usage |
|---|---|---|
| command add | !cb command add "CouchMe" 5 "You have been Couched!" |
Creates a command called CouchMe with a 5 second cooldown that replies « You have been Couched! » |
| command remove | !cb command remove "CouchMe" |
Removes the command, in this instance CouchMe. |
| command list | !cb command list |
Displays a list of the current commands you have programmed. |
Moderation¶
This provides basic moderation actions that can be used via the bot;
| Name | Example | Usage |
|---|---|---|
| kick | !cb kick @MattTheDev#0001 |
Kicks the user from the server. |
| ban | !cb ban @MattTheDev#0001 |
Bans the user from the server. |
| echo | !cb echo Matt is Great! |
Gets the CouchBot to repeat the text you specify. |
Random Announcements¶
Ever wanted to put a random stream in a channel? Of course you did and now you can!
| Name | Example | Usage |
|---|---|---|
| announce random | !cb announce random twitch |
Will announce a random stream in the channel you type it in (Admin Only) |
| dm random | !cb dm random twitch |
Will DM a random stream to the user that ran the command. |
Misc Commands¶
Use the following commands to configure and view various other bits and bobs.
| Name | Example | Usage |
|---|---|---|
| info | !cb info |
Brief stats overview of the bot. |
| invite | !cb invite |
Sends you a message with the bot invite. |
| ytidlookup | !cb ytidlookup "Channel Name" |
Tries to locate the channel ID for YouTube. |
| whatsthis | !cb whatsthis |
Give a link to an image to find out. |
| config list | !cb config list |
Gives a link to the bots configuration. |
| config deleteoffline | !cb config deleteoffline |
Deletes offline streams. |
| config textannouncements | !cb config textannouncements |
Announces in text rather than embeds |
| clap | !cb clap place your text here |
Places a clap in all the spaces. |
| cookie | !cb cookie place your text here |
Places a cookie in all the spaces. |
| clone | !cb clone #ChannelClone All notifications go in here. |
You can use this command to clone a channel and pin the message you specify. |
| prefix | !cb prefix - |
Using the command like this will change your prefix to - |
Purge (Delete) Messages¶
Sometimes you may wish to clear channels, messages or just messages from specific people to help in the effective moderation of you server. To accomplish this you can use the following commands.
Avertissement
You must have Manage Messages permissions to run this command! Once run, you will be unable to restore deleted messages.
| Name | Example | Usage |
|---|---|---|
| purge | !cb purge |
Deletes 100 messages in the current channel. |
| purge | !cb purge 25 |
This would purge 25 messages in the current channel. |
| purge | !cb purge 25 #DiscordChannel |
This would purge 25 messages in the channel #DiscordChannel. |
| purge | !cb purge 25 #DiscordChannel true |
This would purge 25 messages in the channel #DiscordChannel including pinned messages. |
| purge | !cb purge @MattTheDev |
Deletes all messages from user within the last 100 messages in the current channel. |
| purge | !cb purge @MattTheDev true |
Deletes all messages from user within the last 100 messages in the current channel, including pinned messages. |
| purge | !cb purge @MattTheDev #DiscordChannel |
Deletes all messages from user within the last 100 messages in the current channel. |
| purge | !cb purge @MattTheDev #DiscordChannel true |
Deletes all messages from user within the last 100 messages in the current channel, including pinned messages. |
Avertissement
The following commands have no confirmation and will execute when run.
| Name | Example | Usage |
|---|---|---|
| creators purge | !cb creators purge |
Removes all manually added creators from announcing. |
| creators purge | !cb creators purge twitch |
Removes all manually added creators on Twitch from announcing, works for all platforms. |
Troubleshooting¶
You can join the CouchBot support server at this link –> https://discord.couch.bot/
Bot Required Permissions¶
When CouchBot joins your server he should request all the necessary permissions when prompted to join. To ensure that CouchBot can function fully on your server, please ensure all of the following permissions are granted to his server role:
- Manage Roles (For Live Discovery / Role Assignment)
- Read Text Channels (For ALL Functionality)
- Send Messages (For ALL Functionality)
- Manage Messages (For DeleteOffline Functionality)
- Embed Links (For ALL Functionality)
- Read Message History (For ALL Functionality)
- Mention Everyone (For Ping Functionality)
If you are having issues you can use the following commands to help in identifying where they are.
Attention
Ensure the channel also has the correct permissions to allow CouchBot to post!
| Name | Example | Usage |
| ping | !cb ping |
Should provide a « pong » response. |
| permissions | !cb permissions #ChannelName |
Checks the bots permissions in the channel. |
| prefix | @CouchBot#7169 prefix |
Tells you your prefix. |
| uptime | !cb uptime |
Shows the bots uptime. |