BotMember
Sign inCheckout

Documentation

Everything you need to add paid access to your Telegram bot.

Quickstart

  1. 1Sign up and go to the dashboard
  2. 2Click "Connect Bot" and paste your bot token from @BotFather
  3. 3Create plans (Free, Pro Monthly, Lifetime, or Credits)
  4. 4Copy your API key (shown once after creation)
  5. 5In your bot code, call /api/access/check before responding
  6. 6Send locked users to /store/{botId}?telegram_user_id={id} to choose a plan and pay

Access Check API

Call this endpoint before your bot responds to any premium feature. Pass the user's Telegram user ID (a numeric string).

GET /api/access/check?telegram_user_id=123456789

Authentication

Authorization: Bearer bm_your_api_key

Response when active

{
  "active": true,
  "status": "subscription",
  "plan": {
    "id": "plan_abc123",
    "name": "Pro",
    "type": "subscription"
  },
  "telegram_user_id": "123456789",
  "expires_at": "2026-06-01T00:00:00.000Z",
  "credits_remaining": null,
  "checkout_url": null
}

Response when not active

{
  "active": false,
  "status": "not_found",
  "plan": null,
  "telegram_user_id": "123456789",
  "expires_at": null,
  "credits_remaining": 0,
  "checkout_url": "https://app.botmember.com/store/my-bot?telegram_user_id=123456789"
}
Security note: Always use telegram_user_id as the identity — never username. Usernames can change; numeric IDs are permanent.

Use Credit API

For credit-based plans, deduct credits after a premium action. The deduction is atomic — it will never go below zero.

POST /api/access/use-credit
// After a premium action, deduct one credit
const res = await fetch(`${BOTMEMBER_URL}/api/access/use-credit`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ telegram_user_id: ctx.from.id, amount: 1 }),
});

const { success, credits_remaining } = await res.json();
if (!success) {
  return ctx.reply("You've used all your credits. Get more:");
}

Node.js Example (Telegraf)

// Using Telegraf
const res = await fetch(
  `${BOTMEMBER_URL}/api/access/check?telegram_user_id=${ctx.from.id}`,
  {
    headers: {
      Authorization: `Bearer ${process.env.BOTMEMBER_API_KEY}`,
    },
  }
);

const { active, checkout_url, credits_remaining } = await res.json();

if (!active) {
  return ctx.reply("Upgrade to access this feature:", {
    reply_markup: {
      inline_keyboard: [[{ text: "Upgrade →", url: checkout_url }]],
    },
  });
}

// User has access
ctx.reply("Premium feature unlocked ✅");

Python Example (aiogram)

import httpx

async def check_access(telegram_user_id: int) -> dict:
    async with httpx.AsyncClient() as client:
        res = await client.get(
            f"{BOTMEMBER_URL}/api/access/check",
            params={"telegram_user_id": str(telegram_user_id)},
            headers={"Authorization": f"Bearer {BOTMEMBER_API_KEY}"},
        )
        return res.json()

# In your message handler (aiogram example)
@dp.message()
async def on_message(message: Message):
    data = await check_access(message.from_user.id)

    if not data["active"]:
        await message.answer(
            "Upgrade to access this:",
            reply_markup=InlineKeyboardMarkup(
                inline_keyboard=[[
                    InlineKeyboardButton(text="Upgrade", url=data["checkout_url"])
                ]]
            )
        )
        return

    await message.answer("Premium feature unlocked ✅")

n8n (no-code)

1. Add a Telegram Trigger node (Message Received)
2. Add an HTTP Request node:
   - Method: GET
   - URL: https://app.botmember.com/api/access/check
   - Query Parameters: telegram_user_id={{ $json.message.from.id }}
   - Headers: Authorization: Bearer bm_your_api_key
3. Add an IF node:
   - Condition: {{ $json.active }} equals true
4. If true → continue your automation
5. If false → send the checkout_url back to the user

cURL

curl -H "Authorization: Bearer bm_your_api_key" \
  "https://app.botmember.com/api/access/check?telegram_user_id=123456789"

Hosted store page

Send users this URL from your bot when they need to pay. The store page lets them choose a plan, creates a PayPal order for paid plans, and grants access directly for free plans.

/store/{publicBotId}?telegram_user_id={userId}&username={username}&first_name={firstName}

Get the publicBotId from your bot's dashboard. The telegram_user_id is required; name fields are optional and stored for display.

Security

  • • Bot tokens are encrypted with AES-256-GCM and never returned to the frontend.
  • • API keys are stored as SHA-256 hashes — only the raw key can verify access.
  • • Your API key is only shown once. Regenerate from the dashboard if lost.
  • • Rate limit: 100 requests/minute per API key on access checks.
  • • telegram_user_id is the authoritative identity. Do not rely on username.
  • • Checkout pages accept Telegram user data from query params. For stronger verification, a Telegram Login Widget can be added in a future version.