LoopBot SDK TypeScript

The official library for building LoopBot bots using TypeScript/JavaScript.

Installation

npm install loopbot-sdk

Initialization

import { Bot } from 'loopbot-sdk';

const bot = new Bot({
    token: 'your_token_here'
});

// ... your commands here ...

bot.start();

Complete Guide

Working with Embeds

Embeds are rich messages that allow you to display information in a structured way.

import { EmbedBuilder } from 'loopbot-sdk';

bot.command('embed_demo', 'Embed Demo', (ctx) => {
    // Creating an embed
    const embed = new EmbedBuilder()
        .setTitle('Embed Title')
        .setDescription('Detailed description here...')
        .setColor(0x00FF00) // Hex color (e.g., Green)
        .setURL('https://loopbot.app')
        .setFooter('Footer Text', 'https://example.com/icon.png')
        .setAuthor('Author Name', 'https://profile.com', 'https://avatar.com/img.png')
        .setImage('https://example.com/large_image.png')
        .setThumbnail('https://example.com/thumbnail.png')
        .addField('Field 1', 'Value 1', true) // inline = true
        .addField('Field 2', 'Value 2', true)
        .setTimestamp(); // Uses current time if not specified

    // Sending the embed
    ctx.reply({ embeds: [embed] });
});

Working with Containers (Components V2)

Containers are advanced components that allow you to visually group other components like text, separators, and galleries.

Note: To send containers, use the replyWithComponents or updateWithComponents methods.

import { ContainerBuilder, SeparatorBuilder, MediaGalleryBuilder } from 'loopbot-sdk';

bot.command('container_demo', 'Container Demo', (ctx) => {
    // Creating a container
    const container = new ContainerBuilder()
        .setAccentColor(0xFF0000) // Sidebar color
        .setSpoiler(false) // Whether content is a spoiler
        .addText('# Title inside Container')
        .addText('This is normal text inside the container.');

    // Adding a Separator
    // spacing: 1 (small) or 2 (large)
    container.addSeparator(true, 1);

    // Adding a Media Gallery
    const gallery = new MediaGalleryBuilder()
        .addItem('https://example.com/img1.png', 'Caption 1')
        .addItem('https://example.com/img2.png', 'Caption 2');
        
    container.addComponent(gallery);

    // Sending the container
    ctx.replyWithComponents({ components: [container] });
});

Separators

Separators help visually organize content within containers or as standalone components.

import { SeparatorBuilder } from 'loopbot-sdk';

// Separator with visible line and large spacing
const sep = new SeparatorBuilder()
    .setDivider(true)
    .setSpacing(2);

// Can be added to a container
container.addComponent(sep);

Replying to Interactions

The context (ctx) provides various methods to respond to commands and interactions.

Reply with Text and Embeds

// Text only
ctx.reply({ content: 'Hello world!' });

// Text and Embed
ctx.reply({ 
    content: 'Check this out:', 
    embeds: [embed] 
});

// Ephemeral response (visible only to the user who ran the command)
ctx.reply({ 
    content: 'Secret...', 
    ephemeral: true 
});

Reply with Components V2 (Containers)

To send Containers, Galleries, or Separators as the main response.

ctx.replyWithComponents({ components: [container1, container2] });

Updating the Original Message

Useful for button or select menu interactions where you want to change the original message instead of sending a new one.

bot.onButton('my_button', (ctx) => {
    // Update text and embeds of the message where the button was
    const embed = new EmbedBuilder().setTitle('Updated!');
    
    ctx.update({ 
        content: 'New message', 
        embeds: [embed] 
    });

    // Or to update with Containers
    // ctx.updateWithComponents({ components: [newContainer] });
});

Editing the Response (Follow-up)

If you have already replied (e.g., with defer or a quick response) and want to edit that response later.

bot.command('process', 'Long processing', async (ctx) => {
    // Acknowledge processing
    ctx.defer();
    
    // ... long processing ...
    
    // Edit the original response
    await ctx.editReply({ 
        content: 'Processing complete!', 
        embeds: [resultEmbed] 
    });
});

Buttons and Action Rows

Buttons are interactive components that users can click. They must be placed inside an ActionRow.

import { ActionRowBuilder, ButtonBuilder, ButtonStyle } from 'loopbot-sdk';

bot.command('buttons', 'Button demo', (ctx) => {
    // Creating buttons
    const btnPrimary = new ButtonBuilder()
        .setLabel('Click here')
        .setCustomId('btn_click')
        .setStyle(ButtonStyle.PRIMARY); // Blue

    const btnLink = new ButtonBuilder()
        .setLabel('Visit Website')
        .setURL('https://loopbot.app')
        .setStyle(ButtonStyle.LINK); // Gray

    // Adding to ActionRow
    const row = new ActionRowBuilder()
        .addButton(btnPrimary)
        .addButton(btnLink);

    ctx.reply({ content: 'Choose an option:', components: [row] });
});

bot.onButton('btn_click', (ctx) => {
    ctx.reply({ content: 'You clicked the button!', ephemeral: true });
});

Select Menus (Dropdowns)

