Telegram Bot

The core private-message and reply loop is provider-validated. Group mentions, commands, reactions, and streaming are implemented in preview while their remaining provider validation is completed. Inbound media and Telegram voice transcription are supported independently of those preview features.

A Telegram Bot Distribution Ion connects one Telegram bot to an Ion Sequence. Private-chat messages, group messages, commands, replies, and reactions become shared A2A messaging events. Agent output returns to the same Telegram chat and topic by default. This distribution is for Telegram bots. It does not connect or operate as a person’s Telegram account.

Overview

The default Telegram Bot loop keeps platform behavior at the Distribution boundary:

Telegram sends a supported update to the connected bot.
The Distribution verifies and converts the update into a normalized A2A request.
The Sequence handles the request and returns a response.
The Distribution sends the response back into the same Telegram chat, topic, or reply chain.

This means the transport contract stays shared across distributions while the configuration layer remains platform-aware. For the lower-level contract, see Distribution and Event.

Default Request Loop

Configuration

Before you begin

You need:

an Aion organization and a Project containing a Telegram Bot Distribution Ion;
permission to add integrations to that organization; and
a Telegram account that can create a bot or supply an existing bot token.

Create an Aion-managed bot

This is the recommended setup path.

Open Integrations, select Telegram Bot, then add a Telegram Bot account.
Choose Create an Aion-Managed Bot.
Enter the bot display name and optional profile details, then select Continue.
Review and accept the ownership and management disclosures.
Select Open Telegram and confirm bot creation in the manager chat.
Return to Aion and wait for the Telegram Bot identity to become ready.

The Telegram user remains the bot owner. Aion receives management access needed to configure and operate that bot. Releasing the identity stops Aion routing, but it does not detach Aion’s manager relationship because Telegram does not provide that operation.

Connect your own bot

Use this path for a bot you created separately with @BotFather.

Create the bot in Telegram and copy its Bot API token.
Open Integrations, select Telegram Bot, then add a Telegram Bot account.
Choose Connect Your Own Bot and submit the token through the one-time credential form.
Wait for Aion to validate the bot and show the Telegram Bot identity as ready.

Treat the token as a secret. Aion does not display it again after submission.

Assign the bot to a Distribution

Connecting a bot does not automatically bind it to a Project or Distribution.

Open the Project in Composer.
Select the Telegram Bot Distribution Ion and open its Identity tab.
Select the connected bot under Telegram Bot.
To make this endpoint part of an Aion, select its Principal Identity.
Sync the Project changes.

Telegram Bot v1 has no Distribution-specific behavior fields. Telegram privacy mode, group administration, and bot settings still determine which updates Telegram sends. Aion-managed setup does not change those settings automatically.

Activate the Distribution

After selecting a ready Telegram Bot identity, turn on Activate distribution and sync the Project. Activation registers the bot’s webhook and enables message delivery when reconciliation succeeds.

Message Mapping

Telegram Bot distributions map inbound and outbound messages through the same shared transport contracts used by other messaging integrations, while still preserving Telegram-specific chat and reply context. Inbound

Protocol-level request metadata and event identity are defined by Distribution, Event, and Distribution/Messaging.
Framework-level request mapping is described in LangGraph Message Mapping and Google ADK Message Mapping.
Supported voice, audio, and document messages use the shared media and attachments model. Caption text, generated transcript text, the temporary Aion file, normalized event data, media state, and the source update remain separate ordered parts.

Outbound

Default response precedence is: SDK-managed response buffer first, explicit a2a_outbox second, and framework-native fallback third.
Structured outbound messages, reactions, and streaming deltas are defined by Distribution/Messaging.
Framework-level response mapping is described in LangGraph Message Mapping and Google ADK Message Mapping.

Features

Voice messages

Telegram’s provider-designated voice message is eligible for automatic transcription. A forwarded or bot-created voice message receives the same treatment when Telegram still represents it as voice. Ordinary audio and document attachments are not transcribed automatically. Aion directly supports Ogg/Opus, MP3, and M4A voice content for recorded speech-to-text. It does not transcode an unsupported format. The file still reaches the agent with transcription.status = "unsupported" and safeFailureCode = "audio_format_not_supported_for_transcription". Other terminal STT failures likewise preserve the file and use a safe failure code without provider diagnostics. A no-speech result does not dispatch an agent request because it has neither provider caption nor usable transcript. When both are present, the provider-authored caption is the first text part and the generated transcript is the second. Only the caption and its Telegram entities can select a command; generated transcript text cannot turn a voice message into a command. Framework adapters preserve every part instead of flattening caption and transcript provenance.

LangGraph
Google ADK
A2A

Inspect every part in runtime.context.inbox.message.parts. Ordinary graph state receives all text parts in order, while the inbox preserves the file and the mediaId metadata needed to associate the transcript.

Inspect every part in ctx.aion_runtime_context.inbox.message.parts. ADK content conversion does not replace the complete inbox, so agents can distinguish provider caption, generated transcript, and file content.

{
  "file": {
    "fileWithUri": "https://api.aion.to/files/019d0000-0000-7000-8000-000000000001/versions/019d0000-0000-7000-8000-000000000002/content?grant=example",
    "name": "voice-4002.ogg",
    "mediaType": "audio/ogg"
  },
  "metadata": {
    "https://docs.aion.to/a2a/extensions/aion/event/1.0.0": {
      "schema": "https://docs.aion.to/a2a/extensions/aion/distribution/messaging/1.0.0#MessageMediaPayload",
      "mediaId": "2b20168a-eb23-3ffd-a0aa-e4d730609349",
      "fileId": "019d0000-0000-7000-8000-000000000001",
      "fileVersionId": "019d0000-0000-7000-8000-000000000002",
      "kind": "voice-recording",
      "declaredMediaType": "audio/ogg",
      "byteSize": 4096,
      "durationMs": 2300,
      "availability": {
        "status": "available",
        "refreshable": true,
        "accessExpiresAt": "2026-08-29T19:00:00Z",
        "retentionExpiresAt": "2026-08-29T19:30:00Z"
      },
      "transcription": {
        "status": "completed",
        "language": "en"
      }
    }
  }
}

The file part’s MessageMediaPayload metadata carries fileId, the stable File Recording identifier, and fileVersionId, the exact immutable File Recordable identifier. Its URL and access and retention deadlines remain unchanged in task history. Supported Telegram media bytes are retained for one hour after materialization. The access grant may expire sooner; after byte retention ends, the historical URL returns 410 Gone without rewriting the task. Telegram’s standard hosted Bot API download limit is 20 MB. Aion does not apply a separate voice-duration limit, but download and STT work remain bounded by a size-aware processing deadline.

Attachments

Telegram audio and document messages receive normalized metadata and a temporary Aion file part. Aion downloads the content without exposing the bot token, validates bounded size and MIME/signature information, and streams the same ingress toward storage and any eligible STT consumer. Only voice is eligible for automatic transcription. The Aion file URL is authenticated and independent of Telegram’s credential-bearing download URL. Its one-hour byte retention and immutable task-history behavior match voice files. Outbound media delivery is not supported in this release; agent responses remain text, reactions, or supported structured messaging actions.

Mentions

Mentions in Telegram groups are treated as normal inbound message events. The framework sees text plus normalized transport context, and the response flows back into the same group context. Bot API 10.0 permits certain bot-authored messages in groups. Telegram Bot v1 intentionally ignores bot-authored input; bot-to-bot triggering is not supported.

LangGraph
Google ADK
A2A

from typing import Annotated, Optional, TypedDict
from langchain_core.messages import AIMessage, BaseMessage
from langgraph.graph import add_messages

from aion.shared.types import A2AInbox


class AgentState(TypedDict):
    messages: Annotated[list[BaseMessage], add_messages]
    a2a_inbox: Optional[A2AInbox]


def on_telegram_mention(state: AgentState) -> dict:
    inbound = state["messages"][-1]
    return {
        "messages": [
            AIMessage(content=f"Telegram mention received: {inbound.content}")
        ]
    }

The Distribution replies in the same Telegram chat and keeps the same reply context when one exists.

from google.adk.agents import BaseAgent
from google.adk.events import Event


class TelegramMentionAgent(BaseAgent):
    async def _run_async_impl(self, ctx):
        texts = [
            part.text
            for part in ctx.a2a_inbox.message.parts
            if getattr(part, "text", None)
        ]
        text = "\n".join(texts)
        yield Event(
            author=self.name,
            content={"parts": [{"text": f"Telegram mention received: {text}"}]},
        )

