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 (DLive, Glimesh, Picarto, Piczel, Trovo, Theta, Twitch, & YouTube)
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 add your server to the approved server list.

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 add your server to the approved server list. 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
me	`/me`	Shows you allowance and servers added.
addserver	`/addserver server_id: 123456789`	Adds a server to your account.
removeserver	`/removeserver server_id: 123456789`	Removes a server from your account.

The command(s) below is only applicable to specific Patreon tiers;

Name	Example	Usage
/ping	`/ping custom_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.

/allow
Choose 'Live' from the drop down
/twitch creator: MattTheDev channel: #notification message: 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!

Caution

The streamer has to have the status “Streaming” to be automatically announced.

/allow
Choose 'Live' from the drop down
/channel live #notification
/discovery enable

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!

Caution

The streamer has to have the status “Streaming” to be automatically announced.

/allow
Choose 'Live' from the drop down
/channel live #notification
/discovery enable 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.

/allow
Choose 'Live' from the drop down
/twitch creator: MattTheDev channel: #ownerchannel
/twitch creator: Jaymei channel: #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”.

/allow
Choose 'Live' and 'Published' from the drop down
/youtube creator: Channel Name channel: #livechannel type: live
Choose the correct channel from the drop down.
/youtube creator: Channel Name channel: #publishedchannel type: vod
Choose the correct channel from the drop down.

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.

/twitch creator: MattTheDev channel: #BigNotification message: @everyone CouchBot creator **MattTheDev** is now online!
/twitch creator: Jaymei channel: #notification message: @Streamer Another custom message!
/twitch creator: EmElle channel: #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%

/allow
Choose 'Greetings' and 'Goodbyes' from the drop down
/channel greetings #channel-name
/channel goodbyes #channel-name
/message greeting Your Custom Greeting Message
/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%

/message live Your Custom Live Message
/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	`/admin name: MattTheDev`	Adds an individual to admin.
admin	`/admin role: Developers`	Adds a role to administrate the bot.
admin list	`/admins [page #]`	Provides a list of the configured bot admins. Page # is optional, defaults to 1.

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¶

Caution

If you fail to set either of these the bot will announce no-one.

Use the following slash command 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

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%

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;

Discord Live Setup¶

Caution

THIS IS NEWLY DEPLOYED. THERE MAY BE BUGS. SUBMIT FEEDBACK TO MATT - LETS MAKE THIS THING AWESOME!

Use the following commands to configure live Discord announcements, like shown below:

To enable live announcements, first you need to set a Live channel.

/channel discordlive channel: #DiscordChannelToAnnounceIn

Next, you need to enable Discord Live Announcements via the Allow configuration.

/allow

When the drop down appears, ensure that a green tick is next to Discord Live Announcements. If not, click on it - and click outside the drop down.
At this point, you are now good to go. Anytime someone starts streaming via a Voice Channel, an announcement will be made.

Want to customize the message / embed?! Look no further!

Most of the message preceding the embed AND the embed contents itself are configurable.
Type any variation of the command below ..

Discord Live Setup

header will modify #1 in the screenshot.
description will modify #2 in the screenshot.
footer will modify #3 in the screenshot.
message will modify #4 in the screenshot.
mention_role will modify #5 in the screenshot.

Caution

All of the above are OPTIONAL parameters. If you provide an empty option though .. it will reset the setting previously set.

Want to assign a role when these users go live?

Easy peasy! Discord live announcements share the live role with Discovery.

/role live role: @RoleToAssignOnLive

Note

Unlike normal announcements - as of 9/2/2022 these will not be cleaned up when they go offline.

Twitch Setup¶

Caution

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;

Basic Live Discovery Setup¶
Name	Example	Usage
/channel live	`/channel live #discord-channel`	This channel will be where Discovery announcements go.
/discovery	`/discovery enable`	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;

Advanced Live Discovery Setup¶
Name	Example	Usage
/discovery	`/discovery disable`	Prevents the automatic announcing of people with the status of “Streaming”.
/discovery	`/discovery enable 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;

Live Discovery Roles Setup¶
Name	Example	Usage
role live	`/role live role: @RoleName`	Assigns a role when people go live.
role live reset	`/role livenone`	Reset the server join role to nothing.

Manually Add Creator(s)¶

Manually adding creators allows a fine grained level of control over who is announced 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!

Manual Twitch Setup¶
Name	Example	Usage
twitch	`/twitch creator: MattTheDev channel: #discord-channel`	Adds a creator be announced

YouTube Setup¶

Caution

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!

YouTube ID Lookup¶

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.

YouTube ID Lookup¶
Name	Example	Usage
/youtube lookup	`/youtube lookup Channel Name`	A list of channels and their ID / Description will display if valid.

Live Streaming¶

To announce when a creator has started a stream you would use the following command;

Live Streaming¶
Name	Example	Usage
youtube	`/youtube creator: YouTube Channel Name channel: #discord-channel type: live`	A dropdown will appear. Choose the channel to add or remove. Adds / Removes a creator to your list to announce when Live.
youtube	`/youtube creator: YouTube Channel Name channel: #discord-channel type: both`	A dropdown will appear. Choose the channel to add or remove. Adds / Removes a creator to your list to announce when Live and/or Published.
youtube	`/youtube creator: YouTube Channel ID channel: #discord-channel type: live`	This will bypass the dropdown, and directly add the YouTube Channel, if a valid ID is passed.
youtube	`/youtube creator: YouTube Channel ID channel: #discord-channel type: both`	This will bypass the dropdown, and directly add the YouTube Channel, if a valid ID is passed.

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;

Published Videos¶
Name	Example	Usage
youtube	`/youtube creator: YouTube Creator Name or ID channel: #discord-channel type: vod`	A dropdown will appear. Choose the channel to add or remove. Adds / Removes a creator to your list to announce when a video is published.
youtube	`/youtube creator: YouTube Creator Name or ID channel: #discord-channel type: both`	A dropdown will appear. Choose the channel to add or remove. Adds / Removes a creator to your list to announce when Live and/or Published.
youtube	`/youtube creator: YouTube Channel ID channel: #discord-channel type: vod`	This will bypass the dropdown, and directly add the YouTube Channel, if a valid ID is passed.
youtube	`/youtube creator: YouTube Channel ID channel: #discord-channel type: both`	This will bypass the dropdown, and directly add the YouTube Channel, if a valid ID is passed.

Other Platforms¶

Caution

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!

DLive¶

DLive.tv is the largest live streaming community on the blockchain. Discover amazing games and channels, and earn rewards by watching streams on DLive now.

DLive Commands¶
Name	Example	Usage
dlive	`/dlive creator: MattTheDev channel: #discord-channel`	Adds a creator to your list to announce when Live.

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.

Picarto Commands¶
Name	Example	Usage
picarto	`/picarto creator: MattTheDev channel: #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.

Piczel Commands¶
Name	Example	Usage
piczel	`/dlive creator: MattTheDev channel: #discord-channel`	Adds a creator to your list to announce when Live.

Trovo¶

Trovo is an interactive live streaming platform, live since March 2020.

Trovo Commands¶
Name	Example	Usage
trovo	`/trovo creator: MattTheDev channel: #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.

Glimesh Commands¶
Name	Example	Usage
glimesh	`/glimesh creator: MattTheDev channel: #discord-channel`	Adds a creator to your list to announce when Live.

Custom Announcements¶

Caution

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. /twitch creator: MattTheDev channel: #discord-channel message: 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¶

Caution

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 messages.

%NEWLINE% - Insert a new line.
%NICKNAME% - Nickname of the person joining. They do not have one though, this will return username on Greetings.
%RANDOMUSER% - Grab a random username from the server.
%SERVER% - Name of the server.
%SERVERID% - ID of the server.
%TIMESTAMPUTC% - Current Timestamp, in UTC.
%USER% - Username of the person joining.
%USERID% - User ID of the person joining.

Note

The following variables are available to use in the Goodbye messages.

%HOWLONG% - Human readable amount of time they spent on the server, ie: 3 months, 2 days, and 6 hours.
%JOINDATE% - The date the person leaving originally joined the server.
%NEWLINE% - Insert a new line.
%NICKNAME% - Nickname of the person leaving. If they do not have one, will act like %USER%.
%RANDOMUSER% - Grab a random username from the server.
%SERVER% - Name of the server.
%SERVERID% - ID of the server.
%TIMESTAMPUTC% - Current Timestamp, in UTC.
%USER% - Username of the person leaving.
%USERID% - User ID of the person leaving.

If you want to reset your greetings and messages to the default verbiage, use the following commands;

To have the message outside of the embed blank, use the following;

Name	Example	Usage
message live	`/message live empty`	Remove message outside of embed on live stream announcement.
message published	`/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	`/test live`	Tests your live message for the server.
test published	`/test published`	Tests your VOD message for the server.
test greeting	`/test greeting`	Tests your greeting message for the server.
test goodbye	`/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.

Caution

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.

Server Join Commands¶
Name	Example	Usage
role join	`/role join role: @RoleName`	Assigns a role when people join your server.
role join reset	`/role joinnone`	Reset the server join role to nothing.

Reaction Roles are also available to use should you find that easier to implement on your server. Instead of typing a command, your users can react to an emoji attached to a message to be assigned / removed from a given 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 announcement 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.

Game Commands¶
Name	Example	Usage
game	`/game name: Last Epoch channel: #discord-channel`	Toggles adding a game to the server games list.
game list	`/games page: [page #]`	Displays a list of added games. Page # is optional, defaults to 1.

If you have a team or want to announce a team, then use the following settings. An example is the sutv channel on Twitch.

Team Commands¶
Name	Example	Usage
team	`/team name: sutv channel: #discord-channel`	Toggles adding a team to the server teams list.
team list	`/teams page: [page #]`	Displays a list of added teams. Page # is optional, defaults to 1.

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.

Filter Commands¶
Name	Example	Usage
filter game	`/filter type: game platform: twitch filter_text: World of*`	Creates a Game Filter on Twitch for any games starting with “World of”
filter title	`/filter type: title platform: twitch filter_text: World of*`	Creates a Stream Title Filter on Twitch for any titles starting with “World of”
filter list	`/filters page: #`	Displays a list of the current applicable filters. Page # is optional, defaults to 1.

Note

Want to add wildcards to your filters? Go for it! Adding a game filter of "*of*" will announce World of Warcraft, World of Tanks, Anything of Anything! Wildcards can be used in Title filtering too.

Utilities¶

Misc Commands¶

Use the following commands to configure and view various other bits and bobs.

Name	Example	Usage
/info	`/info`	Brief stats overview of the bot.
/invite	`/help`	Display an output of common places to find help with the bot.
/invite	`/invite`	Sends you a message with the bot invite.
config list	`/config`	Displays the bots configuration.

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.

Warning

You must have Manage Messages permissions to run this command! Once run, you will be unable to restore deleted messages.

Name	Example	Usage
/purge	`/purge`	Deletes 100 messages in the current channel.
/purge count	`/purge count: 25`	This would purge 25 messages in the current channel.

Warning

The following commands have no confirmation and will execute when run.

Creator Purge¶
Name	Example	Usage
creators purge	`/purgecreators`	Removes all manually added creators from announcing.
creators purge	`/purgecreators platform: 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	`/ping`	Should provide a “pong” response.
permissions	`/permissions channel: #ChannelName`	Checks the bots permissions in the channel.