Select menus allow users to choose one or more options from a list.

import { SelectMenuBuilder, ActionRowBuilder } from 'loopbot-sdk';

bot.command('menu', 'Menu demo', (ctx) => {
    const select = new SelectMenuBuilder()
        .setCustomId('select_menu')
        .setPlaceholder('Choose your class')
        .addOption('Warrior', 'warrior', 'Melee combat class')
        .addOption('Mage', 'mage', 'Magic class', { name: '🔮' })
        .setMinValues(1)
        .setMaxValues(1);

    const row = new ActionRowBuilder().addSelectMenu(select);
    ctx.reply({ content: 'Select your class:', components: [row] });
});

bot.onSelect('select_menu', (ctx) => {
    const value = ctx.values[0];
    ctx.reply({ content: `You selected: ${value}`, ephemeral: true });
});

Modals (Forms)

Modals are pop-up windows with forms for text input.

import { ModalBuilder } from 'loopbot-sdk';

bot.command('feedback', 'Send feedback', (ctx) => {
    const modal = new ModalBuilder()
        .setCustomId('feedback_modal')
        .setTitle('Give us your feedback')
        .addTextInput(
            'input_msg',
            'Message',
            'paragraph', // or 'short'
            {
                placeholder: 'Write here...',
                required: true
            }
        );
    
    ctx.showModal(modal);
});

Advanced Layout (Sections)

Sections allow you to group text with a side "accessory" like a button or image.

import { SectionBuilder, ButtonBuilder, ButtonStyle } from 'loopbot-sdk';

bot.command('section', 'Section Demo', (ctx) => {
    const btn = new ButtonBuilder()
        .setLabel('See More')
        .setURL('https://google.com')
        .setStyle(ButtonStyle.LINK);

    const section = new SectionBuilder()
        .addText('**Section Title**')
        .addText('Detailed description next to the button.')
        .setButtonAccessory(btn);

    ctx.replyWithComponents({ components: [section] });
});

Files

Sending files as attachments or within structures.

import { FileBuilder } from 'loopbot-sdk';

const file = new FileBuilder('https://example.com/file.pdf').setSpoiler(false);
// Add to a container or send as supported by API

Quick Reference

| Feature | Builder / Method | | :--- | :--- | | Embed | EmbedBuilder | | Container | ContainerBuilder | | Separator | SeparatorBuilder | | Gallery | MediaGalleryBuilder | | Button | ButtonBuilder | | Action Row | ActionRowBuilder | | Select Menu | SelectMenuBuilder | | Modal | ModalBuilder | | Section | SectionBuilder | | File | FileBuilder | | Reply | ctx.reply(...) | | Reply (Container) | ctx.replyWithComponents(...) | | Update Msg | ctx.update(...) | | Edit Reply | ctx.editReply(...) |

Direct Messaging API

Send messages outside of interaction context, manage channels, roles, and more.

Sending Messages

// Send a message to any channel
await bot.send(channelId, { content: 'Hello!' });

// Edit a message
await bot.editMessage(channelId, messageId, { content: 'Updated!' });

// Delete a message
await bot.deleteMessage(channelId, messageId);

Channel Management

// Create a channel
await bot.createChannel(guildId, { name: 'new-channel', topic: 'Description' });

// Modify a channel
await bot.modifyChannel(channelId, { name: 'renamed-channel' });

// Delete a channel
await bot.deleteChannel(channelId);

Forum Channels

// Create a forum post
await bot.createForumPost(forumChannelId, {
    name: 'My Post Title',
    message: { content: 'Post content here' },
    applied_tags: ['tagId']
});

// Get/modify forum tags
const tags = await bot.getForumTags(forumChannelId);
await bot.modifyForumTags(forumChannelId, [{ name: 'New Tag' }]);

// Archive/lock threads
await bot.archiveThread(threadId);
await bot.lockThread(threadId);

Roles

// Get roles
const roles = await bot.getRoles(guildId);

// Create a role
await bot.createRole(guildId, { name: 'Moderator', color: 0x00FF00 });

// Modify a role
await bot.modifyRole(guildId, roleId, { name: 'Admin', hoist: true });

// Delete a role
await bot.deleteRole(guildId, roleId);

// Reorder roles
await bot.reorderRoles(guildId, [{ id: roleId, position: 2 }]);

Webhooks

// Create a webhook
const webhook = await bot.createWebhook(channelId, { name: 'My Webhook' });

// Send message via webhook
await bot.executeWebhook(webhookId, webhookToken, {
    content: 'Message via webhook!',
    username: 'Custom Name'
});

// Edit/delete webhook message
await bot.editWebhookMessage(webhookId, webhookToken, messageId, { content: 'Updated' });
await bot.deleteWebhookMessage(webhookId, webhookToken, messageId);

// Delete webhook
await bot.deleteWebhook(webhookId);

Member Management

// Add/remove roles
await bot.addMemberRole(guildId, userId, roleId);
await bot.removeMemberRole(guildId, userId, roleId);

// Kick/ban members
await bot.kickMember(guildId, userId);
await bot.banMember(guildId, userId);