---
title: Telegram
description: Reach your agent from a Telegram bot in private chats, groups, and forum topics.
url: "https://eve.dev/docs/channels/telegram"
docs_index: /llms.txt
type: integration
---

> For an index of all documentation, see [/llms.txt](/llms.txt).

A Telegram agent answers every message in a private chat. In a group, it answers commands, `@mentions`, and replies to its own messages, and ignores the rest. Approvals and questions appear as inline-keyboard buttons. [Set up](#set-up) connects a bot you create with BotFather, through [Vercel Connect](https://vercel.com/docs/connect) or with self-managed credentials.

For information on all configuration and customization options, see the [Telegram reference](/docs/channels/telegram/reference).

## Set up

Open [@BotFather](https://t.me/BotFather) in Telegram, send `/newbot`, and copy the token BotFather replies with. For an existing bot, send `/token` instead.

#### Vercel Connect

Run the guided setup from your agent project, then deploy:

```bash
eve add channel/telegram
eve deploy
```

Setup links a Vercel project and stores the bot token in a Telegram connector. Connect registers the bot's webhook and forwards updates to `/eve/v1/telegram`, so your deployment holds no bot token or webhook secret. Setup writes the channel file:

```ts title="agent/channels/telegram.ts"
import { connectTelegramCredentials } from "@vercel/connect/eve";
import { telegramChannel } from "eve/channels/telegram";

export default telegramChannel({
  botUsername: "my_bot",
  credentials: connectTelegramCredentials("telegram/my-agent"),
});
```

#### Self-managed

Run `eve add channel/telegram` and choose **Use portable credentials**. eve writes `TELEGRAM_BOT_TOKEN` and a random `TELEGRAM_WEBHOOK_SECRET_TOKEN` to `.env.local`, and writes the channel file:

```ts title="agent/channels/telegram.ts"
import { telegramChannel } from "eve/channels/telegram";

export default telegramChannel({
  botUsername: "my_bot",
});
```

After deploying, set both variables in your host's environment and register the webhook. eve doesn't call `setWebhook` for you:

```bash
curl -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-app.example.com/eve/v1/telegram",
       "secret_token":"'"$TELEGRAM_WEBHOOK_SECRET_TOKEN"'",
       "allowed_updates":["message","callback_query"]}'
```

eve rejects any request whose `X-Telegram-Bot-Api-Secret-Token` header doesn't match `TELEGRAM_WEBHOOK_SECRET_TOKEN`.

## Default channel behavior

By default, the agent answers every message in a private chat. In a group, a message wakes the agent when it's a command directed at the bot (`/ask` or `/ask@my_bot`), mentions `@my_bot`, or replies to one of the agent's messages. Mentions need `botUsername`. Each forum topic is its own session. Group privacy mode is a BotFather setting, not a channel option.

- To customize which commands, mentions, or replies wake the agent, override `onMessage`. See [Dispatch](/docs/channels/telegram/reference#dispatch).
- To change how replies are sent, see [Delivery](/docs/channels/telegram/reference#delivery).

## Human-in-the-loop interactions

By default, tool approvals and option questions appear as inline-keyboard buttons. Freeform questions use a reply prompt, and the person's reply becomes the answer.

- To require approval for a tool or ask the person a question, see [Human-in-the-loop](/docs/human-in-the-loop).
- To render prompts differently, override `events["interaction.opened"]`. See [Human-in-the-loop](/docs/channels/telegram/reference#human-in-the-loop-hitl) and [Options](/docs/channels/telegram/reference#options).

## Start conversations proactively

Start a session from a [schedule](/docs/schedules#handler-form-run) or [another channel](/docs/channels/custom#cross-channel-hand-off) with a `chatId` target. Add `messageThreadId` to post in a forum topic:

```ts title="agent/schedules/daily-digest.ts"
import { defineSchedule } from "eve/schedules";
import telegram from "../channels/telegram";

export default defineSchedule({
  cron: "0 9 * * *",
  async run({ to, waitUntil, appAuth }) {
    waitUntil(
      to(telegram, { chatId: "123456789" }).send("Send today's digest.", { auth: appAuth }),
    );
  },
});
```

## Handle file attachments

Photos and documents people send reach the agent as files. To limit their types or size, see [Attachments](/docs/channels/telegram/reference#attachments).

## Restrict access

Return `{ auth }` from `onMessage` to start a turn, or `null` to ignore the message. A custom `onMessage` replaces the default group filter. This one answers only private chats with listed users:

```ts title="agent/channels/telegram.ts"
import { defaultTelegramAuth, telegramChannel } from "eve/channels/telegram";

const allowedUsers = new Set(["123456789"]);

export default telegramChannel({
  botUsername: "my_bot",
  onMessage(_ctx, message) {
    if (message.chat.type !== "private" || !allowedUsers.has(message.from?.id ?? "")) return null;
    return { auth: defaultTelegramAuth(message) };
  },
});
```

## Reference

The [Telegram reference](/docs/channels/telegram/reference) covers options, credentials, dispatch rules, model context, delivery, human-in-the-loop, proactive session anchoring, and attachments.

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)