Procesar imágenes y documentos en ElevenAgents

Un supervisor de obra detecta que faltan materiales en una obra. Hace una foto, la envía por WhatsApp al agente de compras y confirma la dirección de entrega por voz. El agente procesa la foto, identifica qué falta y realiza un pedido urgente, todo en una sola conversación. Los flujos de trabajo empresariales suelen incluir un contexto que las palabras por sí solas no pueden transmitir. La información necesaria para resolver una solicitud puede llegar como una foto de un artículo dañado o un PDF de una póliza. Enviarla directamente al agente acorta la conversación y acelera la resolución. Cuando un cliente puede mostrar en lugar de describir, el agente resuelve el problema más rápido sin pedirle que cambie de canal. Rohlik, una de las mayores plataformas de supermercado online de Europa, opera su agente por teléfono, web, app y WhatsApp en seis idiomas, y resuelve automáticamente el 90 % de las consultas de clientes. La entrada multimodal amplía esa misma tasa de resolución a los momentos en que un cliente necesita mostrar, no contar. ElevenAgents trata los archivos como entradas de primer nivel en el mismo agente que ya gestiona voz, WhatsApp, web y móvil. Los archivos llegan al modelo subyacente como mensajes nativos, por lo que un único agente gestiona todos los tipos de entrada dentro de un mismo hilo de conversación. 

Esta publicación explica qué significa la multimodalidad en la plataforma, cómo pasan los archivos del dispositivo de un cliente al contexto del modelo, qué admite cada canal y cómo mantener el contexto entre sesiones cuando un cliente vuelve.

Canales y entradas 

ElevenAgents se basa en los canales que las empresas ya usan para llegar a clientes: aplicaciones web y móviles, su plataforma de soporte, teléfono, SMS, correo electrónico, WhatsApp y otros. La configuración del agente (prompt, modelo, herramientas, base de conocimiento y voz) se define una vez y se comparte entre todos los canales. Hay dos elementos que varían según el canal: la capa de transporte y los tipos de entrada que admite. Las aplicaciones web y móviles se conectan mediante el widget integrable, uno de los SDK o el WebSocket de Agents. Las conversaciones telefónicas se conectan mediante Twilio nativo, trunking SIP o integraciones nativas basadas en WebSocket. Los SMS se conectan mediante la integración nativa de Twilio. WhatsApp se conecta importando una cuenta de WhatsApp Business y activando la integración en el agente. Un único agente se puede implementar en todos estos transportes a la vez.

Actualmente, las entradas de archivos (imágenes y PDF) son compatibles con web, móvil y WhatsApp. La gestión de entradas se basa en el tipo, no en el canal: una foto y una nota de voz que llegan en la misma sesión de WhatsApp se procesan mediante procesos completamente distintos antes de llegar al modelo. Independientemente del canal o del tipo de entrada, todas las entradas convergen en la misma capa de preprocesamiento antes de pasar al modelo como contexto nativo, donde siguen una de dos rutas.

Representación de entradas: con archivo asociado o en línea

Independientemente del tipo de entrada o del canal, la plataforma normaliza cada entrada en una de dos representaciones internas antes de pasarla al modelo. Esta clasificación determina cómo se codifica la entrada en la ventana de contexto del modelo y qué debe gestionar tu integración previamente.

Entradas con archivo asociado

Las imágenes y los PDF se pasan al modelo como referencias de archivos nativas, no como resúmenes de texto. La plataforma almacena el archivo, le asigna un file_id y vincula ese identificador al turno del usuario. Un modelo capaz de procesar imágenes o documentos recibe el archivo sin procesar en su ventana de contexto, en lugar de una representación derivada. El requisito de integración es sencillo: captura el file_id que devuelve la ruta de API de carga e inclúyelo en la carga útil del mensaje. Si el mensaje se envía sin el file_id, el modelo no tendrá ninguna referencia al archivo, aunque la carga se haya realizado correctamente. El almacenamiento de archivos está limitado a la conversación. Esto significa que todo lo que deba conservarse más allá de la sesión —el propio archivo, campos extraídos o una salida estructurada— debe gestionarse explícitamente mediante tu integración. El mecanismo para hacerlo varía según el canal y el caso de uso

