Telegram

Your agent answers as a Telegram bot. The bot is private: it only talks to people who joined with an invite link you generated.

Before you start

• A workspace role that can edit Agents (agents.edit). Registering the webhook and creating invite links need it too.
• A Telegram account, to create the bot
• A VirtuAI address reachable over public HTTPS. Telegram doesn’t deliver messages to anything else.

1. Create the bot

1. In Telegram, open a chat with @BotFather and send /newbot.

2. Choose a display name and a username. The username must end in bot, for example acme_support_bot.

3. Copy the token BotFather sends you. It looks like 1234567890:ABCdef....

2. Connect the bot to the agent

1. Open Agents and edit the agent.

2. In Channels, turn on Telegram. A Telegram Configuration card appears.

3. Fill in the card:

   Field	What to enter
   Bot Token	The token from BotFather. Required.
   Bot Username	The bot’s username, without @. Needed for invite links.
   Waiting Message	What the bot shows while the agent works. Default: ⏳ Working on your request...

4. Save the agent.

3. Register the webhook

Edit the agent again. In Telegram Configuration, under Webhook Registration, check the URL:

https://<your-virtuai-host>/telegram/webhook/<agent-id>

Then select Register Webhook. VirtuAI registers this URL with Telegram together with a secret it generates. Telegram sends that secret with every message, and VirtuAI ignores any request that doesn’t carry it. You never see or enter the secret.

Until you register the webhook, the card shows “Not registered with a secret yet — the bot ignores every message until you register the webhook.”

Caution

A bot can only send its messages to one address. Registering it on a second agent moves it there. To free the bot, select Unregister on the agent that has it.

You can select Register Webhook again at any time, for example after changing the Bot Token. Each registration replaces the secret.

4. Invite people

1. In Telegram Configuration, under Invite Link, select + Generate.

2. Copy the link and send it to one person. Each link works once and expires after 24 hours.

3. The person opens the link and taps Start in Telegram. The bot answers “✅ You’re all set! Send me a message to get started.”

Everyone who joined is listed under Authorized Users. Select Revoke to remove someone. Anyone who isn’t on the list gets “⛔ You’re not authorized. Ask your administrator for an invite link.”

Link a VirtuAI account (optional)

After someone joins, the bot also sends a link to “link your VirtuAI account”. Linking lets the agent use that person’s connected apps, such as Gmail, Google Drive or Calendar, when it answers them on Telegram. People who don’t need connected apps can skip it.

To link, the person opens the link within 1 hour, signs in to VirtuAI, and selects Link My Account. Only a member of the agent’s workspace can link: anyone else is told “Your account is not a member of the workspace this bot belongs to”.

Commands

Command	What it does
/new [title]	Starts a new conversation, with an optional title
/resume	Shows your recent conversations as buttons. Tap one to switch to it.
/status	Tells you whether the agent is working, and for how long
/cancel	Cancels the queued message. The current task finishes, but its answer isn’t sent.
/help	Lists the commands

To show these in Telegram’s command menu, send them to BotFather with /setcommands.

How messages behave

• Progress. The bot posts the waiting message, then shows the agent’s steps while it works. The answer follows when it’s done.
• Busy agent. If you write while the agent is working, the bot answers “✉️ Got it — I’ll respond once I finish your current request.” and handles your message next.
• Replies. When you reply to a message, its text is sent to the agent as context.
• Text only. The bot reads text messages. Photos, voice notes and files you send are ignored.
• Files from the agent. Files the agent creates are sent to you as Telegram documents.
• Long answers. Answers longer than Telegram’s 4,096-character limit arrive as several messages.
• Budgets. If the workspace has run out of budget, the bot replies with the budget message instead of an answer.

Troubleshooting

“Telegram requires a public HTTPS URL” : Your VirtuAI address isn’t reachable over public HTTPS. Telegram can’t deliver to it.

The bot doesn’t answer at all : Select Register Webhook again. Check that no other agent registered the same bot afterwards, and that the Bot Token is right. Messages sent before the webhook was registered are ignored.

“❌ Invalid or expired invite link” : The link was already used, is older than 24 hours, or belongs to another agent. Generate a new one.

Linking fails with “Invalid or expired link token” : The link is older than 1 hour or was already used. Ask for a new invite link and open it: the bot sends a new linking link after you join.

“Set the bot username above to generate invite links” : Fill in Bot Username and save the agent.