ΠŸΠ΅Ρ€Π΅ΠΉΡ‚ΠΈ ΠΊ ΡΠΎΠ΄Π΅Ρ€ΠΆΠ°Π½ΠΈΡŽ

TS Ρ‡Π°Ρ‚-Π±ΠΎΡ‚ для ΠΎΡ„ΠΈΡ†ΠΈΠ°Π»ΡŒΠ½ΠΎΠ³ΠΎ API MAX#

maxbot-chatbot-ts β€” это Ρ„Ρ€Π΅ΠΉΠΌΠ²ΠΎΡ€ΠΊ для создания ΠΌΠ°ΡΡˆΡ‚Π°Π±ΠΈΡ€ΡƒΠ΅ΠΌΡ‹Ρ… Π±ΠΎΡ‚ΠΎΠ² для MAX BOT API Π½Π° языкС TypeScript (Node.js). ΠŸΠΎΡΡ‚Ρ€ΠΎΠ΅Π½Π½Π°Ρ Π½Π° основС green-api/maxbot-api-client-ts, эта Π±ΠΈΠ±Π»ΠΈΠΎΡ‚Π΅ΠΊΠ° прСдоставляСт ΡƒΠ΄ΠΎΠ±Π½Ρ‹ΠΉ ΠΌΠ°Ρ€ΡˆΡ€ΡƒΡ‚ΠΈΠ·Π°Ρ‚ΠΎΡ€, автоматичСскоС ΠΎΠ±Π½ΠΎΠ²Π»Π΅Π½ΠΈΠ΅ Π΄Π°Π½Π½Ρ‹Ρ… ΠΈ Π½Π°Π΄Π΅ΠΆΠ½Ρ‹ΠΉ ΠΌΠ΅Π½Π΅Π΄ΠΆΠ΅Ρ€ состояний (FSM) для построСния ΠΌΠ½ΠΎΠ³ΠΎΡˆΠ°Π³ΠΎΠ²Ρ‹Ρ… Π΄ΠΈΠ°Π»ΠΎΠ³ΠΎΠ²Ρ‹Ρ… сцСнариСв.

API#

ДокумСнтация ΠΊ REST API MAX находится ΠΏΠΎ ссылкС. Π‘ΠΈΠ±Π»ΠΈΠΎΡ‚Π΅ΠΊΠ° являСтся ΠΎΠ±Ρ‘Ρ€Ρ‚ΠΊΠΎΠΉ ΠΊ REST API, поэтому докумСнтация ΠΏΠΎ ссылкС Π²Ρ‹ΡˆΠ΅ ΠΏΡ€ΠΈΠΌΠ΅Π½ΠΈΠΌΠ° ΠΈ ΠΊ самой Π±ΠΈΠ±Π»ΠΈΠΎΡ‚Π΅ΠΊΠ΅.

Авторизация#

Для использования Π±ΠΈΠ±Π»ΠΈΠΎΡ‚Π΅ΠΊΠΈ потрСбуСтся ΠΏΠΎΠ»ΡƒΡ‡ΠΈΡ‚ΡŒ Ρ‚ΠΎΠΊΠ΅Π½ Π±ΠΎΡ‚Π° Π² консоли Ρ€Π°Π·Ρ€Π°Π±ΠΎΡ‚Ρ‡ΠΈΠΊΠ° MAX API.

Π‘ΠΎΠ΄Π΅Ρ€ΠΆΠ°Π½ΠΈΠ΅#

Как ΠΈΠΌΠΏΠΎΡ€Ρ‚ΠΈΡ€ΠΎΠ²Π°Ρ‚ΡŒ Π±ΠΈΠ±Π»ΠΈΠΎΡ‚Π΅ΠΊΡƒ ΠΈ ΠΈΠ½ΠΈΡ†ΠΈΠΈΡ€ΠΎΠ²Π°Ρ‚ΡŒ своСго Π±ΠΎΡ‚Π°#

ΠœΠ°Ρ€ΡˆΡ€ΡƒΡ‚ΠΈΠ·Π°Ρ†ΠΈΡ ΠΊΠΎΠΌΠ°Π½Π΄ ΠΈ сообщСний#

Π£ΠΏΡ€Π°Π²Π»Π΅Π½ΠΈΠ΅ состояниями ΠΈ сцСны#

ΠžΡ‚Π²Π΅Ρ‚ с ΠΌΠ΅Π΄ΠΈΠ°Ρ„Π°ΠΉΠ»Π°ΠΌΠΈ#

ΠŸΡ€ΠΈΠΌΠ΅Ρ€ эхо-Π±ΠΎΡ‚Π°#

ЛицСнзия#

Как ΠΈΠΌΠΏΠΎΡ€Ρ‚ΠΈΡ€ΠΎΠ²Π°Ρ‚ΡŒ Π±ΠΈΠ±Π»ΠΈΠΎΡ‚Π΅ΠΊΡƒ ΠΈ ΠΈΠ½ΠΈΡ†ΠΈΠΈΡ€ΠΎΠ²Π°Ρ‚ΡŒ своСго Π±ΠΎΡ‚Π°#

Π£Π±Π΅Π΄ΠΈΡ‚Π΅ΡΡŒ, Ρ‡Ρ‚ΠΎ Ρƒ вас установлСна вСрсия Node.js Π½Π΅ Π½ΠΈΠΆΠ΅ 22.18:

node -v  

Установка Π±ΠΈΠ±Π»ΠΈΠΎΡ‚Π΅ΠΊΠΈ:

npm install @green-api/maxbot-chatbot-ts  

Как ΠΈΠ½ΠΈΡ†ΠΈΠ°Π»ΠΈΠ·ΠΈΡ€ΠΎΠ²Π°Ρ‚ΡŒ ΠΎΠ±ΡŠΠ΅ΠΊΡ‚#

Для ΠΈΠ½ΠΈΡ†ΠΈΠ°Π»ΠΈΠ·Π°Ρ†ΠΈΠΈ Π±ΠΎΡ‚Π° Π½ΡƒΠΆΠ½ΠΎ ΠΏΠ΅Ρ€Π΅Π΄Π°Ρ‚ΡŒ Π² Ρ„ΡƒΠ½ΠΊΡ†ΠΈΡŽ main адрСс ΠΏΠ»Π°Ρ‚Ρ„ΠΎΡ€ΠΌΡ‹ MaxBot, MAX token, Π° Ρ‚Π°ΠΊ ΠΆΠ΅ Π·Π°Π΄Π°Ρ‚ΡŒ значСния для RateLimiter ΠΈ Timeout.

ΠŸΠ°Ρ€Π°ΠΌΠ΅Ρ‚Ρ€Ρ‹ ΠΊΠΎΠ½Ρ„ΠΈΠ³ΡƒΡ€Π°Ρ†ΠΈΠΈ:

  • BaseURL - Π‘Π°Π·ΠΎΠ²Ρ‹ΠΉ URL-адрСс сСрвСров ΠΏΠ»Π°Ρ‚Ρ„ΠΎΡ€ΠΌΡ‹ MaxBot. ВсС ΠΌΠ΅Ρ‚ΠΎΠ΄Ρ‹ API Π±ΡƒΠ΄ΡƒΡ‚ ΠΌΠ°Ρ€ΡˆΡ€ΡƒΡ‚ΠΈΠ·ΠΈΡ€ΠΎΠ²Π°Ρ‚ΡŒΡΡ ΠΏΠΎ этому ΠΊΠΎΡ€Π½Π΅Π²ΠΎΠΌΡƒ адрСсу. ΠΠΊΡ‚ΡƒΠ°Π»ΡŒΠ½Ρ‹ΠΉ адрСс ΡƒΠΊΠ°Π·Π°Π½ Π² ΠΎΡ„ΠΈΡ†ΠΈΠ°Π»ΡŒΠ½ΠΎΠΉ Π΄ΠΎΠΊΡƒΠΌΠ΅Π½Ρ‚Π°Ρ†ΠΈΠΈ.
  • Token - Π£Π½ΠΈΠΊΠ°Π»ΡŒΠ½Ρ‹ΠΉ сСкрСтный ΠΊΠ»ΡŽΡ‡ Π°Π²Ρ‚ΠΎΡ€ΠΈΠ·Π°Ρ†ΠΈΠΈ (API-ΠΊΠ»ΡŽΡ‡) вашСго Π±ΠΎΡ‚Π°. ΠŸΠΎΠ»ΡƒΡ‡ΠΈΡ‚ΡŒ Π΅Π³ΠΎ ΠΌΠΎΠΆΠ½ΠΎ Π² Π»ΠΈΡ‡Π½ΠΎΠΌ ΠΊΠ°Π±ΠΈΠ½Π΅Ρ‚Π΅ послС рСгистрации ΠΈΠ»ΠΈ создании Π±ΠΎΡ‚Π° Π½Π° ΠΏΠ»Π°Ρ‚Ρ„ΠΎΡ€ΠΌΠ΅ business.max.ru. Π§ΠΈΡ‚Π°ΠΉΡ‚Π΅ ΠΏΠ΅Ρ€Π΅Π΄ Π½Π°Ρ‡Π°Π»ΠΎΠΌ Ρ€Π°Π±ΠΎΡ‚Ρ‹, Ρ‡Ρ‚ΠΎΠ±Ρ‹ ΠΏΠΎΠ»ΡƒΡ‡ΠΈΡ‚ΡŒ Ρ‚ΠΎΠΊΠ΅Π½.
  • ratelimiter - ВстроСнный ΠΎΠ³Ρ€Π°Π½ΠΈΡ‡ΠΈΡ‚Π΅Π»ΡŒ частоты запросов. Он ΠΊΠΎΠ½Ρ‚Ρ€ΠΎΠ»ΠΈΡ€ΡƒΠ΅Ρ‚ количСство исходящих запросов Π² сСкунду (RPS), защищая Π±ΠΎΡ‚Π° ΠΎΡ‚ Π±Π»ΠΎΠΊΠΈΡ€ΠΎΠ²ΠΊΠΈ со стороны сСрвСра Π·Π° ΠΏΡ€Π΅Π²Ρ‹ΡˆΠ΅Π½ΠΈΠ΅ Π»ΠΈΠΌΠΈΡ‚ΠΎΠ². Π Π΅ΠΊΠΎΠΌΠ΅Π½Π΄ΡƒΠ΅ΠΌΠΎΠ΅ Π·Π½Π°Ρ‡Π΅Π½ΠΈΠ΅ β€” Π½Π΅ ΠΌΠ΅Π½Π΅Π΅ 25, Π½ΠΎ Π½Π΅ Π±ΠΎΠ»Π΅Π΅ 30.
  • timeout - МаксимальноС врСмя оТидания ΠΎΡ‚Π²Π΅Ρ‚Π° ΠΎΡ‚ сСрвСра (Π² сСкундах). Если сСрвСр Π½Π΅ ΠΎΡ‚Π²Π΅Ρ‚ΠΈΡ‚ Π² Ρ‚Π΅Ρ‡Π΅Π½ΠΈΠ΅ этого Π²Ρ€Π΅ΠΌΠ΅Π½ΠΈ, запрос Π±ΡƒΠ΄Π΅Ρ‚ Π·Π°Π²Π΅Ρ€ΡˆΠ΅Π½ с ошибкой. ΠžΠΏΡ‚ΠΈΠΌΠ°Π»ΡŒΠ½ΠΎΠ΅ Π·Π½Π°Ρ‡Π΅Π½ΠΈΠ΅ β€” 30 сСкунд.
async function bootstrap() {
    const api = new MaxBotAPI({
        base_url: "https://platform-api.max.ru", /* Base url for MAX API requests */
        token: "YOUR_BOT_TOKEN",                 /* Max bot token */
        ratelimiter: 25,
        timeout: 30000
    });

ΠŸΡ€ΠΈΠΌΠ΅Ρ€ ΠΈΠ½ΠΈΡ†ΠΈΠ°Π»ΠΈΠ·Π°Ρ†ΠΈΠΈ Π±ΠΎΡ‚Π°#

    import { MaxBotAPI } from '@green-api/maxbot-api-client-ts';
    import { Bot } from '@green-api/maxbot-chatbot-ts';

    async function bootstrap() {
    const api = new MaxBotAPI({
        base_url: "https://platform-api.max.ru", /* Base url for MAX API requests */
        token: "YOUR_BOT_TOKEN",                 /* Max bot token */
        ratelimiter: 25,
        timeout: 30000
    });

    const myBot = new Bot(api);

    try {
        await myBot.start();
    } catch (error) {
        console.error("Error starting bot:", error);
    }
}

bootstrap();

ΠœΠ°Ρ€ΡˆΡ€ΡƒΡ‚ΠΈΠ·Π°Ρ†ΠΈΡ ΠΊΠΎΠΌΠ°Π½Π΄ ΠΈ сообщСний#

ВстроСнный ΠΌΠ°Ρ€ΡˆΡ€ΡƒΡ‚ΠΈΠ·Π°Ρ‚ΠΎΡ€ ΡƒΠΏΡ€ΠΎΡ‰Π°Π΅Ρ‚ ΠΎΠ±Ρ€Π°Π±ΠΎΡ‚ΠΊΡƒ ΠΊΠΎΠΌΠ°Π½Π΄, ΠΎΠ±Ρ€Π°Ρ‚Π½Ρ‹Ρ… Π²Ρ‹Π·ΠΎΠ²ΠΎΠ² (ΠΊΠΎΠ»Π±Π΅ΠΊΠΎΠ²) ΠΈ ΠΎΠ±Π½ΠΎΠ²Π»Π΅Π½ΠΈΠΉ.

    import { UpdateType, Format } from '@green-api/maxbot-api-client-ts';

    myBot.router.command("/start", async (n) => {
        await n.reply("Hello! Welcome to the MAX Bot.");
    });

    myBot.router.register(UpdateType.MessageCreated, async (n) => {
        const text = n.text();
        if (text === "ping") {
            await n.reply("pong", Format.Markdown);
        }
    });

    myBot.router.callback("accept_rules_payload", async (n) => {
        await n.reply("*Thank you for accepting the rules!*", Format.Markdown);
        await n.answerCallback("Rules accepted");
    });

Π£ΠΏΡ€Π°Π²Π»Π΅Π½ΠΈΠ΅ состояниями ΠΈ сцСны#

Для слоТных Π±ΠΎΡ‚ΠΎΠ² (Π½Π°ΠΏΡ€ΠΈΠΌΠ΅Ρ€, для рСгистрации ΠΏΠΎΠ»ΡŒΠ·ΠΎΠ²Π°Ρ‚Π΅Π»Π΅ΠΉ, Π²ΠΈΠΊΡ‚ΠΎΡ€ΠΈΠ½ ΠΈΠ»ΠΈ ΠΏΠΎΡˆΠ°Π³ΠΎΠ²Ρ‹Ρ… Ρ„ΠΎΡ€ΠΌ) ΠΈΡΠΏΠΎΠ»ΡŒΠ·ΡƒΠΉΡ‚Π΅ ΠœΠ΅Π½Π΅Π΄ΠΆΠ΅Ρ€ состояний (StateManager) ΠΈ сцСны (Scene). Π‘Ρ†Π΅Π½Π° инкапсулируСт ΠΊΠΎΠ½ΠΊΡ€Π΅Ρ‚Π½ΡƒΡŽ ΡΠΈΡ‚ΡƒΠ°Ρ†ΠΈΡŽ Π² Π΄ΠΈΠ°Π»ΠΎΠ³Π΅ ΠΈ ΠΈΠ·ΠΎΠ»ΠΈΡ€ΡƒΠ΅Ρ‚ Π΅Ρ‘ Π»ΠΎΠ³ΠΈΠΊΡƒ.

class RegistrationScene implements Scene {
    async start(n: Notification): Promise<void> {
        const text = n.text();

        if (text === "/start") {
            await n.reply("Let's register! What is your *login*?");
            return;
        }

        if (text.length >= 4) {
            n.setData({ login: text });
            await n.reply(`**Login** \`${text}\` accepted. Now enter your **password**:`);
            n.activateNextScene(new PasswordScene());
        } else {
            await n.reply("Login must be **at least 4 characters long**.");
        }
    }
}

class PasswordScene implements Scene {
    async start(n: Notification): Promise<void> {
        const password = n.text();
        const data = n.getData<{ login: string }>();

        await n.reply(`Success! Profile created.\nLogin: \`${data?.login}\`\nPass: \`${password}\``);

        n.activateNextScene(new RegistrationScene());
    }
}

const stateManager = new MapStateManager({ step: "start" });
stateManager.setStartScene(new RegistrationScene());

myBot.withStateManager(stateManager);

ΠžΡ‚Π²Π΅Ρ‚ с ΠΌΠ΅Π΄ΠΈΠ°Ρ„Π°ΠΉΠ»Π°ΠΌΠΈ#

ΠžΠ±Π΅Ρ€Ρ‚ΠΊΠ° Notification содСрТит Π³ΠΎΡ‚ΠΎΠ²Ρ‹Π΅ асинхронныС ΠΌΠ΅Ρ‚ΠΎΠ΄Ρ‹ для ΠΎΡ‚ΠΏΡ€Π°Π²ΠΊΠΈ Ρ„Π°ΠΉΠ»ΠΎΠ², Π³Π΅ΠΎΠ»ΠΎΠΊΠ°Ρ†ΠΈΠΉ, стикСров ΠΈ статусов Π½Π°Π±ΠΎΡ€Π° тСкста.

myBot.router.command("/photo", async (n) => {
    await n.replyWithMedia(
        "Check out this image!",
        "https://example.com/image.png",
        Format.Markdown
    );
});

ΠŸΡ€ΠΈΠΌΠ΅Ρ€ эхо-Π±ΠΎΡ‚Π°#

Для ΠΏΡ€ΠΈΠΌΠ΅Ρ€Π° Ρ‚ΠΎΠ³ΠΎ, ΠΊΠ°ΠΊ Ρ€Π°Π±ΠΎΡ‚Π°Ρ‚ΡŒ с MAX BOT API, ΠΏΡ€Π΅Π΄Π»Π°Π³Π°Π΅ΠΌ Π²Π°ΠΌ ΠΊΠΎΠ΄ эхо Ρ‡Π°Ρ‚-Π±ΠΎΡ‚Π°:

import { MaxBotAPI, UpdateType } from '@green-api/maxbot-api-client-ts';
import { Bot, MapStateManager } from '@green-api/maxbot-chatbot-ts';

async function main() {
    const api = new MaxBotAPI({
        base_url: "https://platform-api.max.ru", /* Base url for MAX API requests */
        token: "YOUR_BOT_TOKEN",                 /* Max bot token */
    });

    const bot = new Bot(api);
    bot.withStateManager(new MapStateManager({}));

    bot.router.register(UpdateType.MessageCreated, async (n) => {
        const text = n.text();

        if (text && !text.startsWith('/')) {
            await n.reply(`**Echo:** ${text}`);
        }
    });

    process.on('SIGINT', () => {
        console.log("Shutting down...");
        bot.stop();
        process.exit(0);
    });

    try {
        await bot.start();
    } catch (error) {
        console.error("Bot initialization error:", error);
    }
}

main();

ЛицСнзия#

Π›ΠΈΡ†Π΅Π½Π·ΠΈΡ€ΠΎΠ²Π°Π½ΠΎ Π² соотвСтствии с MIT.