{
  "message": {
    "role": "ROLE_USER",
    "extensions": [
      "https://docs.aion.to/a2a/extensions/aion/distribution/1.0.0",
      "https://docs.aion.to/a2a/extensions/aion/event/1.0.0"
    ],
    "parts": [
      { "text": "@bot summarize the last three messages" },
      {
        "data": {
          "userId": "tg-user-42",
          "messageId": "4002",
          "contextId": "tg-chat-9988",
          "parentContextId": "3998",
          "trajectory": "conversation"
        },
        "mediaType": "application/json",
        "metadata": {
          "https://docs.aion.to/a2a/extensions/aion/event/1.0.0": {
            "schema": "https://docs.aion.to/a2a/extensions/aion/distribution/messaging/1.0.0#MessageEventPayload"
          }
        }
      },
      {
        "data": {
          "provider": "telegram",
          "event": {
            "update_id": 9001,
            "message": {
              "message_id": 4002,
              "chat": { "id": -9988, "type": "supergroup" },
              "from": { "id": 42, "username": "tg_user_42" },
              "text": "@bot summarize the last three messages"
            }
          }
        },
        "mediaType": "application/json",
        "metadata": {
          "https://docs.aion.to/a2a/extensions/aion/event/1.0.0": {
            "schema": "https://docs.aion.to/a2a/extensions/aion/distribution/messaging/1.0.0#SourceSystemEventPayload"
          }
        }
      }
    ],
    "metadata": {
      "https://docs.aion.to/a2a/extensions/aion/event/1.0.0": {
        "type": "to.aion.distribution.message.1.0.0",
        "source": "aion://distribution/telegram-dist-123",
        "id": "evt-telegram-mention-001"
      }
    }
  }
}

Commands

A leading Telegram bot_command entity is normalized as a command event. Commands may include an optional @botusername; the distribution accepts that form only when it names the connected bot. The raw argument tail and complete Telegram update remain available to the agent.

LangGraph
Google ADK
A2A

def on_telegram_command(state: AgentState) -> dict:
    inbound = state["messages"][-1]
    return {
        "messages": [
            AIMessage(content=f"Telegram command received: {inbound.content}")
        ]
    }

class TelegramCommandAgent(BaseAgent):
    async def _run_async_impl(self, ctx):
        texts = [
            part.text
            for part in ctx.a2a_inbox.message.parts
            if getattr(part, "text", None)
        ]
        text = "\n".join(texts)
        yield Event(
            author=self.name,
            content={"parts": [{"text": f"Telegram command received: {text}"}]},
        )

{
  "data": {
    "userId": "tg-user-42",
    "contextId": "tg-chat-9988",
    "command": "/summarize",
    "arguments": "last 20 messages"
  },
  "mediaType": "application/json",
  "metadata": {
    "https://docs.aion.to/a2a/extensions/aion/event/1.0.0": {
      "schema": "https://docs.aion.to/a2a/extensions/aion/distribution/messaging/1.0.0#CommandEventPayload"
    }
  }
}

Reactions

Telegram delivers actor-specific reaction changes as message_reaction updates. In groups and supergroups, the bot must be an administrator and the webhook must explicitly request message_reaction. Anonymous aggregate message_reaction_count updates do not identify an actor and are not normalized into Aion reaction events. Each added or removed reaction becomes ReactionEventPayload with the original Telegram update preserved alongside it.

LangGraph
Google ADK
A2A

def on_telegram_reaction(state: AgentState) -> dict:
    inbox = state.get("a2a_inbox")
    event_type = inbox.message.metadata[
        "https://docs.aion.to/a2a/extensions/aion/event/1.0.0"
    ]["type"]

    if event_type == "to.aion.distribution.reaction.1.0.0":
        return {"messages": [AIMessage(content="Reaction observed.")]}

    return {}

class TelegramReactionAgent(BaseAgent):
    async def _run_async_impl(self, ctx):
        yield Event(
            author=self.name,
            content={"parts": [{"text": "Reaction observed."}]},
        )

{
  "message": {
    "role": "ROLE_USER",
    "extensions": [
      "https://docs.aion.to/a2a/extensions/aion/distribution/messaging/1.0.0"
    ],
    "metadata": {
      "https://docs.aion.to/a2a/extensions/aion/event/1.0.0": {
        "type": "to.aion.distribution.reaction.1.0.0",
        "source": "aion://distribution/telegram-dist-123",
        "id": "evt-telegram-reaction-001"
      }
    },
    "parts": [
      {
        "data": {
          "userId": "tg-user-42",
          "contextId": "tg-chat-9988",
          "messageId": "4002",
          "reactionKey": "🔥",
          "displayValue": "🔥",
          "action": "added",
          "isCustom": false
        },
        "mediaType": "application/json",
        "metadata": {
          "https://docs.aion.to/a2a/extensions/aion/event/1.0.0": {
            "schema": "https://docs.aion.to/a2a/extensions/aion/distribution/messaging/1.0.0#ReactionEventPayload"
          }
        }
      },
      {
        "data": {
          "provider": "telegram",
          "event": {
            "update_id": 9002,
            "message_reaction": {
              "chat": { "id": -9988, "type": "supergroup" },
              "message_id": 4002,
              "user": { "id": 42, "username": "tg_user_42" },
              "old_reaction": [],
              "new_reaction": [{ "type": "emoji", "emoji": "🔥" }]
            }
          }
        },
        "mediaType": "application/json",
        "metadata": {
          "https://docs.aion.to/a2a/extensions/aion/event/1.0.0": {
            "schema": "https://docs.aion.to/a2a/extensions/aion/distribution/messaging/1.0.0#SourceSystemEventPayload"
          }
        }
      }
    ]
  }
}

