teli — Telegram bot toolkit

teli is a Python library and CLI for managing Telegram bots and personal Telegram accounts: named connections, async long-polling, message handlers, and a wavi-compatible driver interface.

Install

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

Quick start — Bot connections

# 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 via the bot
teli send mybot 987654321 "Hello from teli!"

# Check what's registered
teli status

Quick start — Personal user account

Send messages from your own Telegram account (no bot token needed):

# 1. Get API credentials at https://my.telegram.org → API development tools
# 2. Register your account
teli user add me --api-id 12345678 --api-hash abc123...

# 3. Authenticate once (asks for phone + code)
teli user connect

# 4. Send messages directly
teli user send Luganense "Hola!"
teli user send @username "Hola!"
teli user send 987654321 "Hola!"

All commands

teli status                                      Show all connections + user accounts
teli add <name> --token TOKEN                    Register a bot
teli list                                        List bot connections
teli remove <name>                               Remove a bot
teli send <name> <chat_id> <message>             Send via bot
teli listen <name> [--webhook URL]               Long-poll incoming messages
teli whoami <name>                               Get bot identity

teli user add <name> --api-id ID --api-hash H    Register personal account
teli user accounts                               List personal accounts
teli user connect [name]                         Authenticate (once)
teli user send <recipient> <message>             Send from your account
teli user listen --bot <bot_username>            Listen for bot messages

teli install-skill                               Install Claude Code skill

Claude Code skill

Install a skill that teaches Claude how to use teli:

teli install-skill

This copies SKILL.md to ~/.claude/skills/teli/. After restarting Claude Code, you can invoke it as /teli.

Python API

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!")

await bot.start()
await bot.stop()

Driver interface (wavi-compatible)

import teli.driver as td

await td.connect("mybot")
await td.send("mybot", "987654321", "Hola!")
print(await td.status("mybot"))
await td.stop("mybot")

Development

pip install -e ".[dev]"
pytest tests/ -v