Telegram Bot API

{
  "service_type": "platform",
  "base_url": "https://api.telegram.org",
  "auth_method": "api_key",
  "auth_config": {
    "bot_token": "Obtained from @BotFather, format like 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11",
    "header_scheme": "none_traditional",
    "alternative": "Telegram also supports user-session (MTProto) auth with api_id + api_hash via core.telegram.org/api"
  },
  "endpoints": [],
  "pricing_model": {
    "type": "freemium",
    "details": {
      "bot_api": "free, with no per-message cost",
      "broadcast_limits": "bot messaging is rate-limited to roughly 30 messages/second; free bulk broadcasting is restricted",
      "paid_options": "Telegram Premium subscriptions (user-facing), Telegram Stars, Bot advertising/promoted messages, paid broadcasting via Telegram Ads"
    }
  },
  "rate_limits": {
    "bot_api": "~30 messages per second globally; ~20 messages per minute per chat for group messages; bulk notifications capped",
    "file_uploads": "up to 2 GB per file via Bot API; up to 4 GB via local Bot API server",
    "documented": true
  },
  "capabilities": [
    "Send/receive text, media, documents, voice, video notes, stickers, polls, locations, contacts",
    "Inline bots and inline keyboards",
    "Custom keyboards and reply markup",
    "Webhooks and long polling for updates",
    "Group and channel administration (ban, restrict, promote, invite links)",
    "Bot commands and scoped commands",
    "Payments via Telegram Payments (Stripe, etc.) and Telegram Stars",
    "Mini Apps / Telegram Web Apps (embedded HTML/JS applications)",
    "Games platform",
    "Localization and language support",
    "Secret chats (MTProto client API only)",
    "File streaming and storage via file_id",
    "Bot-to-bot communication and Business account integration",
    "Webhook secret token verification",
    "Message reactions, editing, deletion, pinning, forwarding",
    "Passport (Telegram Passport) for identity/verification data",
    "Bot API server can be self-hosted locally"
  ],
  "raw_analysis": "Telegram is a mature, cross-platform cloud-based messaging and VoIP service operated by Telegram Messenger LLP (originally founded by Pavel and Nikolai Durov). The public surface is telegram.org (marketing, apps, FAQ, safety) and core.telegram.org (developer documentation). The platform is aimed at end users (individuals and groups) and developers building bots, mini apps, channels, and integrations.\n\nMaturity: Telegram launched in 2013 and is one of the largest messaging platforms worldwide, with hundreds of millions of monthly active users. The Bot API is stable and versioned, with frequent feature additions (welcome messages, buttons, communities, ephemeral group messages, rich text for bots, AI guardians, smartwatch apps, etc. as shown on the homepage blog feed). The MTProto client API is more advanced and lower-level, enabling custom clients.\n\nAPI surface: The Bot API is a straightforward HTTP-based JSON API at https://api.telegram.org/bot<token>/METHOD, with long polling (getUpdates) or webhooks (setWebhook). Auth is a bot token issued by @BotFather. There is no OAuth for bots; simply bearer-in-URL token. The core.telegram.org/api surface is a TL-schema RPC used by official and third-party clients, with api_id/api_hash plus user sessions (MTProto).\n\nPricing: The core API usage is free. Telegram monetizes via Premium subscriptions, Telegram Stars, Ads, and paid broadcasting. Bot messaging is rate-limited rather than metered. Self-hosting the Bot API server is possible for higher limits and larger files.\n\nEcosystem/integrations: Extensive — libraries in virtually every language (python-telegram-bot, aiogram, Telethon, grammY, telegraf, etc.), cloud platform integrations (serverless webhooks on AWS Lambda, Cloudflare Workers, Vercel), payment providers, and Mini App SDK. The file_id system and 2 GB (4 GB local) file limits make it usable as a lightweight storage/CDN for bots.\n\nNotes on this input: The provided 'Auto-generated OpenAPI schema' and HTML show the public marketing site, not the API spec. The real Bot API docs are at https://core.telegram.org/bots/api and machine-readable OpenAPI/JSON schemas are community-maintained. No official OpenAPI file is published by Telegram, so this platform is not a typical REST-API-with-swagger service; it is a platform with an HTTP Bot API plus a lower-level MTProto API.",
  "confidence": 0.95
}

2/3 tests passed

```json
{
  "overall": 84,
  "dimensions": {
    "token_efficiency": 9.5,
    "first_try_success": 9.0,
    "response_parseability": 9.5,
    "error_clarity": 8.5,
    "doc_quality": 9.0,
    "auth_simplicity": 8.0,
    "latency": 7.0,
    "consistency": 8.5
  },
  "pricing_normalized": {
    "model": "freemium",
    "free_tier": "Bot API free with no per-message cost",
    "rate_limits": "~30 messages/second broadcast limit",
    "paid_extras": ["Telegram Premium", "Telegram Stars", "Telegram Ads", "paid broadcasting"]
  },
  "issues": [
    "No llms.txt (404) — agents lack a canonical machine-readable entry point",
    "robots.txt disallows all crawling (Disallow: /), which may impede agentic doc retrieval",
    "Main website latency ~683ms is moderate, not sub-500ms",
    "Bot API broadcast rate limits (~30 msg/s) can bite agents doing bulk operations",
    "Auth for bots requires BotFather onboarding and token handling; no magic-link/SSO for agent identity"
  ],
  "recommendations": [
    "Publish an llms.txt summarizing Bot API endpoints, rate limits, and auth flow for agent consumption",
    "Relax robots.txt for documentation paths to allow agent/doc indexing while keeping sensitive routes blocked",
    "Consider adding a Notlogin-style verified agent identity flow so agents can provision bots without a human BotFather dance",
    "Expose structured error codes/messages (already good) with a public error reference page",
    "Document rate-limit backoff guidance prominently to improve first-try success on bulk sends"
  ]
}
```