Kick Bot provides a flexible system to create and register your own custom commands. This guide will show you how to create, test, and register custom commands to extend Kick Bot's functionality.
Command Module Structure
A command module is a JavaScript object with the following structure:
const MyCustomCommand = {
// Command name (without the ! prefix)
name: 'commandname',
// Command description (shown in !help)
description: 'Description of what the command does',
// Command usage example
usage: '!commandname [arguments]',
// Command handler function
handler: async ({ username, args, bot, commandManager }) => {
// Command logic goes here
return `Response message to send to chat`;
}
};
Creating Your First Custom Command
Let's create a simple command that returns the current time:
// timeCommand.js
const TimeCommand = {
name: 'time',
description: 'Shows the current time',
usage: '!time',
handler: async ({ username }) => {
const now = new Date();
const timeString = now.toLocaleTimeString();
return `The current time is: ${timeString}`;
}
};
module.exports = TimeCommand;
Integrating Custom Commands into Your Project
There are two ways to register your custom commands:
Method 1: Using the enabledCommands Option
Create a directory for your custom commands, e.g., ./commands/
Method 2: Using the Command Manager After Bot Creation
const { createBot } = require('kickbot');
const TimeCommand = require('./commands/timeCommand');
// Create the bot
const bot = createBot({
// Basic configuration
clientId: 'your-kick-client-id',
clientSecret: 'your-kick-client-secret',
skillfulApiKey: 'your-skillful-api-key',
chatroomId: 'your-chatroom-id'
});
// Register your custom command after creating the bot
bot.messageHandler.commandManager.register(TimeCommand, true);
// Start the bot
bot.start()
.then(() => console.log('Bot started!'))
.catch(error => console.error('Failed to start bot:', error));
Advanced Command Features
Accessing Bot Services
The command handler receives several useful objects:
handler: async ({ username, args, bot, commandManager, getState, setState }) => {
// 'username' - The username of the user who sent the command
// 'args' - Array of command arguments (words after the command name)
// 'bot' - Reference to the KickBot instance
// 'commandManager' - Reference to the CommandManager
// 'getState' - Function to get command state
// 'setState' - Function to set command state
}
Using the Skillful AI Client
You can use the Skillful AI client in your custom commands:
const WeatherCommand = {
name: 'weather',
description: 'Get the weather for a location',
usage: '!weather [location]',
handler: async ({ username, args, bot }) => {
if (!args.length) {
return `Please provide a location. Example: !weather New York`;
}
const location = args.join(' ');
try {
// Use the AI to generate a weather response
const prompt = `Generate a brief, fun weather report for ${location}. Keep it to 1-2 sentences maximum.`;
const response = await bot.skillfulClient.sendMessage(prompt);
return response.text || `Sorry, I couldn't get the weather for ${location}.`;
} catch (error) {
return `Sorry, I couldn't process that request. Error: ${error.message}`;
}
}
};
Maintaining Command State
Commands can maintain state between invocations using the setState and getState functions:
const CounterCommand = {
name: 'counter',
description: 'Counts how many times the command has been used',
usage: '!counter',
handler: async ({ username, getState, setState }) => {
// Get current count
let count = getState('count') || 0;
// Increment count
count++;
// Save updated count (with TTL of 1 hour)
setState('count', count, 3600000);
return `This command has been used ${count} times!`;
}
};
Command with Initialization Logic
Some commands need to perform initialization when they're first enabled. Use the init method for this:
const StreamUptimeCommand = {
name: 'uptime',
description: 'Shows how long the stream has been live',
usage: '!uptime',
// Stream start time
streamStartTime: null,
// Initialization function
init: function(commandManager) {
// Record the time when the command is initialized
this.streamStartTime = new Date();
console.log('Uptime command initialized');
},
handler: async ({ username }) => {
if (!this.streamStartTime) {
return 'Stream start time not available.';
}
const now = new Date();
const uptimeMs = now - this.streamStartTime;
const hours = Math.floor(uptimeMs / (1000 * 60 * 60));
const minutes = Math.floor((uptimeMs % (1000 * 60 * 60)) / (1000 * 60));
return `Stream has been live for ${hours}h ${minutes}m.`;
},
// Cleanup function (called when command is disabled)
cleanup: function() {
this.streamStartTime = null;
console.log('Uptime command cleaned up');
}
};
Best Practices for Custom Commands
Keep responses concise: Chat messages should be brief and to the point
Add error handling: Always handle potential errors in your commands
Respect rate limits: Avoid making too many external API calls
Include help text: Make the command's usage clear in the description
Clean up resources: If your command uses external resources, clean them up in the cleanup method
Testing Your Custom Commands
Before integrating into your bot, you can test your command handler function independently:
