Discord match score-bot

Follow this guide to create a customised Discord score-bot!


This customisable Discord match score-bot uses the free PandaScore REST API to deliver match status updates to your Discord communities. Whether you are an esports team, a tournament organiser, or a dedicated gaming community, get ready to captivate your audience with a Discord match score-bot at no cost.


The Discord bot utilises PandaScore REST API to keep track of match status changes by polling the /matches endpoint. The score-bot is configured to send a message to a given Discord channel in two instances:

  • Match start: The match transitions from not_started to running state. A message is sent to the Discord server stating that the match has begun, providing the match name and an available stream URL, allowing users to watch the games unfold.
  • Match end: The match transitions from running to finished state. A message is sent to the Discord server, with the match name, final score, and the winning team.

Thanks to the polling logic on the /matches endpoint, these messages are sent as soon as there is a match status update, keeping your audience up-to-date on the latest match news. To learn more about match lifecycle, please refer to our documentation.

Setting up your Discord score-bot


Before beginning the tutorial, you should first create a new Discord bot.

  1. Create a new application at https://discord.com/developers/applications, click New application, and give the application a name. Once you've created your bot, you can give the bot a public icon, a name, and a description in the General Information tab and save your changes.
  2. Click Bot from the side panel, and copy the token under the Token subheading. Save this for later, as this will be the BOT_TOKEN variable used in the code. The bot token will connect your code to the Discord bot.
  3. Scroll down to the Privileged Gateway Intents heading and enable message content intent.
  4. Navigate to the OAuth 2 heading from the sidebar and click URL generator. Here, you can select that the scope is a bot and assign the permissions the bot can have in your Discord server. For this project, select the permission named send messages.
  5. Copy the generated URL from the bottom of the page and open it in a new tab. Select the Discord server to add the bot to and authorise it. When you navigate to your Discord server, you should see your new bot in the members list in the offline section.

Install guide

The step-by-step tutorial is available in this recipe:

Ensure that you update any constants in your code with your data:

  • DISCORD_CHANNEL_ID - To get the Discord channel ID, make sure Developer Mode is enabled (SettingsAdvancedDeveloper Mode). Once enabled, right-click on the designated server channel and click Copy Channel ID to obtain the channel ID.
  • BOT_TOKEN - See step 2 above to find your Discord bot token.
  • PANDASCORE_TOKEN - Your PandaScore API token is available via your dashboard. You can sign up for free if you do not already have a PandaScore account.

The Discord bot uses the following package versions:


If you have any questions, join our (p)awesome developer and customer Slack.


Your Discord server is unique, and so should the esports experience for your audience. Our Discord bot tutorial puts you in the driving seat, allowing you to customise the notifications and messages sent.

Filter by interest:

With PandaScore covering an average of over 80 matches daily, you may want to filter the matches based on audience interest. For example, filtering by:

  • Participating teams: /matches?filter[opponent_id]={opponent_id_or_slug}.
  • Videogame: /matches?filter[videogame]={videogame_id_or_slug}.
  • Parent tournament: /matches?filter[tournament_id]={tournament_id}.
  • Parent series: /matches?filter[serie_id]={serie_id}.
  • Parent league: /matches?filter[league_id]={league_id}.

These filters can take 1 or more values separated by commas. For example, if you were interested in more than 1 team, you could use the filter /matches?filter[opponent_id]=team_1_id,team_2_id. Filters can also be used together e.g., /matches?filter[league_id]={league_id}&filter[opponent_id]={opponent_id}. To learn more about filtering, please refer to our documentation.

Tailored notifications:

Customise the content of the Discord messages to align with what your community wants. To accompany your match start and end messages, you can use any data points available in the match payload, such as:

  • Match opponents (opponents).
  • Match format and number of games, for example, Best Of 3 (match_type and number_of_games).
  • League/series/tournament names (league.name, serie.full_name, and tournament.name)
  • Videogame name (videogame.name)
  • Streams list (streams_list)
  • Match score (results)
  • Match winner name (winner.name)

Additionally, you can add spoiler-tags in your Discord messages by placing|| before and after the text that is a spoiler. e.g., "Winner team is ||" + match['winner']['name'] + "||".

Example of using spoiler-tags for the winner of a finished match.

Example of using spoiler-tags for the winner of a finished match.