Telegram

Tu agente responde como un bot de Telegram. El bot es privado: solo habla con las personas que se unieron con un vínculo de invitación que generaste.

Antes de comenzar

• Un rol del espacio de trabajo que pueda editar Agents (agents.edit). También se necesita para registrar el webhook y crear vínculos de invitación.
• Una cuenta de Telegram, para crear el bot
• Una dirección de VirtuAI accesible mediante HTTPS público. Telegram no entrega mensajes a ningún otro tipo de dirección.

1. Crea el bot

1. En Telegram, abre un chat con @BotFather y envía /newbot.

2. Elige un nombre visible y un nombre de usuario. El nombre de usuario debe terminar en bot, por ejemplo, acme_support_bot.

3. Copia el token que te envía BotFather. Tiene un formato como 1234567890:ABCdef....

2. Conecta el bot al agente

1. Abre Agents y edita el agente.

2. En Channels, activa Telegram. Aparece una tarjeta Telegram Configuration.

3. Completa la tarjeta:

   Campo	Qué ingresar
   Bot Token	El token de BotFather. Obligatorio.
   Bot Username	El nombre de usuario del bot, sin @. Es necesario para los vínculos de invitación.
   Waiting Message	Lo que muestra el bot mientras el agente trabaja. Valor predeterminado: ⏳ Working on your request...

4. Guarda el agente.

3. Registra el webhook

Vuelve a editar el agente. En Telegram Configuration, en Webhook Registration, verifica la URL:

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

Luego, selecciona Register Webhook. VirtuAI registra esta URL en Telegram junto con un secreto que genera. Telegram envía ese secreto con cada mensaje, y VirtuAI ignora cualquier solicitud que no lo incluya. Nunca ves ni ingresas el secreto.

Hasta que registres el webhook, la tarjeta muestra “Not registered with a secret yet — the bot ignores every message until you register the webhook.”

Precaución

Un bot solo puede enviar sus mensajes a una dirección. Si lo registras en un segundo agente, se traslada a ese agente. Para liberar el bot, selecciona Unregister en el agente que lo tiene.

Puedes volver a seleccionar Register Webhook en cualquier momento, por ejemplo, después de cambiar el Bot Token. Cada registro reemplaza el secreto.

4. Invita a personas

1. En Telegram Configuration, en Invite Link, selecciona + Generate.

2. Copia el vínculo y envíaselo a una persona. Cada vínculo funciona una sola vez y vence después de 24 horas.

3. La persona abre el vínculo y presiona Start en Telegram. El bot responde “✅ You’re all set! Send me a message to get started.”

Todas las personas que se unieron aparecen en Authorized Users. Selecciona Revoke para quitar a alguien. Cualquier persona que no esté en la lista recibe “⛔ You’re not authorized. Ask your administrator for an invite link.”

Vincula una cuenta de VirtuAI (opcional)

Después de que alguien se une, el bot también envía un vínculo para “link your VirtuAI account”. La vinculación permite que el agente use las apps conectadas de esa persona, como Gmail, Google Drive o Calendar, cuando le responde en Telegram. Quien no necesite apps conectadas puede omitirla.

Para vincular la cuenta, la persona abre el vínculo antes de que pase 1 hora, inicia sesión en VirtuAI y selecciona Link My Account. Solo un miembro del espacio de trabajo del agente puede vincular su cuenta: cualquier otra persona recibe “Your account is not a member of the workspace this bot belongs to”.

Comandos

Comando	Qué hace
/new [title]	Inicia una conversación nueva, con un título opcional
/resume	Muestra tus conversaciones recientes como botones. Presiona uno para cambiar a esa conversación.
/status	Te indica si el agente está trabajando y desde hace cuánto
/cancel	Cancela el mensaje en cola. La tarea actual termina, pero su respuesta no se envía.
/help	Muestra los comandos

Para mostrarlos en el menú de comandos de Telegram, envíaselos a BotFather con /setcommands.

Cómo se comportan los mensajes

• Progreso. El bot publica el mensaje de espera y, luego, muestra los pasos del agente mientras trabaja. La respuesta llega cuando termina.
• Agente ocupado. Si escribes mientras el agente está trabajando, el bot responde “✉️ Got it — I’ll respond once I finish your current request.” y procesa tu mensaje a continuación.
• Respuestas. Cuando respondes a un mensaje, su texto se envía al agente como contexto.
• Solo texto. El bot lee mensajes de texto. Las fotos, las notas de voz y los archivos que envías se ignoran.
• Archivos del agente. Los archivos que crea el agente se te envían como documentos de Telegram.
• Respuestas largas. Las respuestas que superan el límite de 4,096 caracteres de Telegram llegan como varios mensajes.
• Presupuestos. Si el espacio de trabajo agotó su presupuesto, el bot responde con el mensaje de presupuesto en lugar de una respuesta.

Solución de problemas

“Telegram requires a public HTTPS URL” : Tu dirección de VirtuAI no es accesible mediante HTTPS público. Telegram no puede entregar mensajes en ella.

El bot no responde nada : Vuelve a seleccionar Register Webhook. Verifica que ningún otro agente haya registrado el mismo bot después y que el Bot Token sea correcto. Los mensajes enviados antes de registrar el webhook se ignoran.

“❌ Invalid or expired invite link” : El vínculo ya se usó, tiene más de 24 horas o pertenece a otro agente. Genera uno nuevo.

La vinculación falla con “Invalid or expired link token” : El vínculo tiene más de 1 hora o ya se usó. Pide un vínculo de invitación nuevo y ábrelo: después de unirte, el bot envía un vínculo de vinculación nuevo.

“Set the bot username above to generate invite links” : Completa Bot Username y guarda el agente.