Bots

Bots

Build bots for Min with a Telegram-compatible Bot API: create a bot, get a token, receive updates by webhook or long polling, send messages with inline keyboards.

Min bots speak a subset of the Telegram Bot API: the same URL shape (/bot<token>/<method>), the same {"ok":true,"result":…} envelope and the same object shapes (Message, User, Chat, Update, CallbackQuery, InlineKeyboardMarkup). Many Telegram libraries work after changing the base URL. Everything not listed in the method reference is not implemented and returns 404.

1. Create a bot#

Any user can own up to 20 bots. Bot usernames must end with bot (e.g. weather_bot). Two ways:

• @BotFather — open a chat with @botfather in Min and send /newbot Weather Bot | weather_bot. Other commands: /mybots, /token <username> (new token), /revoke <username> (delete).
• API — POST /api/bots with your user token (see Bot management).

curl -X POST https://minchatapp.com/api/bots \
  -H "Authorization: Bearer $USER_TOKEN" -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Weather Bot","username":"weather_bot"}'
# → {"success":true,"bot":{"id":5,"username":"weather_bot",…},"token":"5:RyNKXZs7Va1LvKqSLj6Snsoy2FplGb1n8FV"}

2. Call the Bot API#

Methods accept GET or POST with parameters in the query string, application/x-www-form-urlencoded, multipart/form-data (files) or JSON. Nested objects (reply_markup, commands) may be JSON strings.

https://minchatapp.com/bot<token>/<method>
https://minchatapp.com/bot/<token>/<method>        (alternative form)
https://minchatapp.com/file/bot<token>/<file_path> (file download)

{"ok": true, "result": { … }}
{"ok": false, "error_code": 400, "description": "Bad Request: chat not found"}

error_code is the HTTP status: 400 bad request, 401 bad token, 404 unknown method, 409 getUpdates while a webhook is set, 429 rate limit, 500 server error.

Chats and ids#

message_id is the global Min message id. file_id values are bot-scoped.

3. Receive updates#

An update is created for every bot member of a chat when someone else sends (message) or edits (edited_message) a message, and when a user presses an inline button (callback_query). Privacy mode: in groups a bot only receives commands (/start, /weather@weather_bot) unless can_read_all_group_messages is enabled for it. In private chats and channels it receives everything.

Long polling#

Call getUpdates in a loop with timeout (up to 50 s) and offset = last update_id + 1 — this confirms and deletes the earlier updates.

import requests

TOKEN = "5:RyNKXZs7Va1LvKqSLj6Snsoy2FplGb1n8FV"
API = f"https://minchatapp.com/bot{TOKEN}"
offset = 0

while True:
    r = requests.get(f"{API}/getUpdates", params={"offset": offset, "timeout": 30}, timeout=40).json()
    for upd in r["result"]:
        offset = upd["update_id"] + 1
        if "message" in upd:
            msg = upd["message"]
            if msg.get("text", "").startswith("/weather"):
                requests.post(f"{API}/sendMessage", json={
                    "chat_id": msg["chat"]["id"],
                    "text": "Pick a city:",
                    "reply_markup": {"inline_keyboard": [[
                        {"text": "Moscow", "callback_data": "city:moscow"},
                        {"text": "Berlin", "callback_data": "city:berlin"},
                    ]]},
                })
        elif "callback_query" in upd:
            cq = upd["callback_query"]
            requests.post(f"{API}/answerCallbackQuery", json={"callback_query_id": cq["id"], "text": "Loading…"})
            requests.post(f"{API}/editMessageText", json={
                "chat_id": cq["message"]["chat"]["id"],
                "message_id": cq["message"]["message_id"],
                "text": f"Weather for {cq['data'].split(':')[1]}: +5°C",
            })

const TOKEN = process.env.MIN_BOT_TOKEN;
const API = `https://minchatapp.com/bot${TOKEN}`;
const call = (method, body) =>
  fetch(`${API}/${method}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(body ?? {}),
  }).then((r) => r.json());

let offset = 0;
for (;;) {
  const { result } = await call('getUpdates', { offset, timeout: 30 });
  for (const upd of result) {
    offset = upd.update_id + 1;
    const msg = upd.message;
    if (msg?.text === '/start') {
      await call('sendMessage', { chat_id: msg.chat.id, text: `Hi, ${msg.from.first_name}!` });
    }
  }
}

curl "https://minchatapp.com/bot$BOT_TOKEN/getUpdates?timeout=30&offset=0"

Webhook#

setWebhook with an HTTPS URL switches the bot to push delivery: each update is POSTed as JSON. Answer 2xx quickly; failures are retried 3 times, 30 s apart, and reported by getWebhookInfo. Verify the X-Telegram-Bot-Api-Secret-Token header if you set secret_token. While a webhook is set getUpdates returns 409.

curl -X POST "https://minchatapp.com/bot$BOT_TOKEN/setWebhook" \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com/minchat-webhook","secret_token":"s3cr3t-value"}' 

import express from 'express';
const app = express();
app.use(express.json());

app.post('/minchat-webhook', async (req, res) => {
  if (req.get('X-Telegram-Bot-Api-Secret-Token') !== process.env.WEBHOOK_SECRET) return res.sendStatus(403);
  res.sendStatus(200); // acknowledge first
  const msg = req.body.message;
  if (msg?.text) {
    await fetch(`https://minchatapp.com/bot${process.env.MIN_BOT_TOKEN}/sendMessage`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ chat_id: msg.chat.id, text: `You said: ${msg.text}` }),
    });
  }
});
app.listen(3000);

