teli-lib 0.1.0

Telegram bot toolkit: named connections, long-polling, send/receive, and a wavi-compatible driver

teli — Telegram bot toolkit

teli is a Python library and CLI for managing Telegram bots: named connections, async long-polling, message handlers, and a wavi-compatible driver interface for drop-in use alongside WhatsApp automation.

Install

pip install teli
# with user-client support (Telethon):
pip install "teli[user]"

Quick start — CLI

# Register a bot
teli add mybot --token 123456:ABC...

# Discover your chat_id (send /start to the bot, look at output)
teli listen mybot

# Lock down allowed chats
teli update mybot --allow 987654321

# Send a message
teli send mybot 987654321 "Hello from teli!"

Quick start — Python

from teli.bot import Bot

async with Bot.from_connection("mybot") as bot:
    await bot.send_message(987654321, "Hello!")

Long-polling daemon with handlers:

bot = Bot.from_connection("mybot")

@bot.on_command("start")
async def handle_start(msg):
    await bot.send_message(msg["chat"]["id"], "Hi! I'm running on teli.")

await bot.start()
# ... keep alive ...
await bot.stop()

Driver interface (wavi-compatible)

teli.driver exposes the same 7-function interface as wavi_driver, so Pulpo and other orchestrators can treat Telegram and WhatsApp interchangeably:

import teli.driver as td

await td.connect("mybot")                          # start bot
await td.send("mybot", "987654321", "Hola!")       # contact = chat_id
print(await td.status("mybot"))                    # {"daemon_running": True, ...}
print(td.list_session_names())                     # ["mybot"]
await td.stop("mybot")

Function	Returns	Notes
connect(session, new)	{"ok": bool, "qr_page": None, ...}	new is a no-op (no QR for bots)
check_updates(session)	{"status": "ok", "new_inbound": []}	no-op — Telegram is push
send(session, contact, text)	{"ok": bool, ...}	contact = chat_id
status(session)	{"daemon_running": bool, "authenticated": bool, ...}
list_session_names()	list[str]	sync
stop(session)	{"ok": bool, ...}
daemon_running_by_pid(session)	bool	sync

Named connections

Connections are stored in data/connections.json (or $TELI_DATA_DIR/connections.json):

{
  "connections": [
    {
      "name": "mybot",
      "token": "123456:ABC...",
      "allowed_chats": ["987654321"]
    }
  ]
}

User client (Telethon)

The optional [user] extra enables a user-account listener (receive messages sent to your bot from your own Telegram account):

teli user setup mybot --api-id 12345 --api-hash abc123 --bot-username mybotname
teli user connect mybot
teli user listen mybot

License

MIT — see LICENSE.