Posting Bot Stats
Keeping your bot's server count and presence up to date.
Your bot should periodically post its stats so its server count, shard count, and presence stay accurate on its listing.
Endpoint
POST /bots/statsSend an API token for your bot in Authorization, as <token> or
Bot <token>. Create one under API sessions in the bot's dashboard (see
Authentication). There's no rate limit on this
endpoint, so post as often as makes sense for your bot: on every READY or shard
reconnect, and periodically after that. Every 15 to 30 minutes is plenty.
Server listings normally don't need to post anything, because Omniplex keeps their member counts up to date itself. See Posting Server Stats if you'd rather report them.
Body
Every field is optional. Only send what you actually have, omitted fields keep whatever value was last posted rather than being reset to zero.
{
"servers": 1234,
"shards": 4,
"users": 56789,
"shard_list": [0, 1, 2, 3],
"status": "online"
}| Field | Type | Notes |
|---|---|---|
servers | number | Server count. |
shards | number | Shard count. |
users | number | User count. Not currently shown on the site. |
shard_list | number[] | The shard IDs this process handles. |
status | string | One of online, idle, dnd, offline. See below. |
Self-reported presence
Most bots don't share a guild with Omniplex's own Discord client, so there's
usually no real gateway presence to read for your bot. status lets you
report it yourself instead, post it periodically to keep it fresh, it
otherwise keeps showing the last value you sent. Post offline when your bot
shuts down cleanly.
If you never send status at all, but you do post stats regularly with a
nonzero servers count, your bot is still shown as online rather than
falling back to an (almost always stale) gateway-derived status, a recent
stats post is treated as evidence the bot is actually running.
A status you post is the most reliable signal for your bot's status and uptime, especially for bots that use HTTP interactions and have no presence on Discord.
Using an SDK
Every SDK can post stats once, or keep posting them on an interval (30 minutes by default, at least a minute) while your bot runs:
import { Omniplex } from "@omniplex/sdk";
const omniplex = new Omniplex({ token: process.env.OMNIPLEX_TOKEN });
omniplex.autoPostBotStats(() => ({
servers: client.guilds.cache.size,
shards: client.shard?.count ?? 1,
}));