Tracking Commands

Track every slash command or message command your bot processes. Cordia will aggregate this data so you can see which commands are most popular, how often they're used, and across which guilds.

Basic Usage

JavaScript / TypeScript

Track a command

typescript

cordia.trackCommand({
  command: 'play',
});

Python

Track a command

python

await cordia_client.track_command(
    command="play",
    user_id=str(ctx.author.id),
)

Full Payload

JavaScript / TypeScript

Full command tracking

typescript

cordia.trackCommand({
  command: 'play',          // Required: the command name
  userId: '123456789',      // Optional: who ran it
  guildId: '987654321',     // Optional: which server
  metadata: {               // Optional: extra data
    query: 'lofi beats',
    source: 'slash_command',
  },
});

Python

Full command tracking

python

await cordia_client.track_command(
    command="play",               # Required: the command name
    user_id="123456789",          # Optional: who ran it
    guild_id="987654321",         # Optional: which server
)

Payload Reference

Field	JS Type	Python Type	Required	Description
`command`	`string`	`str`	✅ Yes	The command name (e.g., "play", "ban", "help")
`userId / user_id`	`string`	`str`	No	Discord user ID who executed the command
`guildId / guild_id`	`string`	`str`	No	Guild/server ID where it was executed

Discord.js Integration

Slash commands

typescript

// Track slash commands
client.on('interactionCreate', async (interaction) => {
  if (!interaction.isChatInputCommand()) return;

  cordia.trackCommand({
    command: interaction.commandName,
    userId: interaction.user.id,
    guildId: interaction.guildId ?? undefined,
  });

  // Handle the command as usual...
});

Prefix commands

typescript

// Track prefix/message commands
client.on('messageCreate', (message) => {
  if (!message.content.startsWith('!')) return;
  if (message.author.bot) return;

  const args = message.content.slice(1).split(' ');
  const command = args.shift()?.toLowerCase();
  if (!command) return;

  cordia.trackCommand({
    command,
    userId: message.author.id,
    guildId: message.guildId ?? undefined,
  });
});

Discord.py Integration

Using commands.Bot

python

@bot.command()
async def play(ctx, *, query: str):
    await ctx.send(f"Playing {query}")

    await cordia_client.track_command(
        command="play",
        user_id=str(ctx.author.id),
        guild_id=str(ctx.guild.id) if ctx.guild else None,
    )

Prefix commands

python

@bot.event
async def on_message(message):
    if message.author.bot:
        return
    if not message.content.startswith("!"):
        return

    command = message.content.split()[0][1:]  # strip "!"

    await cordia_client.track_command(
        command=command,
        user_id=str(message.author.id),
        guild_id=str(message.guild.id) if message.guild else None,
    )

    await bot.process_commands(message)

💡Batching

Command events are automatically batched and sent in groups. You don't need to worry about flooding the API — the SDK handles this for you.

ℹ️Error Handling

If the command name is empty or invalid, the SDK will log a warning but will never throw an error or crash your bot.

Configuration

Users