Docs

Quickstart

The full flow takes about a minute. Skip ahead if you already have a Telegram bot token.

123456789:AAH-...your-token-here...

How it works

Once your bot is registered, every inbound message follows this path:

User → Telegram → AI Snapsolve webhook → AI agent → Telegram → User

1. End user messages your bot on Telegram (@YourBot_bot).
2. Telegram POSTs the update to:
   POST /api/telegram/whitelabel/<your-bot-id>
   Header: x-telegram-bot-api-secret-token: <per-bot-secret>
3. We verify the secret, look up your bot row in dev_bots,
   atomically check + bump the monthly quota.
4. We assemble the AI request:
   - system: your custom system_prompt (or default)
   - history: last 10 messages for this (bot, chat_id) pair
   - user: the inbound message text
5. Claude or GPT generates a reply.
6. We send the reply via:
   POST https://api.telegram.org/bot<your-token>/sendMessage
7. Both messages are persisted to dev_bot_messages for analytics.

Writing a good system prompt

The system prompt is your bot's personality and rules. Keep it focused.

Good example

You are an AP Calculus study coach.
- Solve problems step-by-step, showing the key intermediate steps.
- Use **bold** for the final answer.
- If a question is outside calculus, gently redirect: "I focus on calculus — try @AiSnapsolve_bot for general help."
- Keep replies under 250 words unless the problem genuinely needs more.

Tips

• Set a tone (warm, blunt, sarcastic — your call).
• Give an explicit scope — what topics, what to refuse.
• Mention formatting: Markdown **bold** and `code` render in Telegram.
• Avoid contradictions — if you say “always be brief” and also “always show full work”, the AI will pick one.

Quotas and rate limits

Each bot has its own monthly request budget. One inbound message processed = one request. Replies, retries, and command-only responses (/start, /help) don't count.

When a bot hits its quota, end users see a friendly “quota reached” message. Counters reset at the start of each calendar month (UTC).

Security

• Per-bot webhook secrets. When you create a bot, we generate a unique secret and tell Telegram to include it on every update via the x-telegram-bot-api-secret-token header. Requests without the right secret are rejected.
• Row-level security. Your bots and message logs are RLS-protected: only your Supabase user can read them. Backend writes go through the service role.
• Token rotation. If your token is leaked, regenerate it via /revoke in BotFather, then delete + recreate the bot here with the new token.

FAQ