Telegram | ElevenLabs Documentation

Resumen

Conecta tus agentes de IA de ElevenLabs con Telegram para responder a los mensajes enviados a tu bot. Esta integración permite a tus agentes recibir mensajes entrantes en chats privados y grupos, consultar información de los chats, enviar respuestas y reaccionar a mensajes a través de la API de bots de Telegram.

Capacidades

Capacidad	Compatible
Modo de retención cero (ZRM)	No compatible
Archivos adjuntos en activadores	No compatible — las fotos, archivos y otros elementos multimedia de los mensajes entrantes no se reenvían al agente
Archivos adjuntos en herramientas	No compatible — las herramientas solo funcionan con texto

Configuración

Crea un bot de Telegram

Abre Telegram e inicia una conversación con @BotFather. Envía /newbot y sigue las indicaciones para elegir un nombre y un nombre de usuario para tu bot. BotFather te responderá con un token de bot.

Conéctalo en ElevenLabs

En la configuración de la integración de ElevenLabs, haz clic en Connect y pega el token de bot de BotFather.

Activa el activador

Tras conectarlo, activa el activador Telegram Message y selecciona el agente que debe gestionar los mensajes entrantes. ElevenLabs registrará automáticamente un webhook en Telegram para que tu bot empiece a recibir mensajes.

Uso del bot en grupos

El bot no necesita ser administrador del grupo y no necesitas desactivar el modo de privacidad de Telegram. Con el modo de privacidad activado (la opción predeterminada), Telegram entrega los mensajes que se dirigen explícitamente al bot, que son precisamente los que escucha esta integración:

Menciones con @ al nombre de usuario del bot, por ejemplo, @my_bot what's the status?.
Respuestas a los propios mensajes del bot, incluidos los turnos de seguimiento dentro de la misma conversación.

Los mensajes que no se dirigen al bot se ignoran por diseño. El bot también ignora los mensajes de otros bots y no actúa sobre mensajes editados o eliminados.

Telegram aplica los cambios del modo de privacidad y del rol de administrador solo a los grupos a los que el bot se une después del cambio. Si anteriormente cambiaste el modo de privacidad en @BotFather o hiciste al bot administrador de un grupo para «arreglar» las menciones, elimina el bot del grupo y vuelve a añadirlo para que se aplique la nueva configuración; normalmente eso es lo que hace que las menciones empiecen a funcionar, no el rol de administrador en sí.

En los chats de grupos y supergrupos, la respuesta del agente se envía como respuesta citada al mensaje que activó la acción, por lo que permanece visualmente vinculada a la pregunta incluso cuando el chat tiene mucha actividad. En los chats privados 1:1, la respuesta citada se omite porque sería redundante.

Herramientas del agente

Cuando añades herramientas de Telegram a un agente, están disponibles las siguientes herramientas integradas:

Herramienta	Descripción
`telegram_get_chat`	Consulta metadatos del chat actual, como el tipo, título, nombre de usuario y descripción. El valor de `chat_id` está vinculado a la conversación actual y no se puede redirigir.
`telegram_send_message`	Envía un mensaje de texto al chat actual. `chat_id` está vinculado; el modelo controla `text` y el valor opcional `parse_mode` (`HTML`, `Markdown` o `MarkdownV2`).
`telegram_react_to_message`	Reacciona al mensaje que activó la acción con un único emoji del conjunto de reacciones permitidas para bots de Telegram; resulta útil cuando una confirmación breve (`👍`, `🎉`, `❤`) es más natural que una respuesta de texto. Tanto `chat_id` como `message_id` están vinculados al turno de origen. Establecer una nueva reacción sustituye cualquier reacción que el bot hubiera establecido previamente en el mismo mensaje.

Algunos chats restringen los emoji permitidos mediante la configuración Available reactions de Telegram. Si se rechaza una llamada de reacción, indica al agente que recurra a una respuesta de texto.

Variables dinámicas

Cuando un agente se ejecuta desde Telegram, las siguientes variables dinámicas están disponibles en prompts y herramientas:

Variable	Descripción
`integration__telegram_chat_id`	ID del chat de Telegram donde tiene lugar la conversación.
`integration__telegram_message_id`	`message_id` de Telegram del mensaje de usuario que activó el turno actual del agente.
`integration__telegram_connection_id`	ID de conexión de la integración de ElevenLabs.

Consulta variables dinámicas para saber cómo usarlas como referencia en prompts y llamadas a herramientas.