MedalBot Documentation

MedalBot

Discord Bots Discord Bots Discord Bots

MedalBot is our very own Discord bot that allows you and your friends to submit and upvote clips directly through Discord - and much more. Earn points and medals by chatting, submitting content, earning upvotes, and upvoting other peoples' content! MedalBot is packed with features you and the communities you participate in and manage will love.

Setup

Invite

Add MedalBot to your Discord server using the link below. It will request necessary permissions to enable full functionality for all of the features listed on this page.

Invite MedalBot

Integrate

Medal integrates with your Discord server seamlessly. You can choose to customize your server's configs, or you can get started with the default configs right away!

MedalBot will automatically create a Medal account for your Discord server. By default, all content submitted by your users will contribute to your Discord community's Medal profile. MedalBot will also start tracking Medal Social participation, listening for clip URLs in chat, and many other features by default. You can find the default settings of each feature in the Configs section.

If you want to get started with default configurations, you don't have to do anything except add MedalBot to your Discord server using the link above. If you want to customize specific settings for MedalBot, check out the section below for more information.

Configure

A Guild is an individual Discord server. You can customize MedalBot configurations specially for your server.

Click here for more information on Guild Configs.

Basic Examples:
  • !config antispam true will enable antispam moderation.
  • !config blacklist discord.gg will add "discord.gg" to the blacklisted keywords, automatically deleting any messages containing discord.gg invites.
  • !config whitelist discord.gg/44dEa will add "discord.gg/44dEa" to the whitelisted keywords, bypassing any blacklisted keyword filters for this specific invite URL.
  • !config default.game [category] will set the default game category to whatever you specify.
  • !config social.enabled true will enabled Medal Social for your server.
  • !config dj.required true will make it so a DJ role is required to use skip and other music features.

Support

If you have any questions or problems, join the Medal Discord below.

Join Discord

Medal Integration

MedalBot integrates your Discord community with Medal automatically.

Account Management

Link your Discord to an existing Medal account, or have MedalBot automatically create a new Medal account just for you! When you link your Discord to Medal, all your MedalBot submissions will appear on your Medal profile. You will also be able to upvote clips, subscribe to MedalBot Daily Clips, and more.

Click here for information on how to link your Discord to Medal, unlink accounts, and view your account information.

Content Submission

Submit clips and videos to Medal directly through MedalBot. Clips you submit will contribute to your Medal Social profile, as well as any Discord servers you participate in.

Click here for information on how to submit clips and videos to MedalBot.

Game Categories

Stay in sync with the latest games at all times through MedalBot. All the game categories you find in our app, MedalBot supports too!

Click here for information on how to submit clips and videos to MedalBot.

Random Clips

Find those hidden gems buried in the depths of our database by posting random clips straight to Discord.

Click here for information on how to retrieve a random clip.

Upvoting

Whenever someone submits a clip, or a clip is posted to the channel by MedalBot, you will be able to upvote it right then and there. Simply adding a thumbs-up reaction to the message will upvote it!

Subscriptions

Subscribe to MedalBot's Daily Clips for your favorite games. Each day, MedalBot will PM you one of the trending clips from that day for each game you subscribe to.

Click here for information on how to manage your subscriptions.

Medal Social

Medal Social is a participation-based social system that rewards you for being an active participant in Discord servers, and on Medal! Earn points to build up your Medal Social profile. Climb the rankings and get to the top of Community and Global leaderboards!

Social Points

Different actions will reward you with different amounts of points. Not only will they reward you, but they will reward any Discord servers you are participating in (that have MedalBot added)!

Chat

Engaging in chat and sending quality messages will reward you with a small number of points.

Points: 1 point

Content Submission

Submitting content earns you the biggest number of points possible!

Points: 500 points

Upvotes

Upvoting clips in Discord will earn you 5 points per upvote, which means watching and upvoting as many clips as you can from Discord will earn you lots of points!

Points: 5 points

Community Rankings

Earn your spot in Community Rankings for each Discord server you participate in. Community Rankings are separate from other servers, and your submissions in one community do not affect your Social Points in another community.

Click here for more information on viewing Community Rankings.

Global Rankings

Claim your place in Global Rankings! All your submissions, chatting, and upvoting in every Discord server (that has MedalBot) will contribute to your global Medal Social profile.

