Skip to main content

Bot lists

The BotlistService posts your server count to bot list sites, receives their vote webhooks and asks them whether a user voted.

Supported lists​

ListServer countVote webhook routeVote check
top.ggtotal and shard countvoting/topggyes
discordbotlist.comper shardvoting/discordbotlistcomthe last 500 votes
botlist.metotal and shard countvoting/botlistmeyes
discord.bots.ggtotalnoneno

top.gg uses its API v1. The statsToken for top.gg is a v1 project token from your bot's settings on top.gg.

Configure a list​

Each list takes a BotListConfig. It reads well from JSON, so it fits into your bot's configuration file:

{
"name": "top.gg",
"statsToken": "token to post stats",
"voteToken": "secret the list sends with every vote",
"guildId": 264445053596991498,
"profileUrl": "https://top.gg/bot/your-bot-id",
"voteUrl": "https://top.gg/bot/your-bot-id/vote"
}

Use empty strings for values you do not have. profileUrl and voteUrl must start with the list's address when they are set.

Start the service​

BotlistService.build(shardManager,
() -> shardManager.getGuilds().size(),
() -> shardManager.getUsers().size())
.forTopGG(config.topGg())
.forDiscordBotListCOM(config.discordBotlistCom())
.forDiscordBotsGG(config.discordBotsGg())
.forBotlistMe(config.botlistMe())
.withVoteService(votes -> votes.withVoteWeebhooks(javalin)
.onVote(vote -> rewards.give(vote.userId(), vote.listId()))
.build())
.build();
MethodDefaultWhat it does
withSubmitInterval(interval, unit)60 minutesHow often the counts are posted. The first post happens after one interval unit.
withExecutorService(executor)a single threadWhere the posts run.
withVoteService(...)noneReceives vote webhooks. Without it, votes are not received.

Votes​

withVoteWeebhooks(javalin) registers one POST route per list on your Javalin instance. withVoteWeebhooks(host, port) starts a Javalin server of its own instead. Point each list's webhook at the route from the table above.

A vote request must carry the list's voteToken in the Authorization header, otherwise it is answered with 401.

Your onVote consumer gets a VoteData:

MethodContent
listId()The list, for example top.gg.
userId()The user who voted.
bonus()true for weekend votes on top.gg.
guildId()For top.gg, the guildId query parameter of the webhook URL. 0 otherwise.

Check a vote​

hasVoted(user) asks every list with a vote check and returns the lists the user has an active vote on:

List<BotList> voted = botlistService.hasVoted(user);

Answers are kept for a minute per list and user. A list that cannot be reached counts as "not voted". Prefer the webhooks to react to votes; the check is for looking up a single user.

Add another list​

BotList.builder(name) builds a list of your own:

BotList myList = BotList.builder("mylist.example")
.forClient(shardManager)
.withBaseUrl("https://mylist.example/api")
.withAuthentication(AuthHandler.of(statsToken))
.withSubmission(StatsMapper.of("bots/{id}/stats", (data, map) -> map.add("servers", data.guilds())))
.withVoteReceiver(VoteReceiver.create(MyVotePayload.class, AuthHandler.of(voteToken)))
.withVoteChecker(new VotingCheckingService<>("bots/{id}/votes/{user}", MyVoteCheck.class))
.build();

{id} is replaced with your application id and {user} with the id of the user to check. Register the list with forBotlist(myList).

PartWhat it does
AuthHandler.of(token)Sends the token in the Authorization header. AuthHandler.bearer(token) adds Bearer .
StatsMapper.of(route, mapper)Posts the stats. StatsMapper.of("PATCH", route, mapper) uses another HTTP method.
useShardStats(true)Sends one request per shard. Write data.shardId() into the body when you use it. The default is the total.
VoteReceiver.create(payload, auth)Receives webhooks. The payload implements VoteDataAdapter and turns the body into a VoteData. Override injectGuild(long) to receive the guildId query parameter.
VotingCheckingServiceCalls the vote check route. The response class implements VotePayload.