vibecodedbot 0.1.1

A entirely vibecoded dependency-free Telegram bot library

vibebot

A dependency-free Python Telegram bot library with a route-based syntax.

Install

From this project directory:

pip install .

For editable development:

pip install -e .

Quick Start

import os

from vibebot import VibeBot

bot = VibeBot(os.environ["TELEGRAM_BOT_TOKEN"])

bot.on_command("start").reply("Hello from vibebot.")
bot.on_text("ping", contains=True).reply("pong")
bot.on_media("photo").reply("Nice photo.")


@bot.on_message().act
def echo(event):
    return event.text


bot.start()

Run the included example:

Routes

Routes return a Route object. Use .reply(...) for simple replies and .act when you need a function.

bot.on_command("help").reply("Available commands: /start, /help")
bot.on_text("hello").reply("Hi")
bot.on_text("urgent", contains=True).reply("I saw urgent.")
bot.on_media().reply("Got media.")


@bot.on_media("document").act
def handle_document(event):
    return f"Document file id: {event.media.file_id}"

Available route helpers:

• bot.on_command("start")
• bot.on_text("hello")
• bot.on_text("hello", contains=True)
• bot.on_media()
• bot.on_media("photo")
• bot.on_message()
• bot.on(...) for generic routing

TelegramEvent

Handlers receive a TelegramEvent.

@bot.on_command("start").act
def start(event):
    event.reply(f"Chat id: {event.chat_id}")

Useful properties:

• event.text
• event.caption
• event.command
• event.chat_id
• event.message
• event.update
• event.media
• event.media_kind
• event.photos
• event.photo

Useful reply helpers:

• event.reply("text")
• event.say("text")
• event.reply_photo(...)
• event.reply_video(...)
• event.reply_document(...)
• event.reply_audio(...)
• event.reply_voice(...)
• event.reply_animation(...)
• event.reply_sticker(...)

Returning a string from an .act handler automatically sends it back to the chat.

Sending Media

bot.send_photo(chat_id, "photo.jpg", caption="Photo")
bot.send_video(chat_id, "video.mp4", caption="Video")
bot.send_document(chat_id, "report.pdf")
bot.send_audio(chat_id, "song.mp3")
bot.send_voice(chat_id, "voice.ogg")
bot.send_animation(chat_id, "animation.gif")
bot.send_sticker(chat_id, "sticker-file-id")

Media values can be Telegram file_ids, public URLs, local paths, Path objects, or open binary file objects.

Media groups are supported with Telegram media dictionaries:

bot.send_media_group(
    chat_id,
    [
        {"type": "photo", "media": "photo-file-id-1"},
        {"type": "photo", "media": "photo-file-id-2"},
    ],
)

Files

file_info = bot.get_file("telegram-file-id")
download_url = bot.file_url("telegram-file-id")

Low-Level API

Bot is available when you want raw Telegram Bot API calls:

from vibebot import Bot

bot = Bot("TOKEN")
result = bot.request("sendMessage", chat_id=123, text="Hello")

Running

These are equivalent polling entry points:

bot.start()
bot.listen()
bot.open()

Exports

Main public exports:

• VibeBot
• Bot
• Route
• TelegramEvent
• MediaFile
• Message
• Update
• Chat
• User
• TelegramError