En línea

La segunda representación es en línea y abarca todo lo demás. La voz y las notas de voz se transcriben. El texto escrito, el habla transcrita, los pines de ubicación de WhatsApp y las tarjetas de contacto se normalizan como texto sin formato en la transcripción antes de que se ejecute el modelo. Un pin de ubicación se convierte en coordenadas y una dirección opcional; un contacto se convierte en un nombre y un número de teléfono. Ninguno de ellos se almacena como archivo ni genera una referencia de archivo. Estas entradas se encuentran directamente en la transcripción.

Por qué es importante la distinción

La división determina dónde debes centrar el esfuerzo de integración. La ruta en línea no requiere nada de ti durante la conversación: la plataforma normaliza estas entradas como texto y se incluyen directamente en la transcripción. La ruta con archivo asociado tiene una superficie de integración distinta. En lugar de convertir el contenido del archivo en texto antes de que se ejecute el modelo, el orquestador pasa el archivo sin procesar directamente a la ventana de contexto del modelo. El modelo trabaja con la estructura del archivo, en lugar de con una representación o descripción de texto derivada, preservando las relaciones espaciales, la disposición visual y el formato del documento que, de otro modo, se perderían. Con esta distinción en mente, el resto de esta publicación explica la implementación: cómo configurar el agente, cómo se desplazan los archivos por cada canal y cómo mantener el contexto entre sesiones.

Configuración de entradas multimodales 

La activación de entradas multimodales empieza con la misma configuración del agente en web, móvil y WhatsApp. A partir de ahí, cómo se carga un archivo y cómo lo recuperas después depende del canal.

Activación de la entrada de archivos

Deben configurarse dos ajustes en el agente antes de que funcione la entrada de archivos. En primer lugar, establece conversation_config.conversation.file_input.enabled en True, ya sea a través de la API al crear el agente o en Configuración > Configuración avanzada > Entrada de archivos en el panel de control. En segundo lugar, el agente debe configurarse con un modelo capaz de procesar imágenes y documentos. El indicador por sí solo no hace nada si el modelo subyacente no puede procesar bloques de imagen o documento; ambos deben configurarse antes de realizar pruebas.

SDK y WebSocket

La entrada de archivos en web o móvil requiere un cliente de chat personalizado creado con el SDK o una conexión WebSocket de Agents sin procesar. El flujo es idéntico en los tres casos, y el orden es un requisito estricto: el archivo debe cargarse antes de enviar el mensaje, porque la carga útil del mensaje hace referencia al identificador que devuelve la carga.

Carga primero el archivo:

from elevenlabs import ElevenLabs

client = ElevenLabs(api_key="YOUR_API_KEY")

response = client.conversational_ai.conversations.files.create(
    conversation_id="your_conversation_id",
    file=open("example_file.jpg", "rb"),
)

file_id = response.file_id  

Consulta la carga de archivos para ver la solicitud y la respuesta completas:

Después, envía un mensaje a través de la conexión que haga referencia al file_id devuelto:

{ 
	"type": "multimodal_message",
	"text": { 
		"type": "user_message", 
		"text": "What does this show?" 
	 },
	"file": { 
		"type": "file_input", 
		"file_id": "<file_id>" 
 	}
}

Los SDK abstraen los pasos de carga y referencia en una sola llamada, y gestionan internamente el identificador de archivo. Consulta la especificación de multimodal_message para ver el formato completo del mensaje. Como tu aplicación realiza la carga, ya tiene el archivo en ese momento. Si solo lo necesitas para la conversación actual, basta con cargarlo y hacer referencia al identificador. Si necesitas conservarlo más allá de la sesión, lo más sencillo es almacenarlo desde tu aplicación en el momento de la carga. También puedes recuperarlo después mediante el webhook posterior a la llamada, que se explica en la sección sobre el contexto entre sesiones.

