Telegram

Triggers turn an agent into a long-lived service that waits for events, acts on them, delivers the result, and goes idle. The telegram trigger connects that loop to Telegram over Bot API long-polling — outbound HTTPS only, so the agent needs no public endpoint. It watches chats and replies to the messages that wake it.

triggers:
  - type: telegram
    # chats: ["-1001234567890"]  # chat ids, group titles, or @usernames; omit for all
    # require_mention: true      # only respond when @-mentioned (private chats always respond)
    # token_env: TELEGRAM_BOT_TOKEN (default)
    # from_users: ["gtchax"]     # only handle these authors (user ids or usernames)
    # reply_chat: "-100987..."   # post replies here instead of the source chat
    # allow_silence: true        # a reply of exactly __NO_REPLY__ posts nothing

Setup

This is the fastest channel to set up — about 2 minutes:

1. Message @BotFather on Telegram, send /newbot, and follow the prompts.
2. Copy the token it gives you and export it: export TELEGRAM_BOT_TOKEN=...
3. Run the agent: af run agent.yaml — then message your bot.

For group chats, one more thing: bots have privacy mode on by default, so in groups they only receive messages that @-mention them or reply to them. Either that's what you want (pair it with require_mention: true), or turn it off via BotFather's /setprivacy and re-add the bot to the group.

The agent replies in-chat to the triggering message; conversations are keyed per chat, and memory.scope: thread continues them (Memory). It ignores bots and empty messages; long replies split at Telegram's 4096-char limit. Private chats always address the bot — require_mention only gates groups.

Observer agents

Three optional keys together turn the trigger from a chatbot into an observer — an agent that watches chats, reacts to specific people, and reports elsewhere (a review bot, a moderation assistant, a coach):

• from_users — handle only these authors (user ids or usernames). The filter runs before the model is called: everyone else's messages are dropped in the trigger and never reach the provider.
• reply_chat — deliver replies to a dedicated chat instead of the source. Out-of-chat replies quote the triggering message and link back to it when the source is a supergroup.
• allow_silence — let the agent say nothing. Instruct it in purpose to answer with exactly __NO_REPLY__ when it has no feedback; the trigger then posts nothing instead of a "looks fine" reply on every message.

Every run — replied or silent — lands in the agent's run history with its status, steps and tokens.