You can also view the Top Discord Servers and see where your favorite ones rank globally for social activity!

Click here for more information on viewing Global Rankings for the top users and Discords.

Bot Commands

MedalBot is packed with features! We know it can be overwhelming at times, but don't worry, we've got you covered. Here is a comprehensive list of commands and how they function.

Guild Management

These commands can help you manage your Discord server (guild) to see how your community is growing, and to help keep things in check.

Member Stats

MedalBot keeps track of when users join and leave your Discord. You can get insight on how well you are retaining your users over a period of 1, 3, 7, 30 days, and so on.

.memberstats Check today's member stats

.memberstats 7 Check member stats for the last week

.memberstats 30 Check member stats for the last month

mod.logs

When enabled, MedalBot will log key actions like when a user joins, has a role added to them, or is banned to a channel named #mod-logs. By default it is true.

Usage
!config mod.logs [true, false]
Prune

Prune the messages from a specified user from the channel.

.prune {@username} Prune previous messages from the user, up to 10 by default

.prune {@username} 25 Prune up to 25 previous messages from the user

grantable.role

The name of the Role(s) that can be granted/revoked using %val=command.prefix%grant [@Username] [role] and %val=command.prefix%grant [@Username] [role] commands (no brackets) (role managers only, see !config role.manager for more details). By default it is none.

You can add multiple roles to this list.

Usage
!config grantable.role [role]
role.manager

The name of the Role(s) that can use the %val=command.prefix%grant [@Username] [role] and %val=command.prefix%revoke [@Username] [role] commands (no brackets). By default it is none.

You can add multiple roles to this list, and all will have role-granting abilities.

Usage
!config role.manager [role]
slow.channel

When a channel is set to be a slow channel, MedalBot will force members to wait %val=slow.rate% seconds between each message.

You can specify the time to wait between messages using the !config slow.rate config.

Usage
!config slow.channel [channel]
slow.rate

The number of seconds to wait between messages for slow channels (see !config slow.channel).

Usage
!config slow.rate [number]
suggestion.channel

The text channel to treat as the suggestions channel by default it is default, which means none. When this is set, the channel you set will require messages to be sent using the %val=command.prefix%suggest [suggestion] command. All suggestions will automatically be marked with :white_check_mark: and :x: so users can vote on suggestions.

Usage
!config suggestion.channel [channel]
Help & Info

Get help and info about MedalBot commands directly in Discord using .medalhelp. You can also type .help (unless the owner has disabled generic help active).

Help / Commands

.medalhelp Get help from MedalBot! See a list of all possible commands and additional information

.medalhelp [command] Get help from MedalBot! See information for the command you specified

Medal Account

Interact with your Medal account directly through MedalBot. Integration with Medal allows you to link an existing Medal account to your Discord, or automatically create a new one.

My Account

Access your the account information for the Medal account linked to your Discord.

.myaccount
Medal Clips

Fetch random clips from any game category, or specific clips of your choosing. Submit your own, and view your submission history, and even subscribe to Daily PMs for your favorite games.

Categories

Medal has dozens of game categories you can browse clips from and submit content to.

.categories View a full list of game categories

Fetch Clip

Fetch a clip for a specified ID. This is useful for grabbing a specific clip you want having MedalBot posting it into the channel, automatically adding a thumbs-up reaction to encourage upvoting.

.clip [id] Fetch a clip from Medal for the specified ID

Random Clip

Fetch a random clip and MedalBot will post it to the Discord channel, automatically adding a thumbs-up reaction to encourage upvoting.

.randomclip Fetch a random clip from any category

.randomclip [category] Fetch a random clip from the category of your choosing

Random Clip

Fetch a random clip and MedalBot will post it to the Discord channel, automatically adding a thumbs-up reaction to encourage upvoting.

.randomclip Fetch a random clip from any category

.randomclip [category] Fetch a random clip from the category of your choosing

Submit Clip

Submit a clip to Medal directly from Discord! If you have already linked your Discord with Medal, then your submissions will save to your Medal profile. Otherwise, they will contribute to the Discord community's profile that you are submitting from.

.submit [title] [url] [category] Submit a clip URL to Medal with the title of your choosing to the game category you specify

.submit [title] [url] Submit a clip URL to Medal with the title of your choosing to the Discord server's default game category (if there is one set)
Click here for information on setting the default game category

