How to Connect HappyCapy to Telegram: Run a Full AI Agent in Any Chat
Your HappyCapy agent — with all its tools, skills, and capabilities — accessible directly from Telegram.
Most Telegram bots answer questions. HappyCapy's Telegram bridge runs claude --print — every message you send triggers a full Claude Code session with Bash access, file operations, web search, image generation, and 300,000+ Skills. Ask it to scrape a website, write a Python script and execute it, or generate a video. It will. That is not a chatbot. That is an agent that happens to live in your Telegram chat.
Why This Is Different from a Telegram Bot
Building a Telegram bot is a weekend project. You register with BotFather, get a token, call the Telegram Bot API, pass incoming messages to an LLM API, return the response. The result is a sophisticated autocomplete machine. It has no file system. It cannot run code. It cannot trigger workflows. It cannot do anything the LLM API cannot do in a single stateless response.
HappyCapy's architecture is different at every layer. HappyCapy runs as an always-on Linux sandbox on Fly.io — root access, Python 3.11, Node.js v24, persistent file storage. When your Telegram message arrives, the bridge calls claude --print with your message as input. That invocation has full tool access: Bash execution, file read/write, web search, image generation, video generation, and the entire 300,000+ Skills library. The agent can open a new shell, run a script, read the output, and send it back to you — all within the same conversation turn.
The practical gap between these two approaches is not incremental. A generic Telegram bot can tell you the weather. HappyCapy's Telegram bot can write code to pull weather data from three APIs, compare them, plot a chart, save it as a PNG, and send it to you as an image — in one message, without you leaving Telegram.
| Feature | Generic Telegram Bot | HappyCapy Telegram Bot |
|---|---|---|
| Answers questions | Yes | Yes |
| Runs Bash commands | No | Yes |
| Writes and executes code | No | Yes |
| Accesses persistent files | No | Yes |
| Generates AI images | No (needs separate integration) | Yes, natively |
| Generates video | No | Yes |
| Web scraping | No | Yes |
| Access to 300,000+ Skills | No | Yes |
| Runs 24/7 without your computer | No | Yes (Fly.io always-on) |
| Per-user conversation history | Limited | Full, persistent |
What You Can Actually Do
The list of capabilities is not theoretical. These are things users do today:
- Ask the bot to scrape a website and return structured data as a table or JSON
- Have it write a Python script, execute it in the sandbox, and return the stdout — no IDE required
- Generate an AI image from a prompt and receive it directly in the Telegram chat
- Trigger any of HappyCapy's 300,000+ Skills mid-conversation — PDF generation, spreadsheet creation, PPTX slides, audio synthesis
- Search the web, read multiple sources, and return a synthesized summary with citations
- Create and save files to persistent storage, then retrieve or update them in later messages
- Run scheduled tasks: the agent can run a script every morning and message you the output
- Monitor a URL or API endpoint and alert you when something changes
- Process uploaded documents — paste a CSV link, get analysis back
- Chain multi-step workflows that would otherwise require switching between five different tools
Pros
- Always on, no laptop required. The sandbox runs on Fly.io infrastructure. You can message the bot from your phone at 2am and it will execute code on a server you never have to touch.
- Single interface for everything. Instead of opening Claude, then a code editor, then a browser, then an image tool — one Telegram message triggers all of it.
- Context persists. Conversation history is stored per user. You can reference something you asked three days ago without re-explaining context.
- Full root access in the sandbox. The agent can install packages, write files, and run any Unix command. No restrictions that a consumer chatbot would impose.
- 300,000+ Skills available instantly. Any workflow that has been packaged as a HappyCapy Skill is one sentence away.
- Shareable. Give the bot username to a colleague or client. Multiple users can interact simultaneously, each with isolated conversation history.
- Free tier available. The Telegram bridge itself adds no cost on top of your existing HappyCapy plan.
Real Use Cases
The freelance developer who left their laptop at the office. You pushed a commit, caught a bug in the deploy logs, and you are already out the door. From your phone you message the bot: "Pull the latest deploy logs from the server and tell me what line 847 is complaining about." Thirty seconds later you have the answer. You message back: "Write a patch and open a PR." Done. No laptop opened.
The small business owner who monitors metrics daily. Instead of logging into five dashboards each morning, the bot runs a scheduled digest. Every 8am: it pulls revenue data from Stripe, visitor counts from an analytics API, and inventory levels from Shopify. It formats the summary and sends it as a Telegram message before the first coffee is finished. The setup took one conversation with the bot to configure.
The researcher who needs quick data extraction. You are reading a paper and want to cross-reference a dataset from three other sources. Switching to a browser, navigating to each source, downloading CSVs, and running a comparison takes 20 minutes. Messaging the bot with the URLs and a description of what you need takes two. The bot scrapes, parses, compares, and returns a table.
The parent who set up a homework helper. The kids have a Telegram account already. The HappyCapy bot was added to a family group. It can explain math problems step by step, generate diagrams, write practice questions, and check answers — without ads, without account creation, and without the distraction loop of a consumer chatbot. The parent keeps the admin token; the kids get a focused tool.
How to Set It Up
Setup takes under five minutes if you have a HappyCapy account. The process starts with Telegram's BotFather: message @BotFather, run /newbot, choose a name, and receive a bot token — a string that looks like 7384920156:AAF.... That token is all HappyCapy needs to know where to route conversations.
Inside HappyCapy, the Telegram skill handles the rest. Run the skill, paste your bot token when prompted, and the bridge is live. The skill starts a polling loop in the sandbox that listens for incoming Telegram messages and routes them through claude --print with full tool access. Conversation history is stored per Telegram user ID, so each person who messages your bot gets their own persistent session.
The full skill with setup scripts, environment variable documentation, and configuration options for rate limiting and user allowlists is available at github.com/ndpvt-web/happycapy-telegram. If you want a deeper understanding of why HappyCapy's agent architecture differs from a typical chatbot setup before you start, AI Agent vs Chatbot covers the distinction in detail. And if you are thinking about running your own persistent AI infrastructure instead of relying on Fly.io, the Mac Mini as AI Server 2026 breakdown is worth reading first.
Frequently Asked Questions
Does the bot run 24/7 or only when my computer is on? It runs 24/7. The sandbox lives on Fly.io's infrastructure, not your local machine. Once you deploy the Telegram skill, it stays alive without your computer being on or even connected to the internet.
Can the bot access my HappyCapy files and tools? Yes. The bot runs inside your HappyCapy sandbox, which means it has access to everything in that environment: files you have stored, skills you have installed, environment variables you have set, and any integrations you have connected. It is your agent, accessible through a different interface.
Is this free to use? The Telegram bridge skill itself is free. Your costs are determined by your HappyCapy plan, which covers the sandbox compute and AI model usage. There are no additional fees for the Telegram integration layer.
How does per-user conversation history work? Each Telegram user ID gets its own conversation thread stored in the sandbox. When user A sends a message, the bot loads user A's history and appends the new turn. User B's messages are completely isolated. History is persistent across sessions — a conversation you had a week ago is still accessible in context unless you explicitly clear it.
Can I restrict who can use the bot? Yes. The skill supports an allowlist configuration. You can specify a list of Telegram user IDs or usernames that are permitted to interact with the bot. Messages from users not on the allowlist are silently ignored or return a custom rejection message — your choice.
What happens if Telegram rate-limits my bot? The skill handles rate limiting with exponential backoff. If Telegram returns a 429 response, the bridge pauses, waits the required retry period, and resumes automatically. You will not lose messages. In practice, rate limits only trigger under heavy simultaneous load, which is configurable in the skill settings.
Can multiple people use the bot simultaneously? Yes. The polling loop processes messages asynchronously, and each user session is independent. There is no queue that blocks one user while another is being served. Under very high load, you can scale the sandbox instance on Fly.io to handle more concurrent sessions — the skill documentation covers this configuration.
Final Thoughts
The Telegram integration is not a feature for its own sake — it removes the last friction point between you and a fully capable AI agent. Your HappyCapy sandbox already runs code, generates media, and orchestrates 300,000+ Skills. The Telegram bridge means you access all of that from wherever you already are, with no context switch. Whether that is useful at 2am when you are debugging remotely or useful every morning when you want a structured briefing before you open your laptop — it is the same agent, now available in every pocket.