WhatsApp

En WhatsApp, tu aplicación no participa en la carga. Cuando un cliente envía una imagen, un documento o un sticker, el archivo llega primero a la infraestructura de Meta. Meta notifica a ElevenLabs a través del webhook de la API de WhatsApp Business, y ElevenLabs usa las credenciales de tu cuenta de WhatsApp Business conectada para descargar el archivo de servidor a servidor, almacena su propia copia y la adjunta a la conversación del mismo modo que en una carga desde web o SDK. El agente lo recibe como entrada multimodal y la transcripción registra un evento file_input.

Como tu aplicación nunca gestiona la carga, tampoco tiene el archivo directamente. No hay ninguna forma de capturarlo en el momento de la carga como ocurre en web y móvil. El archivo llega a tu sistema mediante la file_url del webhook posterior a la llamada, que apunta a la copia almacenada por ElevenLabs. La URL de contenido multimedia de Meta se utiliza únicamente para la ingesta y nunca se expone externamente. Los mecanismos de recuperación, incluidas las restricciones de tiempo de descarga, se explican en la sección sobre el contexto entre sesiones.

En WhatsApp, el cliente envía el archivo en el chat. ElevenLabs lo recupera de Meta, lo almacena y adjunta el file_id del lado de la plataforma. Esto significa que no hay ningún paso de carga en el cliente. A diferencia de web y móvil, tu aplicación no llama a POST /v1/convai/conversations/{id}/files ni envía multimodal_message a través de WebSocket. ElevenLabs gestiona la entrega, el almacenamiento y el turno del agente.

Mantener el contexto entre sesiones

ElevenAgents procesa cada conversación de forma independiente. Nada de lo que envía un cliente, ni nada de lo que resuelve el agente durante una conversación, pasa automáticamente a la siguiente. El agente entrega a tu sistema todo lo relativo a una conversación finalizada mediante el webhook posterior a la llamada, pero la memoria que abarca varias conversaciones reside fuera de los límites de ElevenLabs. La continuidad es responsabilidad tuya.

Conviene diseñar deliberadamente en torno a ese límite arquitectónico. Las conversaciones en las que más importa la entrada multimodal —un cliente que fotografía un artículo dañado, carga un documento de póliza o comparte una ubicación— a menudo no se resuelven en una sola sesión. Un cliente que envía una foto de una pieza rota y programa una devolución de llamada espera que el agente recuerde la foto cuando vuelva a llamar. Sin una gestión explícita del contexto, el agente empieza desde cero cada vez y el cliente tiene que repetirse. El patrón que resuelve esto tiene dos partes. Cuando finaliza una conversación, el webhook posterior a la llamada entrega la transcripción, los resultados del análisis, los campos de recopilación de datos estructurados que hayas definido y las URL de los archivos que hayan pasado por la sesión. Tu backend almacena lo relevante asociado a un identificador de cliente duradero, como un número de teléfono, un ID de usuario o una clave de cuenta. Cuando ese cliente vuelve, tu aplicación inyecta el contexto almacenado al iniciar la sesión mediante variables dinámicas, para que el agente empiece la conversación con lo que ya sabe. En el caso concreto de las entradas con archivo asociado, la URL del archivo en la carga útil del webhook apunta a la copia almacenada por ElevenLabs y es la única vía de recuperación después de que se cierre la conversación. La copia de la plataforma está limitada a la sesión, por lo que, si necesitas el archivo en una conversación futura o en tus propios sistemas, debes descargarlo de la carga útil del webhook antes de que se cierre esa ventana. La rapidez con la que debes actuar depende de la política de retención, que se explica en la documentación de referencia. El webhook saca el estado. Las variables dinámicas lo introducen de nuevo. Todo lo que hay entre medias es responsabilidad de tu sistema, y ahí es donde se concentra el verdadero trabajo de integración en cualquier caso de uso en el que los clientes vuelven, escalan o retoman una resolución a medias.

