Build on Yapit.

Your first bot

This minimal example connects to Yapit and replies to !ping in a guild where the bot is installed. Enable messages.read and messages.write in the bot dashboard for this example.

import { YapitBot } from 'yapit-bot-sdk';

const bot = new YapitBot({
  token: process.env.YAPIT_BOT_TOKEN,
  baseUrl: process.env.YAPIT_API_URL || 'https://yapit.online',
});

bot.on('ready', ({ bot: me }) => {
  console.log('Connected as ' + me.username);
});

bot.on('messageCreate', async (message) => {
  if (message.author.isBot) return;
  if (message.content.trim().toLowerCase() === '!ping') {
    await bot.sendMessage(message.channelId, 'Pong!');
  }
});

await bot.start();

Keep YAPIT_BOT_TOKEN in your environment, not in browser code or a public repository. See Security for more.

Install locally

Extract the SDK beside your bot project, then install it from your bot project's directory:

npm install ../yapit-bot-sdk

Core methods

Runtime notes

• Use a host that supports a persistent Node.js process and environment variables. A static-only website host cannot keep a bot running.
• The SDK stores separate event cursors in .yapit-event-cursor.json, so each stream can advance independently.
• Pollers are started automatically by bot.start() for the scopes granted to your bot.
• Call await bot.stop() when shutting down cleanly.

Base URL and authentication

POST https://yapit.online/api.php?a=bot_me
Authorization: Bearer YOUR_BOT_TOKEN
Content-Type: application/json

{}

curl -X POST "https://yapit.online/api.php?a=bot_me" \
  -H "Authorization: Bearer $YAPIT_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

const res = await fetch('https://yapit.online/api.php?a=bot_me', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + process.env.YAPIT_BOT_TOKEN,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
console.log(await res.json());

Use the action name in the a query parameter. The request body is JSON. Do not send the bot token as a URL parameter.

Available actions

The current bot API uses REST requests and event polling. It does not provide a public WebSocket gateway, webhooks, voice support or message attachments.

Apply permission changes

1. Open Developers → Manage bot → Permissions in Yapit.
2. Enable the scopes your bot needs and save the changes.
3. Restart your Node.js bot so the SDK reloads its granted scopes.

1. Enable the required scopes

Enable commands to register commands and receive invocations. Enable messages.write if the bot will answer using interaction.reply(). You do not need messages.read for slash commands.

2. Register the command definitions

Call registerCommands() with the complete command list. Registration replaces the current list; it does not append to it.

await bot.registerCommands([
  { name: 'ping', description: 'Check whether the bot is online.' },
  {
    name: 'say',
    description: 'Repeat text in this channel.',
    options: [
      {
        name: 'text',
        description: 'Text to repeat.',
        type: 'string',
        required: true
      }
    ]
  }
]);

3. Handle command interactions

bot.on('interactionCreate', async (interaction) => {
  if (interaction.commandName === 'ping') {
    await interaction.reply('Pong!');
  } else if (interaction.commandName === 'say') {
    await interaction.reply(interaction.options.getString('text'));
  }
});

await bot.start();

Command and option limits

• Up to 100 commands per bot and up to 25 options per command.
• Command names are 1–32 lowercase letters, numbers, underscores or hyphens.
• Descriptions are 1–100 characters. String option values are limited to 1,000 characters.
• Supported option types: string, integer, number, boolean and user.
• Use getString, getInteger, getNumber, getBoolean or getUser to read values.

What users type

For one option, users can enter /say Hello there. For several options, named pairs such as /profile user:<@123456789012> are recommended. A user option must identify a member of the current guild.

Message events

Enable messages.read to receive message events. The SDK emits messageCreate for new messages.

Channel mentions

The SDK emits mention_channel when a valid channel is mentioned with #. The event contains channel, sourceChannel, guild, author and the normalized message. Mentioned channel IDs are resolved only inside the message's own guild.

bot.on('mention_channel', ({ channel, sourceChannel, author, message }) => {
  console.log(
    author.username + ' mentioned #' + channel.name +
    ' in #' + sourceChannel.name
  );
});

Member and moderation events

Guild-management events

Enable manage_guild to receive guild configuration and role lifecycle events. The SDK emits manage_guild and direct action events such as guild_update, role_create, role_update, role_delete and roles_reordered, along with camel-case aliases.

Independent cursors

Each stream has its own saved cursor in .yapit-event-cursor.json: cursor for messages, memberCursor for member events, guildCursor for guild events and interactionCursor for slash commands. A failure in one stream does not stop the others.

Suggested environment

YAPIT_BOT_TOKEN=your_private_bot_token
YAPIT_API_URL=https://yapit.online

Never expose a real token in an issue report or support request. If you need help debugging a bot, share the error message and remove credentials first.