Telegram Events

Telegram surfaces the same provider-neutral chat.* event keys as Slack and Discord, so an agent’s Telegram triggers look like its Slack triggers with a different connection: and $.chat.provider: telegram. This page covers what is Telegram-specific: how bots receive messages, how mentions resolve to agents, and which parts of the shared chat contract Telegram does and does not emit.

How Telegram connects

Each agent identity on Telegram is its own Telegram bot, created and managed through a manager bot connection. The connection name defaults to telegram-<manager-bot-username> — for example telegram-FractalWorks_bot — and that is the name a trigger’s connection: field references. Messages arrive on per-bot webhooks; unlike Slack there is no workspace-level event stream, so each bot sees the chats it participates in.

triggers:
  - events:
      - chat.message.mentioned
      - chat.message.direct
    connection: telegram-FractalWorks_bot
    where:
      $.chat.provider: telegram
      $.auto.authored: false
    routing:
      kind: spawn

Event keys

Event	Fires when
`chat.message.mentioned`	A group message @-mentions the agent’s bot username. Delivered as an addressed copy targeting that agent; the thread is subscribed.
`chat.message.direct`	A direct message to the agent’s bot. The conversation is subscribed automatically.
`chat.message.subscribed`	A new message in a conversation the bot is subscribed to (after a mention, a DM, or an explicit subscribe from a session).
`chat.message.channel`	Any other group message the bot receives.
`chat.reaction.added` / `chat.reaction.removed`	An emoji reaction was added to or removed from a message.

Telegram does not emit chat.message.edited — edit events are wired for Slack and Discord only. A Telegram message edit produces no trigger event.

Mentions

A mention on Telegram is a literal @<bot-username> in a group message. auto extracts the mentioned bot usernames from the raw message and matches them against the agent bot personas realized on the connection; each matched agent receives its own addressed chat.message.mentioned event. Since bot usernames are globally unique on Telegram, there is no alias-prefix scheme like Slack’s @auto.<alias>. Direct messages need no mention: any DM to the agent’s bot arrives as chat.message.direct. Note that Telegram users must start a conversation with a bot before it can message them — an agent can always reply in a chat it was written to, but cannot open a cold DM to a user who never started its bot.

Payload

Telegram events use the shared chat payload — see the Slack events page for the full field-by-field reference. In summary:

chat — provider: "telegram", kind, threadId, channelId, isDirectMessage, messageId. Thread and channel ids are canonical, provider-prefixed ids — pass them back to chat.send exactly as delivered.
message — text, author (with author.userName and author.isMe as the commonly used fields), isMention, dateSent, attachments, links.
auto — mentioned, authored, contextual, attribution / attributions (sessions already attached to the conversation), and agent on addressed events.
raw — the raw Telegram update.

Reactions carry reaction (added, emojiName, rawEmoji, emoji, user) plus the chat envelope with messageId pointing at the reacted-to message. One Telegram nicety: the group title rides on every message payload, and auto records it as a durable destination alias — so a session can later chat.send to that group by title, not just by numeric chat id.

Template placeholders

message: |
  {{message.author.userName}} wrote on {{chat.provider}}:

  {{message.text}}

  Chat: {{chat.channelId}}
  Thread: {{chat.threadId}}

Filters

Filter	Use
`$.chat.provider: telegram`	Pin the trigger to Telegram when the agent also listens on Slack or Discord.
`$.auto.authored: false`	Suppress the agent’s own messages. Required on every `attributedSessions` deliver trigger over `chat.message.*`.
`$.auto.attributions: { exists: false }` / `{ exists: true }`	The spawn/deliver split: spawn only for fresh conversations, deliver only into conversations with an attributed session. Required to be mutually exclusive when both triggers listen on the same event.
`$.chat.isDirectMessage: true`	Match DMs only.
`$.reaction.user.isMe: false`	Ignore the bot’s own reactions.

Threads and routing

Telegram messages and reactions carry the same canonical chat-thread routing target as every chat provider: the pair (connection grant, chat.threadId). The target type is named slack.thread for historical reasons but is provider-agnostic — a Telegram conversation binds through it exactly like a Slack thread. The standard patterns:

spawn on chat.message.mentioned / chat.message.direct for new conversations.
deliver + routeBy: { kind: attributedSessions } for follow-up messages and reactions in conversations a session already owns.
bind with target: slack.thread to resolve an event to the one session bound to its conversation.

Example: a conversational agent on Telegram

Adapted from the managed @auto/chat-assistant template — a chat agent that answers mentions and DMs, keeps each conversation in one session, and notices reactions to its messages.

.auto/agents/assistant.yaml

name: assistant
systemPrompt: |
  You are the team's conversational assistant. Reply in the
  thread you were addressed in using chat.send with target provider
  `telegram`, the triggering channel, and the triggering thread.
  Never reply to your own messages.
initialPrompt: &initial_prompt |
  Someone mentioned you on {{chat.provider}} and wants to chat.

  - Channel: {{chat.channelId}}
  - Thread: {{chat.threadId}}
  - Author: {{message.author.userName}}
  - Message: {{message.text}}

  Reply in that thread with chat.send, then subscribe so the rest of the
  conversation routes back to this session.
tools:
  auto:
    kind: local
    implementation: auto
  chat:
    kind: local
    implementation: chat
    auth:
      kind: connection
      provider: telegram
      connection: telegram-FractalWorks_bot
triggers:
  # New conversation: a mention or DM with no session attached yet.
  - events:
      - chat.message.mentioned
      - chat.message.direct
    connection: telegram-FractalWorks_bot
    where:
      $.chat.provider: telegram
      $.auto.authored: false
      $.auto.attributions:
        exists: false
    message: *initial_prompt
    routing:
      kind: spawn
  # Follow-ups in conversations this agent already holds.
  - events:
      - chat.message.mentioned
      - chat.message.direct
      - chat.message.subscribed
    connection: telegram-FractalWorks_bot
    where:
      $.chat.provider: telegram
      $.auto.authored: false
      $.auto.attributions:
        exists: true
    message: |
      {{message.author.userName}} replied in your Telegram conversation:

      {{message.text}}

      Channel: {{chat.channelId}}
      Thread: {{chat.threadId}}

      Reply in that thread with chat.send.
    routing:
      kind: deliver
      routeBy:
        kind: attributedSessions
      onUnmatched: drop
  # Reactions to the agent's own messages.
  - events:
      - chat.reaction.added
      - chat.reaction.removed
    connection: telegram-FractalWorks_bot
    where:
      $.chat.provider: telegram
      $.message.author.isMe: true
      $.reaction.user.isMe: false
    message: |
      A Telegram reaction was applied to one of your messages.

      Reaction: {{reaction.rawEmoji}} from {{reaction.user.userName}}
      Reacted-to message id: {{chat.messageId}}
    routing:
      kind: deliver
      routeBy:
        kind: attributedSessions
      onUnmatched: drop

Get Started

Concepts

Examples

Reference

Telegram Events

How Telegram connects

Event keys

Mentions

Payload

Template placeholders

Filters

Threads and routing

Example: a conversational agent on Telegram

See also

​How Telegram connects

​Event keys

​Mentions

​Payload

​Template placeholders

​Filters

​Threads and routing

​Example: a conversational agent on Telegram

​See also

How Telegram connects

Event keys

Mentions

Payload

Template placeholders

Filters

Threads and routing

Example: a conversational agent on Telegram

See also