La inyección de contexto depende del canal

El mecanismo de inyección varía según el canal, pero el patrón subyacente es coherente. En telefonía, ElevenLabs llama a tu servidor antes de que se conecte la llamada, lo que te da la oportunidad de buscar a quien llama por su número y devolver variables dinámicas como el nombre, el ID del pedido o el nivel de cuenta antes de que hable el agente. En WhatsApp, se activa un webhook previo al mensaje con cada mensaje entrante, lo que te permite enriquecerlo con contexto de identidad y negocio de tus sistemas antes de que el agente lo procese. De lo contrario, los mismos campos se pasan en conversation_initiation_client_data al abrirse la sesión. ElevenAgents no fusiona las sesiones entre canales en un único hilo. Una conversación de WhatsApp y una conversación web son sesiones independientes aunque involucren al mismo cliente. Sin embargo, como la salida del webhook y la inyección de variables dinámicas funcionan de forma idéntica en todos los canales, una única capa de persistencia las gestiona todas. Constrúyela una vez y cubrirá todos los canales en los que opera el agente. La inyección de contexto gestiona datos con forma de texto: nombres, ID de pedidos, resúmenes y campos estructurados. Los archivos son un caso aparte y requieren un enfoque distinto.

Conservar archivos para futuras sesiones

Los archivos están limitados a una conversación y no se conservan automáticamente. Lo que debes conservar depende de si la siguiente conversación necesita la información de un archivo o el archivo en sí. En la mayoría de los casos, solo necesita la información. El agente interpreta un archivo cargado en el turno en que llega, pero no guarda automáticamente esa interpretación en ningún lugar duradero. La salida estructurada procede de los datos posteriores a la llamada: la transcripción, el resumen de la transcripción y los campos de resultados de recopilación de datos que definas. Si un cliente envía una foto de una junta de puerta agrietada y vuelve una semana después para hacer seguimiento de la reclamación, el agente no necesita la foto de nuevo. Necesita saber que la reclamación se refiere a una junta de puerta agrietada. Extraes esa información de los datos posteriores a la llamada, la almacenas asociada al identificador del cliente y la inyectas como variable dinámica cuando vuelva. Normalmente basta con un breve resumen o unos pocos campos estructurados.

Cuando sí necesitas el archivo original, para tus propios registros, cumplimiento normativo o sistemas posteriores, el webhook posterior a la llamada es la vía de recuperación. Cada archivo cargado aparece en la transcripción como un evento file_input con una URL de archivo firmada. Esa URL es válida durante quince minutos, así que descarga y almacena el archivo cuando llegue el webhook en lugar de posponerlo. Si pierdes esa ventana mientras la conversación sigue existiendo, la API GET de conversación vuelve a emitir URL nuevas como alternativa. Prevé que file_input no esté presente en algunos casos, como en el modo de retención cero, en lugar de asumir que cada turno con archivo asociado incluye una URL.

Esto cubre todo el ciclo de vida: un archivo entra en la sesión, el modelo trabaja con él de forma nativa, la salida estructurada sale a través del webhook y tu capa de persistencia decide qué sabrá el agente la próxima vez.

Conclusión

La misma configuración de agente acepta imágenes y PDF en web, móvil y WhatsApp sin necesidad de crear una implementación independiente para cada canal. Los archivos se normalizan, se vinculan al turno y se pasan al modelo como bloques nativos en lugar de resúmenes de texto, por lo que la disposición espacial, la estructura visual y el formato del documento llegan intactos al modelo. El contexto entre sesiones sigue el mismo patrón en todos los canales: el webhook posterior a la llamada saca el estado y las variables dinámicas lo introducen de nuevo.

Si estás desarrollando con ElevenLabs Agents y quieres que tu agente trabaje con imágenes y documentos junto con voz y texto, activa la entrada multimodal y cuéntanos qué te parece.