teled

What it is

In plain terms, teled is the connector that plugs Telegram into arizuko, so the agent can read and reply in Telegram chats and groups.

teled is the Telegram channel adapter. It long-polls the Telegram Bot API for updates, posts inbound messages and reactions to routd, and serves outbound calls back to the Bot API. JID prefix is telegram:; per-chat JIDs look like telegram:<chat_id>.

Why it exists

Telegram is the workhorse personal channel for arizuko deployments — it is free, has a stable bot API, and supports voice notes and file uploads up to 50 MB without partner approval. teled gives arizuko the long-poll loop, the file proxy, and the reaction translation that routd does not do itself.

How it fits

Telegram (api.telegram.org)
        |  long-poll getUpdates (allowed_updates=[message, message_reaction])
        v
      teled     (LISTEN_ADDR=:8080)
        |  POST /v1/messages    (signed by CHANNEL_SECRET)
        v
      routd
        |  POST /send           (callback to teled)
        v
      teled     (sendMessage / sendPhoto / setMessageReaction / ...)
        |
        v
      Telegram

Wired verbs (teled/bot.go): send, send_file (photo / video / document by extension), post, like (setMessageReaction, default 👍), delete, forward (true forwardMessage when the source carries chatJid|id), edit (own messages, 48 h window), typing (refreshed every 4 s). dislike, quote, repost are 501-with-hint — the agent gets a structured pointer to like(emoji='👎') / reply / forward.

Inbound mention detection: the bot’s own user-id is filtered from incoming traffic, but messages from other bots are passed through (fixed in v0.40.5 — before that, all bot-authored messages were silently dropped). Reply-to-bot and reactions on bot messages are promoted to verb=mention by the gateway.

Telegram bot-token file URLs are short-lived, so teled proxies them via GET /files/<file_id> for the agent.

Standalone usage

teled is a plain Go binary. It needs a reachable routd, a bot token from @BotFather, and a writable data dir for the poll offset.

export ROUTER_URL=http://routd:8080
export CHANNEL_SECRET=$(grep ^CHANNEL_SECRET .env | cut -d= -f2)
export LISTEN_ADDR=:8080
export TELEGRAM_BOT_TOKEN=123456:ABC-...
export DATA_DIR=/srv/data/arizuko_demo
export ASSISTANT_NAME=arizuko
./teled

Telegram-side setup: talk to @BotFather, create a bot, grab the token. For group chats: add the bot, then either give it admin or disable privacy mode so it can read non-command messages. No webhook setup required — teled long-polls.

GET /health returns 200 when connected AND inbound has flowed in the last 5 minutes; 503 with {status:"disconnected"} otherwise.

Verb support

Notes from teled/README.md: reactions are bounded by the chat’s admin allow-list (off-list emojis 400). delete for other users’ messages requires can_delete_messages. fetch_history returns source: "unsupported" — Telegram Bot API has no per-chat history endpoint; the gateway falls back to its local cache.

Go deeper

components/channels — cross-adapter verb matrix.
teled/README.md — full env vars, verb table, limitations.