Skip to content
NDC Developer Docs

Building Your First NDC Bot

In this guide, you will build a simple “Ping-Pong” bot for NDC. When a user sends !ping in any channel your bot can see, the bot will immediately reply with Pong! 🏓.

How NDC Bots Work

Section titled “How NDC Bots Work”

NDC uses a modern, two-part architecture for bots:

  1. The Gateway (WebSocket): A persistent connection where NDC pushes real-time events to your bot (e.g. MESSAGE_CREATE, READY, GUILD_CREATE).
  2. The REST API (HTTP): Standard HTTP endpoints for actions (e.g. sending a message, creating a channel, adding reactions).

Prerequisites

Section titled “Prerequisites”

Before writing code, make sure you have:

  1. Created an Application in the Developer Portal and copied your Bot Token.
  2. Invited your bot to an NDC server with the Send Messages permission.
  3. Node.js (v18+) or Python (v3.10+) installed on your machine.

Choose Your Language

Section titled “Choose Your Language”

1. Initialize Your Project

Section titled “1. Initialize Your Project”

Open a terminal, create a new folder, and initialize a Node.js project:

Terminal window
mkdir ndc-ping-bot
cd ndc-ping-bot
npm init -y
npm install ws dotenv

2. Configure Your Environment

Section titled “2. Configure Your Environment”

Create a .env file to securely store your token:

Terminal window
NDC_BOT_TOKEN=your_bot_token_here
NDC_API_URL=https://chat.nexoriadevelopment.com/api/v1
NDC_GATEWAY_URL=wss://chat.nexoriadevelopment.com/gateway?v=1&encoding=json

3. Create bot.js

Section titled “3. Create bot.js”

Create a file named bot.js and paste the following code:

require('dotenv').config();
const WebSocket = require('ws');


const TOKEN = process.env.NDC_BOT_TOKEN;
const API_URL = process.env.NDC_API_URL;
const GATEWAY_URL = process.env.NDC_GATEWAY_URL;


if (!TOKEN) {
  console.error("Error: NDC_BOT_TOKEN is missing in your .env file!");
  process.exit(1);
}


// 1. Helper function to send messages via NDC REST API
async function sendMessage(channelId, content) {
  try {
    const res = await fetch(`${API_URL}/channels/${channelId}/messages`, {
      method: 'POST',
      headers: {
        'Authorization': `Bot ${TOKEN}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ content }),
    });


    if (!res.ok) {
      const err = await res.text();
      console.error(`Failed to send message (${res.status}):`, err);
    }
  } catch (error) {
    console.error('Error sending message:', error);
  }
}


// 2. Connect to the NDC Gateway WebSocket
console.log('Connecting to NDC Gateway...');
const ws = new WebSocket(GATEWAY_URL);
let heartbeatTimer = null;
let lastSequence = null;


ws.on('open', () => {
  console.log('Connected to Gateway socket!');
});


ws.on('message', async (data) => {
  const payload = JSON.parse(data.toString());
  const { op, d, s, t } = payload;


  if (s !== null) {
    lastSequence = s;
  }


  // Opcode 10: Hello -> Start Heartbeating & Send Identify
  if (op === 10) {
    const { heartbeat_interval } = d;
    console.log(`Received Hello! Heartbeat interval: ${heartbeat_interval}ms`);


    // Start sending periodic heartbeats (Opcode 1)
    heartbeatTimer = setInterval(() => {
      ws.send(JSON.stringify({ op: 1, d: lastSequence }));
    }, heartbeat_interval);


    // Send Identify (Opcode 2) to log in with your Bot Token
    ws.send(JSON.stringify({
      op: 2,
      d: {
        token: TOKEN,
        properties: {
          os: process.platform,
          browser: 'ndc-simple-bot',
          device: 'ndc-simple-bot',
        },
      },
    }));
  }


  // Opcode 0: Dispatch Events
  if (op === 0) {
    // When the bot successfully logs in
    if (t === 'READY') {
      console.log(`Logged in as ${d.user.username}#${d.user.discriminator || '0'}!`);
      console.log('Bot is online and ready to listen for messages.');
    }


    // When a message is sent in any channel
    if (t === 'MESSAGE_CREATE') {
      // Ignore messages sent by other bots or ourself
      if (d.author.bot) return;


      const content = d.content ? d.content.trim() : '';


      // Check for !ping command
      if (content.toLowerCase() === '!ping') {
        console.log(`Received !ping in channel ${d.channel_id} from ${d.author.username}`);
        await sendMessage(d.channel_id, 'Pong! 🏓 Greetings from my first NDC Bot!');
      }
    }
  }
});


ws.on('close', (code, reason) => {
  clearInterval(heartbeatTimer);
  console.log(`Gateway connection closed (${code}): ${reason.toString()}`);
});


ws.on('error', (err) => {
  console.error('Gateway WebSocket error:', err);
});

4. Run Your Bot!

Section titled “4. Run Your Bot!”
Terminal window
node bot.js

You will see:

Connecting to NDC Gateway...
Connected to Gateway socket!
Received Hello! Heartbeat interval: 41250ms
Logged in as My Helper Bot!
Bot is online and ready to listen for messages.

Go to your NDC server, type !ping in any channel the bot has access to, and watch it reply with Pong! 🏓!

Expanding Your Bot

Section titled “Expanding Your Bot”

Now that your bot can listen for messages and respond, check out the API guides to add more features: