Bot API Nemazing

Боты — это программы, которые общаются с пользователями прямо в чатах: отвечают на команды, присылают уведомления, принимают оплату и работают в группах и каналах.

Bot API — обычный HTTP-интерфейс. Подойдёт любой язык программирования: JavaScript, Python, PHP, Go, Java и другие. Никаких специальных библиотек не нужно — достаточно уметь отправлять HTTP-запросы и разбирать JSON.

Создание бота

1. Откройте в Nemazing чат с @botfather (Nemazing Father) — он создаёт ботов и управляет ими. Его также можно найти в «Настройки → Мои боты».
2. Отправьте команду /newbot.
3. Введите имя бота — его увидят пользователи, например «Погода».
4. Придумайте логин: латиница, 5–32 символа, в конце bot. Например, weather_bot.
5. Nemazing Father пришлёт токен вида 123:AbCdEf…. Он нужен для всех запросов к API.

Другие команды Nemazing Father

Аватар, имя и описание бота также можно поменять в приложении: «Настройки → Мои боты».

Как делать запросы

Все методы вызываются по адресу:

https://nemazing.org/bot<ТОКЕН>/<метод>

Название метода не зависит от регистра: sendMessage и sendmessage — одно и то же. Параметры можно передавать любым способом:

• в строке запроса — GET …/sendMessage?chat_id=5&text=Привет;
• в теле POST как JSON (Content-Type: application/json);
• как форму application/x-www-form-urlencoded;
• как multipart/form-data — так загружаются файлы.

Ответ всегда в формате JSON:

{ "ok": true, "result": { … } }

// при ошибке
{ "ok": false, "error_code": 400, "description": "Bad Request: chat not found" }

Быстрый старт

Проверьте токен — метод getMe вернёт информацию о боте:

curl "https://nemazing.org/bot<ТОКЕН>/getMe"

А теперь — бот-«эхо», который повторяет всё, что ему пишут:

// node echo.js  (Node.js 18+)
const API = 'https://nemazing.org/bot' + process.env.TOKEN;
let offset = 0;

async function call(method, params = {}) {
  const r = await fetch(`${API}/${method}`, {
    method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(params)
  });
  const j = await r.json();
  if (!j.ok) throw new Error(j.description);
  return j.result;
}

while (true) {
  const updates = await call('getUpdates', { offset, timeout: 30 });
  for (const u of updates) {
    offset = u.update_id + 1;
    const m = u.message;
    if (!m?.text) continue;
    if (m.text === '/start') await call('sendMessage', { chat_id: m.chat.id, text: 'Привет! Напиши что-нибудь 👋' });
    else await call('sendMessage', { chat_id: m.chat.id, text: m.text, reply_to_message_id: m.message_id });
  }
}

# pip install requests;  TOKEN=... python echo.py
import os, requests

API = "https://nemazing.org/bot" + os.environ["TOKEN"]

def call(method, **params):
    r = requests.post(f"{API}/{method}", json=params, timeout=60).json()
    if not r["ok"]:
        raise RuntimeError(r["description"])
    return r["result"]

offset = 0
while True:
    for u in call("getUpdates", offset=offset, timeout=30):
        offset = u["update_id"] + 1
        m = u.get("message") or {}
        if "text" not in m:
            continue
        if m["text"] == "/start":
            call("sendMessage", chat_id=m["chat"]["id"], text="Привет! Напиши что-нибудь 👋")
        else:
            call("sendMessage", chat_id=m["chat"]["id"], text=m["text"], reply_to_message_id=m["message_id"])

<?php // webhook.php — укажите его адрес в setWebhook
$token = getenv('TOKEN');
$u = json_decode(file_get_contents('php://input'), true);
$m = $u['message'] ?? null;
if ($m && isset($m['text'])) {
    $q = http_build_query(['chat_id' => $m['chat']['id'], 'text' => 'Вы написали: ' . $m['text']]);
    file_get_contents("https://nemazing.org/bot$token/sendMessage?$q");
}

Студия разработчика

Бота можно не размещать на своём сервере: в приложении откройте Настройки → Мои боты → бот → Студия разработчика. Это среда разработки прямо в Nemazing:

• Файловый менеджер — проект из любого числа файлов и папок: модули .js, .json, картинки, звуки, документы. Загрузка файлов и перетаскивание с компьютера, переименование, копирование, скачивание.
• Редактор кода — вкладки, подсветка синтаксиса, нумерация строк, автоотступы, Ctrl+S — сохранить, Ctrl+Enter — сохранить и перезапустить, Ctrl+/ — закомментировать.
• Встроенный хостинг — бот работает на сервере Nemazing круглосуточно, с автоперезапуском после сбоя, журналом, статистикой памяти и запросов.
• Терминал, переменные окружения для токенов и паролей, сайт бота и собственный HTTP API, импорт и экспорт проекта в ZIP, готовые шаблоны.

API скриптов

Код пишется на JavaScript. Главный файл (по умолчанию main.js) подключает остальные через require('./путь'). Объект bot доступен везде:

// main.js — главный файл проекта
const { money } = require('./lib/format');   // модули проекта
const catalog = require('./catalog.json');   // JSON сразу как объект

bot.command('start', (ctx) => ctx.reply('Привет, ' + ctx.from.first_name, {
  buttons: [[{ text: 'Каталог', data: 'catalog' }]]
}));
bot.on('callback', async (ctx) => {
  if (ctx.data === 'catalog') await ctx.edit(catalog.items.map((i) => i.title + ' — ' + money(i.price)).join('\n'));
});
bot.command('photo', (ctx) => ctx.replyPhoto('img/banner.jpg', 'Картинка из проекта'));

const n = await bot.storage.incr('starts');            // хранилище бота
await bot.fs.write('data/stats.json', { starts: n });    // файлы данных
const key = process.env.WEATHER_KEY;                     // секреты
bot.daily('09:00', () => bot.send(Number(process.env.CHANNEL_ID), 'Доброе утро!'));

Полная справка с примерами — в самой Студии (кнопка «Справка по API»).

Сайт и HTTP API бота

Файлы из папки public/ проекта публикуются по адресу /b/<логин_бота>/ — это может быть лендинг, мини-приложение или панель управления. Свои обработчики запросов добавляются через bot.http:

// public/index.html открывается по адресу https://nemazing.org/b/<логин_бота>/
bot.http.get('/items', async (req, res) => res.json(await bot.storage.get('items')));
bot.http.post('/order', async (req, res) => {
  await bot.send(Number(process.env.ADMIN_CHAT), 'Заказ: ' + req.body.name);
  res.json({ ok: true });
});
// → POST https://nemazing.org/b/<логин_бота>/api/order

Страницы ботов открываются в изолированной «песочнице» браузера: у них нет доступа к аккаунту и данным мессенджера.

Терминал

Безопасная оболочка для проекта: работает с файлами проекта, управляет ботом и выполняет код внутри него. Установка npm-пакетов недоступна — положите код библиотеки в проект файлом и подключите через require.

help                        все команды
ls · tree · cd · cat · grep · find · mv · cp · rm · mkdir · touch
start · stop · restart · status · logs 50
env TOKEN=abc               переменная окружения
kv ls · kv get ключ         хранилище бота
api getMe                   любой метод Bot API
js await bot.storage.all()  выполнить код внутри работающего бота
template shop               проект из шаблона: echo, shop, quiz, site

Обновления

Всё, что происходит с ботом — новое сообщение, нажатие на кнопку, оплата счёта, — приходит ему в виде обновления (Update). Получать обновления можно двумя способами — выберите один:

• getUpdates — бот сам спрашивает сервер о новых событиях. Проще всего начать: не нужен свой сервер с внешним адресом.
• Webhook — Nemazing сам отправляет каждое событие на ваш адрес. Удобно для сайтов и облачных функций.

Неполученные обновления хранятся 24 часа.

Объект Update

В каждом обновлении есть update_id и одно из полей:

{
  "update_id": 1052,
  "message": {
    "message_id": 881,
    "date": 1790851234,
    "chat": { "id": 42, "type": "private", "first_name": "Мария", "username": "maria" },
    "from": { "id": 3, "is_bot": false, "first_name": "Мария", "username": "maria" },
    "text": "/start",
    "entities": [{ "type": "bot_command", "offset": 0, "length": 6 }]
  }
}

Объект Message

User и Chat

User

Chat

Вместо числового chat_id публичного канала или группы можно передать его ссылку: @channel_name.

Клавиатуры

К любому отправляемому сообщению можно добавить параметр reply_markup — JSON-объект с кнопками.

Кнопки под сообщением

При нажатии на кнопку с callback_data бот получит обновление callback_query. Кнопка с url открывает ссылку. До 20 рядов, до 8 кнопок в ряду, текст — до 64 символов.

{
  "inline_keyboard": [
    [{ "text": "👍 Нравится", "callback_data": "like" }, { "text": "👎", "callback_data": "dislike" }],
    [{ "text": "Открыть сайт", "url": "https://example.com" }]
  ]
}

Другие кнопки

Оформление кнопок — цвет и анимация

Любой кнопке (и под сообщением, и в клавиатуре внизу) можно задать вид. Поля необязательные — без них кнопка обычная.

{ "inline_keyboard": [
  [{ "text": "Купить", "callback_data": "buy", "style": "success", "effect": "pulse", "icon": "🛒" }],
  [{ "text": "Промокод", "copy_text": { "text": "NEMAZING10" }, "color": "#ff2d92", "color2": "#7c3aff", "effect": "shine" }]
] }

Кнопки без действия или со ссылкой не на https://, tg://, nemazing://, mailto:, tel: не показываются. Пользователи с включённым «облегчённым режимом» или «уменьшением движения» видят кнопки без анимации.

Клавиатура вместо обычной

Кнопки с готовыми ответами внизу экрана. Нажатие отправляет текст кнопки обычным сообщением.

{ "keyboard": [["Погода", "Курс"], ["Помощь"]], "resize_keyboard": true, "one_time_keyboard": false }

// убрать клавиатуру
{ "remove_keyboard": true }

Информация о боте

Отправка сообщений

Все методы отправки возвращают отправленный Message и принимают общие параметры:

curl -X POST "https://nemazing.org/bot<ТОКЕН>/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{"chat_id": 42, "text": "Привет! 👋", "reply_markup": {"inline_keyboard": [[{"text": "Старт", "callback_data": "go"}]]}}'

Медиа и файлы

Файл можно передать тремя способами:

• загрузить в запросе multipart/form-data — имя поля совпадает с названием параметра (photo, video…);
• указать file_id файла, который уже есть в Nemazing;
• указать ссылку на файл.

Подпись передаётся в параметре caption. Размеры фото Nemazing определяет сам — картинка показывается в чате целиком, с правильными пропорциями. Ссылку на файл сервер скачивает к себе (до 20 МБ), поэтому фото не пропадёт, даже если исходный сайт удалит его. has_spoiler: true скрывает фото и видео под спойлер.

curl -X POST "https://nemazing.org/bot<ТОКЕН>/sendMediaGroup" \
  -F chat_id=42 -F media='[{"type":"photo","media":"attach://a","caption":"Отпуск"},{"type":"photo","media":"attach://b"}]' \
  -F a=@1.jpg -F b=@2.jpg

curl -X POST "https://nemazing.org/bot<ТОКЕН>/sendPhoto" \
  -F chat_id=42 -F caption="Закат 🌅" -F photo=@sunset.jpg

Изменение и удаление

Чаты

// приветствие новичка с кнопкой
if (update.message?.new_chat_members) {
  const u = update.message.new_chat_members[0];
  await api('sendMessage', { chat_id: update.message.chat.id, text: `Привет, ${u.first_name}! 👋`, parse_mode: 'HTML',
    reply_markup: { inline_keyboard: [[{ text: 'Правила', url: 'https://example.com', style: 'primary', effect: 'pulse' }]] } });
}

Добавить бота: откройте его профиль → «В группу» или «В канал», либо «Управление» сообщества → «Боты». В группу бота можно добавить участником или администратором (для модерации и приветствий). В канал бот добавляется администратором — тогда он публикует записи (с кнопками), изменяет и удаляет их и получает channel_post.

Мини-приложения и кнопка «Меню»

Мини-приложение — ваш сайт, который открывается внутри Nemazing поверх чата. Сайт сразу знает, кто его открыл (без логина), и может принимать оплату рублями. Работает как Telegram Mini Apps: подключите наш скрипт — и код, написанный для Telegram, заработает без изменений.

<script src="https://nemazing.org/js/web-app.js"></script>
// дальше — как в Telegram
const app = Telegram.WebApp;   // или Nemazing.WebApp
app.ready(); app.expand();
app.initDataUnsafe.user          // { id, first_name, username, … }
app.MainButton.setText('Купить').show().onClick(() => …);
app.openInvoice(link, (status) => { /* 'paid' | 'cancelled' | 'failed' */ });

Как открыть приложение

• кнопка под сообщением: { "text": "Открыть", "web_app": { "url": "https://…" } };
• кнопка клавиатуры внизу с web_app — тогда приложение может вызвать Telegram.WebApp.sendData(…), и бот получит message.web_app_data;
• кнопка «Меню» у поля ввода — метод setChatMenuButton (или «Мои боты» → «Мини-приложение и кнопка Меню»);
• кнопка «Открыть» в профиле бота — появляется, если задана кнопка меню.

Трансляция геопозиции

Игры

HTML5-игра открывается в мессенджере на весь экран. Создайте её методом setMyGame, отправьте sendGame — у сообщения будут кнопки «Играть» и «Рекорды». При нажатии «Играть» бот получает callback_query с полем game_short_name (как в Telegram) и может ответить answerCallbackQuery с url; если у игры задан url, она откроется сразу. К ссылке добавляется #nmz_ticket=…&user_id=…&chat_id=…&message_id=…: игра передаёт эти данные вашему серверу, а он записывает результат.

Inline-режим

Включите inline-режим в «Мои боты» → бот → «Inline-режим». Пользователь пишет @ваш_бот запрос в любом чате — бот получает обновление inline_query { id, from, query, offset, chat_type } и в течение 8 секунд отвечает методом answerInlineQuery. Выбранный результат отправляется от имени пользователя с пометкой «через @бот», бот получает chosen_inline_result.

// в Студии разработчика
bot.on('inline', (q) => q.answer([
  { type: 'article', id: '1', title: 'Эхо: ' + q.query, input_message_content: { message_text: q.query } }
], { cache_time: 0 }));

Нажатия на кнопки

Когда пользователь нажимает кнопку с callback_data, бот получает callback_query:

Платежи в рублях

Боты могут продавать товары и услуги за рубли с баланса пользователя в Nemazing. Пользователь оплачивает счёт одной кнопкой, деньги поступают на кошелёк владельца бота, откуда их можно вывести на карту. Код валюты в API — PHM.

Подтверждение оплаты

После оплаты бот получит обновление message с полем successful_payment:

"successful_payment": {
  "currency": "PHM",
  "total_amount": 150,
  "invoice_payload": "order-1024",
  "invoice_id": 77,
  "charge_id": "3191"
}

Ошибки

Ограничения

• Текст сообщения — до 8000 символов.
• Размер файла — до 200 МБ.
• До 20 ботов на один аккаунт.
• Неполученные обновления хранятся 24 часа.
• Webhook должен ответить за 10 секунд.
• Не отправляйте одному пользователю больше 1 сообщения в секунду, а в группу — больше 20 в минуту.

Правила для ботов

• Бот пишет пользователю, только если тот сам начал с ним чат.
• Запрещены спам, реклама без согласия, мошенничество и сбор чужих данных.
• При оплате бот обязан выполнить обещанное или вернуть деньги через refundPayment.
• За нарушения бот и аккаунт владельца могут быть заблокированы.