Max Bot API — Skill

Full reference: [[Knowledge/max-bots/max-bot-api]]

Quick Start

const { Bot, Keyboard } = require('@maxhub/max-bot-api');
const bot = new Bot(process.env.MAX_BOT_TOKEN);
bot.start();

Critical Differences from Telegram

Common Patterns

Buttons

Keyboard.button.callback('Text', 'payload')   // callback
Keyboard.button.link('Site', 'https://...')    // external link
Keyboard.button.openApp('Open', appUrl)        // Mini App

User State (quiz/onboarding)

const users = {}; // in production → PostgreSQL or Redis
bot.on('bot_started', ctx => { users[ctx.user().user_id] = { step: 0 }; });
bot.on('message_callback', ctx => {
  const u = users[ctx.user().user_id];
  // switch u.step by payload
});

Mini App — URL with Token

const token = require('crypto').createHash('sha256')
  .update(`${userId}_${Date.now()}`).digest('hex').slice(0, 32);
const url = `https://app.example.com?token=${token}&uid=${userId}`;

Webhook vs Long Polling

• Development: bot.start() — long polling, simple
• Production: webhook HTTPS 443, POST /subscriptions
• If no response for 8 hours → automatic webhook unsubscription

Server Deployment

pm2 start bot.js --name bot-name
pm2 save && pm2 startup

Tokens

⚠️ Store in .env, not in code and not in vault:

MAX_BOT_TOKEN=xxxxx