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:
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:
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:
After deploying, set both variables in your host's environment and register the webhook. eve doesn't call setWebhook for you:
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.
- To require approval for a tool or ask the person a question, see Human-in-the-loop.
- To render prompts differently, override
events["interaction.opened"]. See Human-in-the-loop and Options.
Start conversations proactively
Start a session from a schedule or another channel with a chatId target. Add messageThreadId to post in a forum topic:
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:
Reference
The Telegram reference covers options, credentials, dispatch rules, model context, delivery, human-in-the-loop, proactive session anchoring, and attachments.