arizuko › components › teled

teled

What it is

teled is the Telegram channel adapter. It long-polls the Telegram Bot API for updates, posts inbound messages and reactions to gated, 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 gated 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
      gated
        |  POST /v1/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 gated, a bot token from @BotFather, and a writable data dir for the poll offset.

export ROUTER_URL=http://gated: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