@messanger/bot-sdk

Official Bot SDK for Mess&Anger Messenger — Build powerful P2P bots with TypeScript

🚀 Features

• ✅ Command Routing — /command handlers with auto-matching
• ✅ Message Handling — Text, media, and callback messages
• ✅ Inline Keyboards — Beautiful button layouts
• ✅ FSM Support — Multi-step conversations out of the box
• ✅ Webhooks — External integrations (Paymento, APIs)
• ✅ Payments — Accept Stars from users
• ✅ Analytics — Track bot usage and performance
• ✅ P2P Native — No servers required, direct WebRTC connections
• ✅ TypeScript — Full type safety

📦 Installation

npm install @messanger/bot-sdk

📖 Quick Start

1. Create a Bot

First, create a bot in Mess&Anger:

1. Open Settings → Bots → Create Bot
2. Enter name, description, commands
3. Copy the token

2. Write Bot Code

import { MessAngerBot, InlineKeyboardBuilder } from '@messanger/bot-sdk';

// Initialize bot
const bot = new MessAngerBot({
  token: 'bot:your-token-here',
  name: 'MyHelperBot',
  commands: [
    { command: '/start', description: 'Start the bot' },
    { command: '/help', description: 'Show help' },
  ],
});

// Handle /start command
bot.onCommand('/start', async (ctx) => {
  await ctx.reply('👋 Привет! Я бот-помощник.\n\nИспользуй /help для списка команд.');
});

// Handle /help command
bot.onCommand('/help', async (ctx) => {
  const keyboard = new InlineKeyboardBuilder()
    .callback('📚 Документация', 'docs')
    .callback('💬 Поддержка', 'support')
    .row()
    .url('🌐 Сайт', 'https://mess.cvr.name')
    .build();

  await ctx.reply('📖 Справка:', { keyboard });
});

// Handle callback queries
bot.onCallbackQuery('docs', async (ctx) => {
  await ctx.answerCallback();
  await ctx.reply('📚 Документация: https://github.com/joker096/mESS/tree/main/docs');
});

bot.onCallbackQuery('support', async (ctx) => {
  await ctx.answerCallback();
  await ctx.reply('💬 Поддержка: @support_bot');
});

// Handle regular messages
bot.onMessage(async (ctx) => {
  if (ctx.text) {
    await ctx.reply(`🤔 Я не понимаю "${ctx.text}". Используй /help для списка команд.`);
  }
});

// Start bot
await bot.start();
console.log('✅ Bot started!');

3. Run Bot

# Development
npx tsx bot.ts

# Production
npm run build
node dist/bot.js

📚 API Reference

MessAngerBot(options)

Main bot class.

| Option | Type | Required | Description | |--------|------|----------|-------------| | token | string | ✅ | Bot token from Mess&Anger | | name | string | ✅ | Display name | | description | string | ❌ | Bot description | | commands | BotCommand[] | ❌ | List of commands |

bot.onCommand(command, handler)

Register command handler.

bot.onCommand('/start', async (ctx) => {
  await ctx.reply('Hello!');
});

bot.onMessage(handler)

Handle non-command messages.

bot.onMessage(async (ctx) => {
  if (ctx.text) {
    await ctx.reply(`You said: ${ctx.text}`);
  }
});

bot.onCallbackQuery(pattern, handler)

Handle inline keyboard callbacks.

bot.onCallbackQuery('settings', async (ctx) => {
  await ctx.answerCallback();
  await ctx.reply('Settings...');
});

bot.setFSM(fsm)

Enable multi-step conversations.

import { BotFSM } from '@messanger/bot-sdk';

const fsm = new BotFSM({
  initialState: 'idle',
  states: {
    idle: {
      onMessage: async (ctx) => {
        if (ctx.text === '/register') return 'waiting_name';
      },
    },
    waiting_name: {
      onEnter: async (ctx) => await ctx.reply('What is your name?'),
      onMessage: async (ctx, fsmCtx) => {
        fsmCtx.data.name = ctx.text;
        return 'done';
      },
    },
    done: {
      onEnter: async (ctx, fsmCtx) => {
        await ctx.reply(`Nice to meet you, ${fsmCtx.data.name}!`);
      },
    },
  },
});

bot.setFSM(fsm);

🎨 Examples

See examples/ directory:

• echo-bot.ts — Simple echo bot
• menu-bot.ts — Bot with inline keyboard menu
• registration-bot.ts — Multi-step registration with FSM
• payment-bot.ts — Bot that accepts payments
• webhook-bot.ts — Bot with external webhooks

🔒 Security

• Tokens are encrypted — never share them publicly
• Bot permissions limit what bots can do
• All P2P messages are E2E encrypted

📄 License

MIT

💬 Support

• Documentation: BOT_API_ARCHITECTURE.md
• Examples: BOT_API_EXAMPLES.md
• Issues: GitHub Issues