Installation

Install the Cordia SDK in your Discord bot project using your preferred language and package manager. We support both JS/Node.js and Python.

Requirements

Node.js 18+ or Python 3.8+
A Cordia account — Sign up at cordialane.com to get your API key.

Install the Package

JavaScript / TypeScript

npm

bash

npm install cordia@latest

yarn

bash

yarn add cordia@latest

pnpm

bash

pnpm add cordia@latest

Python

pip

bash

pip install cordia --upgrade

Environment Variables

💡Security First

We recommend storing your API key in environment variables (never hardcode it). Bot ID is auto-detected from your Discord client.

.env

bash

CORDIA_API_KEY=your-api-key-here

Basic Setup & Examples

Discord.js Example

Here's a complete example integrating Cordia with a discord.js bot (v1.2.1+):

bot.ts

typescript

import { Client, GatewayIntentBits } from 'discord.js';
import { CordiaClient } from 'cordia';

const client = new Client({
  intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages],
});

// Create the client — heartbeat starts automatically!
const cordia = new CordiaClient({
  apiKey: process.env.CORDIA_API_KEY!,
  discordClient: client, // botId + shard metadata auto-detected
});

client.on('ready', async () => {
  console.log(`✅ Logged in as ${client.user?.tag}`);
  await cordia.postGuildCount(client.guilds.cache.size);
});

client.on('interactionCreate', async (interaction) => {
  if (!interaction.isChatInputCommand()) return;
  
  // Track the command with Cordia
  cordia.trackCommand({
    command: interaction.commandName,
    userId: interaction.user.id,
    guildId: interaction.guildId ?? undefined,
  });
});

// Graceful shutdown
process.on('SIGINT', async () => {
  await cordia.destroy();
  client.destroy();
  process.exit(0);
});

client.login(process.env.DISCORD_TOKEN);

Discord.py Example

Here's a complete example integrating Cordia with a python discord.py bot (v1.2.1+):

bot.py

python

import discord
from discord.ext import commands
import cordia
import os

intents = discord.Intents.default()
bot = commands.Bot(command_prefix="!", intents=intents)

# Initialize cordia client
cordia_client = cordia.CordiaClient(
    api_key=os.getenv("CORDIA_API_KEY"),
    bot=bot  # bot_id + shard metadata auto-detected
)

@bot.event
async def on_ready():
    print(f"✅ Logged in as {bot.user}")
    await cordia_client.post_guild_count(len(bot.guilds))
    
    # Start the async background heartbeat and queue processor
    cordia_client.start(bot.loop)

@bot.command()
async def ping(ctx):
    await ctx.send("Pong!")
    
    # Track the command with Cordia
    await cordia_client.track_command(
        command="ping",
        user_id=str(ctx.author.id),
        guild_id=str(ctx.guild.id) if ctx.guild else None
    )

bot.run(os.getenv("DISCORD_TOKEN"))

ℹ️What happens on init?

When you initialize the CordiaClient and start it, these things happen automatically:

✅ Config is validated
✅ Heartbeat starts pinging in the background
✅ Event queue is initialized with Adaptive Flushing
✅ Version handshake check is performed

ℹ️Shard Metadata

In v1.2.1+, Cordia SDK auto-detects shardId and totalShards from discord.js/discord.py clients. You can still override these manually when needed.

Next Steps

Now that you have the SDK installed, learn how to configure it for your needs.

Introduction

Configuration