The miniapps.me API
Tell us what your users do and see their numbers, or ask whether someone upvoted you and reward them in your bot or mini app.
Free, with no plan or billing. 20 requests a second. Stats for your app are free too, and a bot that runs its own code can add its users to the panel.
curl -G https://miniapps.me/api/v1/upvoted \
-d app=yourbot \
-d user=123456789 \
-H "Authorization: Bearer ma_live_your_key_here"{
"user": 123456789,
"upvoted": true,
"since": "2026-05-25",
"app": "yourbot",
"icon": "https://miniapps.me/apps/logos/yourbot.jpg",
"votes": 84
}How is your app built?
Pick one. Your panel then walks you through it, in at most three steps, with your own bot's details already in the code.
Bot with its own code
Create a key, then send us what people do from your code.
Bot run by the panel
It has no code of its own, so there's nothing to install.
How it fits your app
The call to our API is the same either way. What changes is where you get the user's id, and where your key is kept. Pick what you are building.
Telegram bot
- UserChats with your bot
- sends /profeature unlocked
- Your botOn your server. The key stays here.
- user id + key"upvoted": true
- miniapps.meKnows who upvoted
-
Get the user's id from the update
Every message Telegram sends your bot says who sent it. In the raw update that is
message.from.id. It comes straight from Telegram, so you can trust it.bot.py, with aiogramuser_id = message.from_user.id # 123456789bot.js, with grammYconst userId = ctx.from.id; // 123456789 -
Ask miniapps.me
Send that id and your app's identifier, with your key in the
Authorizationheader. Keep the key in an environment variable, not in your code.bot.pyimport os, aiohttp async def check_upvote(user_id): async with aiohttp.ClientSession() as session: async with session.get( "https://miniapps.me/api/v1/upvoted", params={"app": "yourbot", "user": user_id}, headers={"Authorization": f"Bearer {os.environ['MINIAPPS_KEY']}"}, ) as res: res.raise_for_status() return await res.json()bot.jsasync function checkUpvote(userId) { const res = await fetch( `https://miniapps.me/api/v1/upvoted?app=yourbot&user=${userId}`, { headers: { Authorization: `Bearer ${process.env.MINIAPPS_KEY}` } } ); if (!res.ok) throw new Error(`miniapps.me said ${res.status}`); return res.json(); } -
Reply, or unlock something
If
upvotedis true, give them the feature. If it is false, the reply includes avote_url. Send it as a button with their id on the end,?r=123456789.bot.pyfrom aiogram import F, Router from aiogram.filters import Command, CommandStart from aiogram.types import InlineKeyboardButton, InlineKeyboardMarkup, Message router = Router() @router.message(Command("pro")) async def pro(message: Message): user_id = message.from_user.id data = await check_upvote(user_id) if data["upvoted"]: await message.answer("Pro filters are on. Thanks for the upvote!") return button = InlineKeyboardButton( text="Upvote on miniapps.me", url=f"{data['vote_url']}?r={user_id}", ) await message.answer( "Upvote us once to unlock pro filters.", reply_markup=InlineKeyboardMarkup(inline_keyboard=[[button]]), )bot.jsimport { Bot, InlineKeyboard } from "grammy"; const bot = new Bot(process.env.BOT_TOKEN); async function pro(ctx) { const data = await checkUpvote(ctx.from.id); if (data.upvoted) { await ctx.reply("Pro filters are on. Thanks for the upvote!"); return; } await ctx.reply("Upvote us once to unlock pro filters.", { reply_markup: new InlineKeyboard().url( "Upvote on miniapps.me", `${data.vote_url}?r=${ctx.from.id}` ), }); } bot.command("pro", pro); -
Welcome them back
They tap the button, upvote, and Telegram brings them back to your chat as
/start v_123456789. Run the same check again. Use the id from the update rather than the one in the link, because anyone can type a link.bot.py# Put this line straight above "async def pro" in step 3, # and register the router before your normal /start handler. @router.message(CommandStart(deep_link=True, magic=F.args.startswith("v_")))bot.js// Merge this into your /start handler if you have one. bot.command("start", async (ctx) => { if (ctx.match.startsWith("v_")) await pro(ctx); }); bot.start();
Count your users too
While you are in that handler, tell us who used the bot. You get a free dashboard with users, active users, commands and languages. We can't check what your server sends, so these numbers are labelled as reported. How stats work, including how a bot with no code of its own gets verified numbers.
AUTH = {"Authorization": f"Bearer {os.environ['MINIAPPS_KEY']}"}
async def report(user_id, command):
event = {"app": "yourbot", "user": user_id,
"event": "command", "name": command}
async with aiohttp.ClientSession() as session:
await session.post("https://miniapps.me/api/v1/events",
json=event, headers=AUTH)
await report(message.from_user.id, "/pro")async function report(userId, command) {
await fetch("https://miniapps.me/api/v1/events", {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${process.env.MINIAPPS_KEY}`,
},
body: JSON.stringify({
app: "yourbot", user: userId,
event: "command", name: command,
}),
});
}
await report(ctx.from.id, "/pro");Mini app
- UserOpens your mini app
- taps a buttonfeature unlocked
- Your mini appOn their phone. No key here.
- initData"upvoted": true
- Your serverChecks initData. The key stays here.
- user id + key"upvoted": true
- miniapps.meKnows who upvoted
Never put your API key in mini app code. A mini app is a web page on the user's phone, so anyone can open it and read the key. The mini app talks to your server, and only your server talks to us.
-
Send initData to your server
Your mini app can read the user's id from
Telegram.WebApp.initDataUnsafe.user.id. That is fine for showing a name, but anyone can fake it, so do not unlock anything with it. SendTelegram.WebApp.initDatainstead. It holds the same details, signed by Telegram.In your mini app<script src="https://telegram.org/js/telegram-web-app.js"></script> <script> const tg = window.Telegram.WebApp; tg.ready(); // No API key anywhere in this file. async function checkUpvote() { const res = await fetch("/check-upvote", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ initData: tg.initData }), }); return res.json(); } </script> -
Check that Telegram really signed it
Only Telegram and you know your bot token, so only Telegram could have made a hash that matches. Use the token of the bot your mini app belongs to. Refuse anything that fails, or that is more than a day old.
The recipe: remove
hash, sort the other fields by name, and join them askey=valuelines. That is the data check string. The secret is HMAC_SHA256 of your bot token, usingWebAppDataas the key. The hash is the hex HMAC_SHA256 of the data check string, using that secret as the key.server.pyimport hashlib, hmac, json, os, time from urllib.parse import parse_qsl def verify_init_data(init_data): """Returns the Telegram user, or None if the data is fake or old.""" fields = dict(parse_qsl(init_data, keep_blank_values=True)) received = fields.pop("hash", "") check_string = "\n".join(f"{k}={fields[k]}" for k in sorted(fields)) secret = hmac.new( b"WebAppData", os.environ["BOT_TOKEN"].encode(), hashlib.sha256 ).digest() expected = hmac.new( secret, check_string.encode(), hashlib.sha256 ).hexdigest() if not hmac.compare_digest(expected, received): return None if time.time() - int(fields.get("auth_date", 0)) > 86400: return None return json.loads(fields["user"])server.jsimport crypto from "node:crypto"; // Returns the Telegram user, or null if the data is fake or old. function verifyInitData(initData) { const params = new URLSearchParams(initData); const received = params.get("hash") ?? ""; params.delete("hash"); params.sort(); const checkString = [...params].map(([k, v]) => `${k}=${v}`).join("\n"); const secret = crypto .createHmac("sha256", "WebAppData") .update(process.env.BOT_TOKEN) .digest(); const expected = crypto .createHmac("sha256", secret) .update(checkString) .digest("hex"); if (expected.length !== received.length) return null; if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received))) return null; if (Date.now() / 1000 - Number(params.get("auth_date")) > 86400) return null; return JSON.parse(params.get("user")); } -
Ask miniapps.me from your server
Now you have an id you can trust. Call our API with your key, and pass back only what the mini app needs. If your server is on a different domain from your mini app, allow your mini app's domain with CORS.
server.py, with FastAPIimport httpx from fastapi import Body, FastAPI, HTTPException app = FastAPI() @app.post("/check-upvote") async def check_upvote(body: dict = Body(...)): user = verify_init_data(body.get("initData", "")) if user is None: raise HTTPException(401, "Could not verify initData") async with httpx.AsyncClient() as client: res = await client.get( "https://miniapps.me/api/v1/upvoted", params={"app": "yourbot", "user": user["id"]}, headers={"Authorization": f"Bearer {os.environ['MINIAPPS_KEY']}"}, ) res.raise_for_status() data = res.json() return { "upvoted": data["upvoted"], "votes": data["votes"], "vote_url": data.get("vote_url"), }server.js, with Expressimport express from "express"; const app = express(); app.post("/check-upvote", express.json(), async (req, res) => { const user = verifyInitData(req.body.initData ?? ""); if (!user) return res.status(401).json({ error: "bad_init_data" }); const api = await fetch( `https://miniapps.me/api/v1/upvoted?app=yourbot&user=${user.id}`, { headers: { Authorization: `Bearer ${process.env.MINIAPPS_KEY}` } } ); if (!api.ok) return res.status(502).json({ error: "api_failed" }); const { upvoted, votes, vote_url } = await api.json(); res.json({ upvoted, votes, vote_url }); }); app.listen(3000); -
Act on the answer in the mini app
If
upvotedis true, unlock the feature. If not, openvote_urlfrom a button. After upvoting they land in your bot's chat. When they come back to the mini app, the same check runs again.In your mini appasync function refresh() { const data = await checkUpvote(); if (data.upvoted) { unlockProFilters(); // your own code } else { upvoteButton.hidden = false; upvoteButton.onclick = () => tg.openLink(data.vote_url); } } refresh(); tg.onEvent("activated", refresh); // runs again when they return
Count your users too
Add one line to your page and we count each launch. No key, no server and no cookies. Telegram signs the launch data and we check the signature, so the numbers are verified and can show on your public page. How stats work.
<script src="https://miniapps.me/stats.js" data-app="yourbot"></script>What to do with the answer
Pro filters are on. Thanks for the upvote!
Unlock a feature
Open a feature, a bonus or a role when upvoted is true. People who already upvoted never see the prompt.
Tick off a task
If your app has quests or daily tasks, make this one of them. Your code checks upvoted, so nobody has to send you a screenshot.
Welcome back. We have 84 upvotes on miniapps.me.
Show your score
Put votes in a welcome message or a stats screen. Use /api/v1/apps if you only need the count.
Get started in three steps
If your app is already listed and verified, you can make your first call in about a minute.
-
List your app
Add your app. Once it is live, open it from your profile and paste your bot token to verify it, which proves it is yours. A mini app uses the token of the bot it belongs to.
Your app's identifier is the last part of its miniapps.me address. For miniapps.me/yourbot, it is
yourbot.Your apps
Sign in and your bots appear here with their live upvote counts, which is exactly what the API returns.
-
Create a key
Give it a name so you remember what it is for, and tick only what it needs. We show the full key once, so copy it straight away and keep it somewhere private.
One key works for all your verified apps. If one ever leaks, revoke it and it stops working immediately. To change what a key can do, make a new one and revoke the old one.
-
Make your first call
Paste this into a terminal with your key in place of the example. Use your own Telegram id for the test.
If you see JSON with
upvotedin it, you are done. If you seeerror, the error table says what to change.Terminalcurl -G https://miniapps.me/api/v1/upvoted \ -d app=yourbot \ -d user=123456789 \ -H "Authorization: Bearer ma_live_your_key_here"
Reference
Two endpoints for reading, both GET, both answering in JSON. The address is https://miniapps.me. The two that write are under Stats and Add users.
Your key
Send it in the Authorization header on every call. That is the only place we accept it, so it never ends up in a web address or an access log.
Authorization: Bearer ma_live_your_key_here| Permission | What it opens |
|---|---|
| Read | GET /api/v1/upvoted and GET /api/v1/apps |
| Send stats | POST /api/v1/events |
| Add users | POST /api/v1/panel/users |
You choose these when you make the key, and they cannot be changed afterwards. A key that writes does not read unless you tick Read as well. Calling something the key has no permission for gets a 403 with the error missing_permission.
GET/api/v1/upvoted
Whether a Telegram user has upvoted your app, plus your current count.
| Parameter | What it is |
|---|---|
app | Required. Your app's identifier, the last part of its miniapps.me address. |
user | Required. A Telegram user id. To check several, separate up to 100 with commas. |
| Field | What it is |
|---|---|
upvoted | true or false. It goes back to false if they remove their upvote. |
since | The date they upvoted, in UTC, or null. |
votes | Your app's total upvotes. |
icon | Your logo as a full address, or null if the listing has none. |
vote_url | Your upvote link. With one id, only there when upvoted is false. With several ids, always there. |
results | Only with several ids: user, upvoted and since for each one. |
{
"user": 123456789,
"upvoted": true,
"since": "2026-05-25",
"app": "yourbot",
"icon": "https://miniapps.me/apps/logos/yourbot.jpg",
"votes": 84
}{
"user": 123456789,
"upvoted": false,
"since": null,
"app": "yourbot",
"icon": "https://miniapps.me/apps/logos/yourbot.jpg",
"votes": 84,
"vote_url": "https://miniapps.me/v/yourbot"
}{
"app": "yourbot",
"icon": "https://miniapps.me/apps/logos/yourbot.jpg",
"votes": 84,
"vote_url": "https://miniapps.me/v/yourbot",
"results": [
{ "user": 123456789, "upvoted": true, "since": "2026-05-25" },
{ "user": 987654321, "upvoted": false, "since": null }
]
}GET/api/v1/apps
Your verified apps and their current upvote counts. It takes no parameters. The list is empty if you have no verified listing yet.
icon is a full address you can use in your own messages, and is null if the listing has no logo.
{
"apps": [
{
"app": "yourbot",
"name": "Your Bot",
"icon": "https://miniapps.me/apps/logos/yourbot.jpg",
"url": "https://miniapps.me/yourbot",
"votes": 84
}
]
}The upvote link
This is the vote_url from above. Add ?r= and a value, usually the user's id, using up to 48 letters, numbers, dashes or underscores.
It signs them in if needed and adds their upvote. Opening it twice never removes it. They then go back to your bot with v_ and your value as the start parameter. If your listing has no t.me link, they land on your listing page instead.
https://miniapps.me/v/yourbot?r=123456789https://t.me/yourbot?start=v_123456789If something goes wrong
Every failure has a status code, plus JSON with an error code and a message written for a person.
{
"error": "bad_key",
"message": "That key is not valid, or it was revoked."
}| Status | Error | What it means |
|---|---|---|
400 | no_app | You left out app. |
400 | no_user | You left out user. |
400 | bad_user | user has something in it that is not a number. |
400 | too_many | More than 100 ids in one request. |
401 | no_key | The Authorization header is missing. |
401 | bad_key | The key is wrong, or it was revoked. |
403 | missing_permission | This key was not given the permission that call needs. The reply names it as needs. Make a new key with it. |
403 | not_yours | That app is not one of your verified listings. The reply lists the ones that are, as your_apps. |
429 | rate_limited | Over 20 requests a second on this key. Wait a moment and retry. |
Limits
The per-second cap is there to stop a broken retry loop, not to meter you. Go over and you get a 429, then you are fine again a second later.
Stats
See how many people use your app, and how often they come back. It's free, and there are three ways to turn it on. Which one fits depends on where your code runs.
A free dashboard
Total users, active users, new users, how many come back, your top commands, languages and where people came from.
Numbers on your public page
Your miniapps.me page shows your total, this month and today, labelled by where they came from. Verified numbers show unless you hide them.
A place in Most active
Most active ranks apps by verified users in the last 30 days. You appear once we have counted 50 users.
A bot connected to the panel Verified
For a bot with no code of its own. Telegram sends the bot's updates straight to us, so there is nothing to add, and the numbers don't depend on anything you tell us.
We read who sent each update, their language, the command word and the start payload. Message text is never stored.
Telegram sends a bot's updates to one place only, so any other code running this bot stops receiving them. If your bot has its own code, use the third way.
- Open Add your app, paste its token and tick Manage it in the panel.
- In the bot's Settings, choose to let the panel run it. Nothing changes until you do.
- Counting starts with the next update. To show the numbers publicly, verify your listing with this same bot's token.
The mini app script Verified
One line in your page. Each time someone opens your mini app, the script sends us the launch data Telegram signed. We check Telegram's signature and take the user from that, never from your page, so it can't be faked by calling us with made-up ids.
It sets no cookies and stores nothing on the phone.
Your page must be verified with the token of the bot this mini app belongs to, because that is how we know which bot's launches to accept. If the same bot is also connected to the panel, one person using both counts once.
<script src="https://miniapps.me/stats.js" data-app="yourbot"></script>data-app is the last part of your miniapps.me address. No listing yet? Connect the bot in the panel and use bot- and its Telegram id: the API page in the panel has the exact line.
POST/api/v1/events Reported
For a bot that runs its own code. Your server tells us what happened, using a key with the Send stats permission, and only for listings you own and have verified. No listing yet? Pass "bot" with your bot's number in the panel instead of "app".
We can't check what a server tells us. Your dashboard shows these numbers from the first event. They stay off your public page until you choose to show them, where they read "Reported by owner, not checked". They never count for Most active.
curl https://miniapps.me/api/v1/events \
-H "Authorization: Bearer ma_live_your_key_here" \
-H "Content-Type: application/json" \
-d '{"app": "yourbot", "user": 123456789,
"event": "command", "name": "/start",
"language": "en", "source": "channel_post"}'{
"ok": true,
"accepted": 1,
"label": "reported"
}{
"app": "yourbot",
"events": [
{"user": 123456789, "event": "command", "name": "/start"},
{"user": 987654321, "event": "message"}
]
}| Field | What it is |
|---|---|
app | The last part of your miniapps.me address. You can leave it out if your key has only one listing. |
user | Required. The Telegram user id. We turn it into a hash before storing anything. |
event | command, message, callback, open or event. If you leave it out, it is event. |
name | Required for command and event. Up to 64 characters, and up to 100 different names of each kind per app. Never put message text or anything personal here. |
language | Optional. The user's language code from Telegram, such as en. |
source | Optional. Where they came from, such as your start payload. It only counts on the first event we see from a person. Letters, digits, _ and -, up to 64. |
| Status | Error | What it means |
|---|---|---|
400 | bad_event | One event is wrong, and nothing was saved. message says what, and index says which. |
400 | no_app | You left out app and your key has more than one listing, or none. |
400 | no_events | events is empty, or is not a list. |
400 | too_many | More than 100 events in one request. |
400 | bad_json | The body is not a JSON object. |
403 | not_yours | That app is not one of your verified listings. The reply lists the ones that are. |
413 | too_large | The request is over 64 KB. |
422 | too_many_names | This app already has 100 different names of that kind. |
Keys and limits work as in the rest of the API, so a bad key gets a 401, a key without Send stats gets a 403, and going over 20 requests a second gets a 429. If you turned counting off for this app, you still get a 202, with accepted at 0. An event is dated when it reaches us, so send them as they happen.
What the numbers mean
Total users is everyone we have seen since you turned stats on, so it starts at zero. Active this month is people seen in the last 30 days, and active today is people seen since midnight UTC. Public numbers refresh about every five minutes.
They are separate from the monthly users figure on your page, which comes from Telegram.
What you owe your users
We store a hash of each user id, never the id, and you never see who is who. You still need to tell your users that you count usage, usually in your own privacy policy. What we collect and for how long.
Add your bot's users
If your bot runs its own code, it keeps its own webhook and we never see who starts it. Your code can tell us instead, so those people are there when you send a broadcast from the bot panel.
POST/api/v1/panel/users
Needs a key with the Add users permission, made by the account that connected the bot.
People you add show as not checked yet, the same as a file upload, until a send or a health check confirms them. Sending someone again never changes their status, so a nightly send of your whole list cannot undo a block we found. Repeating a request changes nothing, so a retry after a timeout is safe.
Anyone on your do not contact list stays on it and is never messaged. excluded tells you how many of the ids you sent are on it.
curl https://miniapps.me/api/v1/panel/users \
-H "Authorization: Bearer ma_live_your_key_here" \
-H "Content-Type: application/json" \
-d '{"bot": 42,
"users": [{"id": 123456789, "language": "en",
"source": "ad-november"},
987654321],
"blocked": [555555555]}'{
"ok": true,
"bot": 42,
"received": 3,
"added": 2,
"updated": 0,
"unchanged": 1,
"rejected": 0,
"errors": [],
"excluded": 0,
"audience": {"used": 3937, "limit": 20000}
}| Field | What it is |
|---|---|
bot | Required. The bot's number, shown on its settings page in the panel. |
users | People to add or update. Each one is a Telegram user id, or an object with id and, if you have them, language and source. Someone listed twice counts once. |
blocked | Ids of people who blocked the bot. Your code hears about that from Telegram in a my_chat_member update. An id we do not hold is not stored. Someone in both lists counts as blocked. |
language | A language code such as en or pt-br, up to 12 characters. |
source | Where they came from, up to 32 characters: letters, digits, _, . and -. started, imported and unknown_sender are ours and get rejected. |
| In the answer | What it means |
|---|---|
received | How many entries we could count, after dropping repeats. |
added, updated, unchanged | What happened to the entries we could use. Marking someone blocked counts as updated. |
rejected, errors | Entries we could not use, and up to 20 of them with a reason: bad_id, bad_language, bad_source or reserved_source. A bad entry does not stop the good ones, so this can happen with a 200. |
audience | How many people your account holds across all its bots, and its limit. limit is null if there is none. |
| Status | Error | What it means |
|---|---|---|
400 | bad_json | The body is not a JSON object. |
400 | bad_bot | bot is missing, or is not a positive whole number. |
400 | bad_batch | users or blocked is not a list. |
400 | empty_batch | Both lists are empty. |
403 | missing_permission | The key does not have Add users. |
403 | suspended | This account's panel is suspended. |
403 | audience_limit | The new people in this request would take your account over its limit, and nothing in the request was applied. new_ids says how many were new. Updates and blocks for people already here still work on their own. |
404 | bot_not_found | This key's account has no bot with that number. |
413 | batch_too_large | More than 1000 ids in one request, counting both lists. |
413 | too_large | The body is over 256 KB. |
429 | rate_limited | Over 60 requests a minute for this account, however many keys it has, or over 20 a second on this key. Put more users in each request. The per-minute answer has a Retry-After header. |
Questions
Why would I ask people to upvote?
Upvotes count toward your place in the ranking on miniapps.me: established apps start from a baseline score we set, and every new upvote adds to it. From time to time we also choose apps to post on our Telegram channel. The people already using your app are the ones most likely to back it, and you can reach them more easily than anyone else can.
Can I reward people for upvoting?
Unlocking something behind an upvote is fine. Paying per upvote is not. We keep the IP address behind every upvote, and farmed upvotes get removed along with the listing that farmed them. Ask, do not buy.
Can I call the API straight from my mini app?
No. Your key would be readable by anyone who opens the mini app. Call it from your server, as shown in the mini app walkthrough.
Why does my listing have to be verified?
A key only answers for listings you own and have verified. Without that, a key would be a way to find out whether a named person upvoted a named bot.
What if someone removes their upvote later?
upvoted goes back to false on your next call. If it matters to you, check again each time rather than saving the answer forever.
What if my key leaks?
Revoke it under Your keys and create a new one. A revoked key stops working on the very next call.