telegram-bot-api

Telegram Bot API (Raw HTTP)

Untether uses a custom Telegram Bot API client built on httpx (async) and msgspec (JSON). There is no Telegram SDK dependency.

Key files

File	Purpose
src/untether/telegram/client.py	TelegramClient — all Bot API calls
src/untether/telegram/outbox.py	TelegramOutbox — queued send/edit/delete with rate limiting
src/untether/telegram/bridge.py	TelegramPresenter — renders progress, inline keyboards, answers
src/untether/telegram/loop.py	Long polling loop (getUpdates), callback dispatch
src/untether/telegram/commands/	Command and callback handlers
docs/reference/transports/telegram.md	Full transport reference

Bot API call pattern

All calls go through TelegramClient, which wraps httpx.AsyncClient:

# Typical Bot API call (inside TelegramClient)
resp = await self._http.post(
    f"{self._base_url}/bot{self._token}/{method}",
    json=params,
)
data = msgspec.json.decode(resp.content, type=TelegramResponse)

• Base URL: https://api.telegram.org
• Auth: bot token in the URL path (/bot<token>/)
• All responses decoded with msgspec.json.decode into typed structs
• Error handling: check ok field, raise on HTTP or Telegram errors

Inline keyboards and callback queries

Permission requests and plan mode buttons use Telegram inline keyboards:

# reply_markup structure in RenderedMessage.extra
{
    "reply_markup": {
        "inline_keyboard": [
            [{"text": "Approve", "callback_data": "ctrl:approve:<request_id>"}],
            [{"text": "Deny", "callback_data": "ctrl:deny:<request_id>"}],
            [{"text": "Pause & Outline Plan", "callback_data": "ctrl:discuss:<request_id>"}],
        ]
    }
}

• Callback data format: <prefix>:<action>:<id> (max 64 bytes)
• Must call answerCallbackQuery promptly to clear the spinner
• Early answering: set answer_early = True on the backend to clear the spinner immediately with a toast