Telegram

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 connects a bot you create with BotFather, through Vercel Connect or with self-managed credentials.

For information on all configuration and customization options, see the Telegram reference.

Set up

Open @BotFather in Telegram, send /newbot, and copy the token BotFather replies with. For an existing bot, send /token instead.

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

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:

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"),
});

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:

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:

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.
  • To change how replies are sent, see 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.

Start conversations proactively

Start a session from a schedule or another channel with a chatId target. Add messageThreadId to post in a forum topic:

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.

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:

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 covers options, credentials, dispatch rules, model context, delivery, human-in-the-loop, proactive session anchoring, and attachments.