> ## Documentation Index
> Fetch the complete documentation index at: https://docs.auto.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Telegram Events

> Telegram events an agent trigger can listen on: group messages, bot mentions, direct messages, and reactions, with payload placeholders and filters.

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.

```yaml theme={null}
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.                                                                           |

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

## 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](/reference/events/slack) 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

```yaml theme={null}
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.

```yaml .auto/agents/assistant.yaml theme={null}
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
```

## See also

* [Slack events](/reference/events/slack) — the full shared chat payload reference
* [Triggers reference](/reference/triggers) — routing kinds and filter grammar
* [Connections and identities](/concepts/connections-and-identities) — setting up the Telegram manager bot and agent bot identities