teled

teled long-polls the Telegram Bot API for updates and sends the replies of the agent as Bot API calls.

teled connects Telegram to arizuko

teled connects Telegram to 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 sends outbound calls to the Bot API. teled reads its numeric bot id from getMe before registration. It registers telegram:<bot_id>/ and telegram:group/. A DM has the JID telegram:<bot_id>/user/<user_id>. The sender and pairing identity stay telegram:user/<user_id>. A group has telegram:group/<id>. teled removes the minus sign of the Telegram group id.

Telegram is the main personal channel

Telegram is the main personal channel of 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, which routd does not do itself.

teled sits between Telegram and routd

Telegram (api.telegram.org)
        │  long-poll getUpdates (allowed_updates=[message, message_reaction])
        ▼
      teled     (LISTEN_ADDR=:8080)
        │  POST /v1/messages    (service:<daemon> ES256 bearer)
        ▼
      routd
        │  POST /send           (callback to teled)
        ▼
      teled     (sendMessage / sendPhoto / setMessageReaction / ...)
        │
        ▼
      Telegram

The wired verbs are in teled/bot.go:

send, post, delete: Plain Bot API calls.
send_file: A photo, video or document, chosen by the file extension.
like: setMessageReaction, with 👍 by default.
forward: A real forwardMessage when the source carries chatJid|id.
edit: Own messages only, within a 48-hour window.
typing: Refreshed every 4 seconds.

dislike, quote and repost return 501 with a hint. The agent gets a structured pointer to like(emoji='👎'), reply or forward.

teled filters out the own user id of the bot from inbound traffic and passes messages from other bots through. routd promotes a reply to the bot and a reaction on a bot message to verb=mention.

Telegram file URLs that contain the bot token expire quickly, so teled serves them to the agent through GET /files/<file_id>.

teled runs alone with routd and a bot token

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

export ROUTER_URL=http://routd:8080
export AUTHD_URL=http://authd:8080
export AUTHD_SERVICE_KEY=$(grep ^AUTHD_SERVICE_KEY .env | cut -d= -f2)
export LISTEN_ADDR=:8080
export TELEGRAM_BOT_TOKEN=<bot token>
export DATA_DIR=/srv/data/arizuko_demo
export ASSISTANT_NAME=arizuko
./teled

On the Telegram side, talk to @BotFather, create a bot and copy the token. For group chats, add the bot, and then make it an admin or turn off privacy mode. Then it can read messages that are not commands. teled long-polls, so no webhook setup is necessary.

GET /health returns 503 with {status:"disconnected"} when the link to Telegram is down. Otherwise it returns 200, with the status stale when no inbound message arrived for 5 minutes.

Telegram limits some verbs

The chat admin allow-list limits reactions, and an emoji outside the list gets a 400. To delete the messages of other users, the bot needs can_delete_messages. fetch_history returns source: "unsupported", because the Telegram Bot API has no history endpoint per chat. routd then uses its local cache.

Two sources cover the details

components/channels: the verb table across adapters.
[teled/README.md]: the full environment variables, the verb table and the limits.