Subscribe

Subscribe to Daily PMs of clips from your favorite games! You can also subscribe for hourly and weekly PMs from MedalBot.

.subscribe [category] Subscribe to Daily PMs for clips from the game category you specify

Subscriptions

.subscriptions View all of your active clip subscriptions.

Unsubscribe

Unsubscribe from game categories, or from all games entirely. You can resubscribe at any time!

.unsubscribe [category] Unsubscribe from the game category you specify

.unsubscribe Unsubscribe from all game categories

Medal Social

MedalBot keeps track of how much you and your users participate in Discord communities. Any servers with MedalBot added to them are participating in Medal Social (unless they've disabled social features).

Compete against other users and communities to maintain your ranks!

My Social

View your Medal Social profile. Check out your Social Points and where you're most active.

.mysocial Fetch your Medal Social profile for the guild you're in. If you're not in a guild, it will automatically retrieve your global profile.

.mysocial global Fetch your global Medal Social profile

Social

View the Medal Social profile of someone else.

.social [username] Fetch the Medal Social profile for the username you specify. If you're not in a guild, it will automatically retrieve your global profile.

.social [uername] global Fetch the global Medal Social profile for the username you specify

Top Social

Check which users and Discord communities are dominating the Community Rankings and the Global Rankings!

.topsocial Check the top users for the guild you're in. If you're not in a guild, it will automatically check the top global users.

.topsocial global users Check the top global users

.topsocial guilds Check the top Discord communities

Settings

You can customize some settings to fit your server's needs. Settings only work for server owners, you cannot use these as an individual user.

You can configure settings using the !config command. Typing !config [setting] will show you the description and usage of that setting.

Some settings act as lists which store multiple values. Generic configs can only hold one value, like in the example above.

List Settings

Some settings function as lists and can store multiple values. For these settings you can type !config [setting] -all to list all of the current values in that list.

You can also type !config [setting] -clear to erase all values for the setting.

If you want to remove only one entry from the setting list, you can type !config [setting] -rm [keyword] to remove only the specified keyword from the setting list.

Antispam

antispam

When enabled, MedalBot will detect spammers who spams messages in one channel in a few seconds.

At first it will warn them to stop. If the spam continues, they will be punished with the antispam.action.

You can use the antispam.action config to set what action to perform when spammers are detected. Mods+ can bypass antispam filters.

Usage
!config antispam [true, false]
antispam.action

This is the action to perform when a spammer is detected when antispam is set to true. By default it is warn, which means the owner will be mentioned and the user warned.

Alternatively, you can use:

mute to automatically mute the user in every text and voice channel

kick to automatically kick spammers

ban to automatically ban spammers

Usage
!config antispam.action [warn, mute, kick, ban]

Auto Assign Roles

auto.assign.role

The name of the Role(s) to automatically assign to new members when they join. You can also specify multiple roles to treat as public roles.

For example:

!config auto.assign.role Member

This would automatically assign the Member role to new members.

Usage
!config auto.assign.role [role]

Auto Clip Detection

clip.detection

When set to true, MedalBot will automatically detect clips when users include them in messages and PM them asking if they want to upload it to Medal.

Usage
!config clip.detection [true, false]
clip.detection.channel

The channel to automatically detect clips in when users include them in their messages. By default it is any channel.

Usage
!config clip.detection.channel [text]

Blacklist Keyword

blacklist

Blacklist a keyword so whenever it shows up in chat, the bot automatically deletes the message. By default there are none, but a common usage of this is for disallowing Discord invites.

Usage
!config blacklist [text]

Command Configs

command.prefix

Sets the command prefix used to start commands with. By default it is ..

Usage
!config command.prefix [text]
disable.command

Disable commands using this config. When you add a command to this list, MedalBot will ignore input for it in the server.

This only applies to MedalBot commands.

Usage
!config disable.command [command]
disable.command.help

When set to true, MedalBot will ignore .help and will only listen to .medalhelp, .info, and .commands.

Usage
!config disable.command.help [true, false]
restrict.commands

Restrict commands to specified roles. Only the roles in this list will be allowed to use commands.

This only applies to MedalBot commands.

Usage
!config restrict.commands [role]
Default Game Category
default.game

The default game topic to use globally (overridden by channel-specific topics). Set it to none to require users to specify a category when using the .submit command, and for randomclip to choose from a random category by default.

Usage
!config default.game [text]
DJ & Music
dj.required

When enabled, the music bot requires the DJ role to use skipping, resetting, and stopping functions. By default it is true

Usage
!config dj.required [true, false]
dj.role

The name of the Role the server uses for the DJ role. By default it is DJ

You can add multiple roles to this list, and all will be given DJ privileges.

Usage
!config dj.role [role]
music.auto.leave

When enabled, the bot will automatically leave voice channels when no music is playing. By default it is false.

Usage
!config music.auto.leave [true, false]
music.channel

The channel(s) to restrict music commands to. By default there are none, and music commands can be used in any channel.

Usage
!config music.channel [channel]
music.prefix

The command prefix for music commands. By default it is m!

For example:

m!play I Feel Good

Usage
!config music.prefix [text]
Public Role
guild.public.role

The name of the Role(s) that is considered the "public" role. By default, it is default, which uses the @ everyone role.

You can specify multiple roles to treat as public roles, for example:

!config guild.public.role PC !config guild.public.role Member

This would mark both the PC and Member roles as the lowest ranked role in the server that still has access to channels.

Usage
!config guild.public.role [role]
Social Enabled
social.enabled

When enabled, MedalBot will reward users with Social Points for actions like chatting, upvoting, and submitting content.

Users can build up their Medal Social and contribute to the Discord server's Community Ranking!

You can type .social for more information on how Medal Social works.

Usage
!config social.enabled [true, false]
Welcome Message
welcome.message

When a welcome message is set, the message will be posted in the channel set in the welcome.message.channel config. By default, it will use your public channel.

To include the person's username that just joined in your message, you can use %username% where you want to use their name.

To send welcome messages only in private messages to new users, you can type !config welcome.message.channel PM.

To disable welcome messages completely, you can type !config welcome.message -reset

Usage
!config welcome.message [text]
welcome.message.channel

When a welcome message is set, the message will be posted to the channel specified in this config. By default, it will use your public channel (usually #general).

To send welcome messages only in private messages to new users, you can type !config welcome.message.channel PM.

Usage
!config welcome.message.channel [text]
Whitelist Keyword
whitelist

Whitelist a keyword so whenever it shows up in chat, the bot allows it even if some/all of it is blacklisted.

Usage
!config whitelist [text]

Public API

Here are some basic example calls for Medal. All response are given in JSON only. For features such as being able to upvote inside discord, submitting clips, and seeing results from a specific discord channel, you'll have to use MedalBot.

Examples

Click here for some Java / Javascript examples.

Categories

Get started by syncing with our game categories.

GET https://api.gomedal.com/categories

You will receive a response with JSON array of categories. Simply save the categoryId and categoryName to a local array or list for later.

Response

[
  {
    "categoryId": 39,
    "categoryName": "Battlefield",
    "categoryThumbnail": "https://static-cdn.jtvnw.net/ttv-boxart/Battlefield%201-52x72.jpg",
    "categoryBackground": "https://static-cdn.jtvnw.net/ttv-boxart/Battlefield%201-52x72.jpg",
    "categoryFollowers": 52,
    "categoryPublishers": 1,
    "isFeatured": 1
  },
  {
    "categoryId": 41,
    "categoryName": "PUBG",
    "categoryThumbnail": "https://static-cdn.jtvnw.net/ttv-boxart/PLAYERUNKNOWN%27S%20BATTLEGROUNDS-272x380.jpg",
    "categoryBackground": "https://static-cdn.jtvnw.net/ttv-boxart/PLAYERUNKNOWN%27S%20BATTLEGROUNDS-272x380.jpg",
    "categoryFollowers": 104,
    "categoryPublishers": 1,
    "isFeatured": 1
  }
]
                                
Random Clip

You can add random=true to your query parameters to request 1 random clip. You can still supply a categoryId and limit. For example:

GET https://api.gomedal.com/botclips?random=true&categoryId=41

This would return 1 random trending PUBG clip from that day.

If you don't specify a category, you will get clips globally across all game categories. For example, this would return the 1 random trending clip globally from that day:

GET https://api.gomedal.com/botclips?random=true&limit=1