Telegram AI Agent Template (Python)

A ready-to-run starting point for building a Telegram AI agent in Python. If you're looking for how to build a Telegram bot that answers with an AI model, clone this template, add your bot token, plug in your model, and run — the messaging plumbing (receiving updates, replying in the right chat, deduping) is handled by Caspian, so all you write is one handler.

Quickstart (under 5 minutes)

1. Use this template — click "Use this template" at the top of this repo (or clone it), then cd into your new project.
2. Install dependencies:

   pip install -r requirements.txt

3. Get a Telegram bot token — message @BotFather on Telegram, send /newbot, and copy the token it gives you.
4. Get a Caspian API key — copy .env.example to .env, then fill it in:

   cp .env.example .env
   pipx run caspian-cli init   # writes your CASPIAN_API_KEY

   Paste your bot token into TELEGRAM_BOT_TOKEN in the same .env.
5. Run it:

   python main.py

   Message your bot on Telegram — it replies. Now open main.py and replace the placeholder in respond() with your model call.

How it works

• CommClient() reads CASPIAN_API_KEY and CASPIAN_BASE_URL from your environment or .env.
• client.connect_telegram(bot_token=...) connects your bot — no webhook or server to host.
• The @client.on_message handler fires for every inbound message; message.text is what the user sent.
• message.reply(...) answers in the same chat.
• client.listen() runs the loop for the lifetime of your agent.

Plug in your model

The template ships with an echo placeholder. In main.py, the respond(text) -> str function is the one spot to change:

def respond(text: str) -> str:
    # PLUG YOUR LLM CALL HERE
    reply = my_model.generate(text)
    return reply

It's provider-neutral — use any model or agent framework you like.

Add more channels

The same handler works across every channel Caspian supports — you just add one more connect_* call. For example, to also answer on Discord:

client.connect_discord(bot_token=os.environ["DISCORD_BOT_TOKEN"])

No new handler code. Email, Slack, WhatsApp, SMS, and more work the same way.

Links

• Main repo: github.com/TryCaspian/caspian-sdk — star it if useful.
• Docs: trycaspianai.com

License

MIT — see LICENSE.