Tracking Users

Track active users interacting with your bot. This helps you understand engagement — how many unique users your bot serves, and how they interact with it.

Basic Usage

JavaScript / TypeScript

Track a user

typescript

cordia.trackUser({
  userId: '123456789',
});

Python

Track a user

python

await cordia_client.track_user(
    user_id="123456789",
    action="message",
)

Full Payload

JavaScript / TypeScript

Full user tracking

typescript

cordia.trackUser({
  userId: '123456789',      // Required: Discord user ID
  guildId: '987654321',     // Optional: which server
  action: 'message',        // Optional: type of interaction
});

Python

Full user tracking

python

await cordia_client.track_user(
    user_id="123456789",           # Required: Discord user ID
    guild_id="987654321",          # Optional: which server
    action="message",              # Optional: type of interaction
)

Payload Reference

Field	JS Type	Python Type	Required	Description
`userId / user_id`	`string`	`str`	✅ Yes	The Discord user ID
`guildId / guild_id`	`string`	`str`	No	Guild/server ID where the user is active
`action`	`string`	`str`	No	Type of action (e.g., "message", "reaction", "voice_join")

Discord.js Examples

Track on messages

typescript

// Track users who send messages
client.on('messageCreate', (message) => {
  if (message.author.bot) return;

  cordia.trackUser({
    userId: message.author.id,
    guildId: message.guildId ?? undefined,
    action: 'message',
  });
});

Track on reactions

typescript

// Track users who add reactions
client.on('messageReactionAdd', (reaction, user) => {
  if (user.bot) return;

  cordia.trackUser({
    userId: user.id,
    guildId: reaction.message.guildId ?? undefined,
    action: 'reaction',
  });
});

Discord.py Examples

Track on messages

python

@bot.event
async def on_message(message):
    if message.author.bot:
        return

    await cordia_client.track_user(
        user_id=str(message.author.id),
        guild_id=str(message.guild.id) if message.guild else None,
        action="message",
    )

    await bot.process_commands(message)

Track on reactions

python

@bot.event
async def on_reaction_add(reaction, user):
    if user.bot:
        return

    await cordia_client.track_user(
        user_id=str(user.id),
        guild_id=str(reaction.message.guild.id) if reaction.message.guild else None,
        action="reaction",
    )

💡Deduplication

The Cordia backend automatically deduplicates user events, so even if a user sends 100 messages, they'll only count as 1 active user for that period.

⚠️Privacy

The SDK only sends the Discord user ID — no usernames, emails, or other personally identifiable information. All data is anonymized on our servers.

Commands

Guild Count