Agents can add or remove one supported non-paid bot reaction by emitting a ReactionActionPayload through the reserved aion:reaction artifact. The distribution validates the current chat and message before calling Telegram.

Cards

Cards are not planned for the Telegram Bot distribution. It does not interpret Distribution/Cards, Telegram Rich Messages, inline keyboards, or callback-button actions. Agents return plain text for Telegram responses.

Streaming

Telegram preserves one target context for the full response. In an eligible private chat, the distribution can show coalesced partial text through Telegram message drafts before sending the final message. In groups and supergroups, it posts once and applies rate-limited text edits. The Telegram Bot distribution controls the typing chat action while it waits for provider-visible output. No downstream A2A typing event is required, and a working task status alone does not activate typing.

LangGraph
Google ADK
A2A

from langchain_core.messages import AIMessageChunk
from langgraph.types import StreamWriter
from aion.langgraph import emit_message


def stream_telegram_reply(state: AgentState, writer: StreamWriter):
    emit_message(writer, AIMessageChunk(content="Here"))
    emit_message(writer, AIMessageChunk(content=" is the first part "))
    emit_message(writer, AIMessageChunk(content="of the answer."))
    return state

class TelegramStreamingAgent(BaseAgent):
    async def _run_async_impl(self, ctx):
        yield Event(
            author=self.name,
            content={"parts": [{"text": "Here"}]},
            partial=True,
        )
        yield Event(
            author=self.name,
            content={"parts": [{"text": " is the first part "}]},
            partial=True,
        )
        yield Event(
            author=self.name,
            content={"parts": [{"text": "of the answer."}]},
        )

{
  "artifactUpdate": {
    "taskId": "task-telegram-stream-42",
    "contextId": "ctx-telegram-stream-42",
    "append": true,
    "lastChunk": false,
    "metadata": {
      "https://docs.aion.to/a2a/extensions/aion/distribution/messaging/1.0.0": {
        "schema": "https://docs.aion.to/a2a/extensions/aion/distribution/messaging/1.0.0#StreamDeltaPayload"
      }
    },
    "artifact": {
      "artifactId": "aion:stream-delta",
      "parts": [
        { "text": "Here is the first part " }
      ]
    }
  }
}

DMs

Telegram private chats are the cleanest default request loop. The inbound message maps to trajectory = "direct-message" and the default outbound response goes right back to that chat.

Telegram Bot limitation: A bot cannot start a new private conversation. The user must first start or message the bot. Aion can reply in that established private-chat context, but an agent cannot use an arbitrary Telegram user ID to open a new DM.

LangGraph
Google ADK
A2A

def on_telegram_dm(state: AgentState) -> dict:
    inbound = state["messages"][-1]
    return {
        "messages": [
            AIMessage(content=f"Telegram DM received: {inbound.content}")
        ]
    }

class TelegramDMAgent(BaseAgent):
    async def _run_async_impl(self, ctx):
        texts = [
            part.text
            for part in ctx.a2a_inbox.message.parts
            if getattr(part, "text", None)
        ]
        text = "\n".join(texts)
        yield Event(
            author=self.name,
            content={"parts": [{"text": f"Telegram DM received: {text}"}]},
        )

{
  "data": {
    "userId": "tg-user-42",
    "messageId": "4002",
    "contextId": "tg-private-chat-42",
    "parentContextId": null,
    "trajectory": "direct-message"
  }
}

Guides

Core Concepts

Ions

Resources

Distributions

Tools

Other

Overview

Default Request Loop

Configuration

Before you begin

Create an Aion-managed bot

Connect your own bot

Assign the bot to a Distribution

Activate the Distribution

Message Mapping

Features

Voice messages

Attachments

Mentions

Commands

Reactions

Cards

Streaming

DMs

​Overview

​Default Request Loop

​Configuration

​Before you begin

​Create an Aion-managed bot

​Connect your own bot

​Assign the bot to a Distribution

​Activate the Distribution

​Message Mapping

​Features

​Voice messages

​Attachments

​Mentions

​Commands

​Reactions

​Cards

​Streaming

​DMs

Overview

Default Request Loop

Configuration

Before you begin

Create an Aion-managed bot

Connect your own bot

Assign the bot to a Distribution

Activate the Distribution

Message Mapping

Features

Voice messages

Attachments

Mentions

Commands

Reactions

Cards

Streaming

DMs