from flask import Flask, request, abort
import os, requests

app = Flask(__name__)
API = f"https://minchatapp.com/bot{os.environ['MIN_BOT_TOKEN']}"

@app.post("/minchat-webhook")
def hook():
    if request.headers.get("X-Telegram-Bot-Api-Secret-Token") != os.environ["WEBHOOK_SECRET"]:
        abort(403)
    upd = request.get_json()
    msg = upd.get("message")
    if msg and msg.get("text"):
        requests.post(f"{API}/sendMessage", json={"chat_id": msg["chat"]["id"], "text": "Got it!"})
    return "ok"

Example webhook body (message update):

{
  "update_id": 1,
  "message": {
    "message_id": 51,
    "date": 1792660008,
    "chat": {
      "id": 1,
      "type": "private",
      "first_name": "Anna",
      "username": "anna_s"
    },
    "from": {
      "id": 1,
      "is_bot": false,
      "first_name": "Anna",
      "last_name": "Smith",
      "username": "anna_s"
    },
    "text": "/weather Moscow"
  }
}

4. Inline keyboards and callbacks#

Attach reply_markup with inline_keyboard — rows of buttons. Each button has text (≤ 64 chars) and either callback_data (≤ 64 bytes) or url. Clients render the keyboard under the message; URL buttons open externally. A press sends a callback_query update; answer it with answerCallbackQuery and usually update the message with editMessageText / editMessageReplyMarkup (an empty inline_keyboard removes the keyboard). Edits are delivered to clients live (MessageUpdated).

{
  "chat_id": 1,
  "text": "Pick a city:",
  "reply_markup": {
    "inline_keyboard": [
      [ {"text": "Moscow", "callback_data": "city:moscow"}, {"text": "Berlin", "callback_data": "city:berlin"} ],
      [ {"text": "Open website", "url": "https://minchatapp.com"} ]
    ]
  }
}

callback_query update:

{
  "update_id": 3,
  "callback_query": {
    "id": "1",
    "from": {
      "id": 1,
      "is_bot": false,
      "first_name": "Anna",
      "last_name": "Smith",
      "username": "anna_s"
    },
    "chat_instance": "8",
    "data": "city:moscow",
    "message": {
      "message_id": 50,
      "date": 1792660008,
      "chat": {
        "id": 1,
        "type": "private",
        "first_name": "Anna",
        "username": "anna_s"
      },
      "from": {
        "id": 5,
        "is_bot": true,
        "first_name": "Weather",
        "last_name": "Bot",
        "username": "weather_bot",
        "can_join_groups": true,
        "can_read_all_group_messages": false,
        "supports_inline_queries": false
      },
      "text": "Pick a city:",
      "reply_markup": {
        "inline_keyboard": [
          [
            {
              "text": "Moscow",
              "callback_data": "city:moscow"
            },
            {
              "text": "Berlin",
              "callback_data": "city:berlin"
            }
          ],
          [
            {
              "text": "Open website",
              "url": "https://minchatapp.com"
            }
          ]
        ]
      }
    }
  }
}

5. Commands#

Register commands with setMyCommands; messages starting with / are delivered to bots in groups even in privacy mode. /cmd@your_bot addresses a specific bot.

curl -X POST "https://minchatapp.com/bot$BOT_TOKEN/setMyCommands" \
  -H 'Content-Type: application/json' \
  -d '{"commands":[{"command":"start","description":"Start the bot"},{"command":"weather","description":"Current weather"}]}' 

6. Files#

Send media by multipart upload, by URL (the server downloads up to 50 MB) or by a file_id you received earlier. To download a file, call getFile and fetch /file/bot<token>/<file_path>.

curl -F chat_id=1 -F caption='Forecast map' -F photo=@map.png \
  "https://minchatapp.com/bot$BOT_TOKEN/sendPhoto"

Limits#

Bot management (user API)#

These endpoints use the owner's Sanctum token, not the bot token.

curl 'https://minchatapp.com/api/bots' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Accept: application/json'

{
  "success": true,
  "bots": [
    {
      "id": 5,
      "name": "Weather Bot",
      "username": "weather_bot",
      "avatar": null,
      "created_at": "2026-10-22T09:06:14+00:00"
    }
  ]
}

curl -X POST 'https://minchatapp.com/api/bots' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"name": "Weather Bot", "username": "weather_bot"}'

{
  "success": true,
  "bot": {
    "id": 5,
    "name": "Weather Bot",
    "username": "weather_bot",
    "avatar": null
  },
  "token": "5:AAEhBP0av28Jc9RIwmZ8P-exampleToken"
}

curl -X POST 'https://minchatapp.com/api/bots/5/token' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Accept: application/json'

{
  "success": true,
  "token": "5:AAEhBP0av28Jc9RIwmZ8P-exampleToken"
}

curl -X DELETE 'https://minchatapp.com/api/bots/5' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Accept: application/json'

Related: GET /api/username-available?kind=bot checks a bot username; POST /api/messages/{id}/callback is what clients call when a user presses a button.