Procesar imágenes y documentos en ElevenAgents

Un supervisor detecta que faltan materiales en una obra. Hace una foto, la envía al agente de compras por WhatsApp y confirma la dirección de entrega por voz. El agente procesa la foto, identifica lo que falta y hace un pedido urgente, todo en una sola conversación. Los flujos de trabajo empresariales suelen requerir contexto que no se puede transmitir solo con palabras. La información necesaria para resolver una solicitud puede llegar como una foto de un objeto dañado o un PDF de una póliza. Enviar eso directamente al agente agiliza la conversación y acelera la resolución. Cuando un cliente puede mostrar en vez de explicar, el agente resuelve más rápido sin pedirle que cambie de canal.Rohlik, una de las mayores plataformas de alimentación online de Europa, utiliza su agente en teléfono, web, app y WhatsApp en seis idiomas y resuelve automáticamente el 90% de las consultas de clientes. La entrada multimodal permite mantener ese mismo nivel de resolución incluso cuando el cliente necesita mostrar en vez de contar. ElevenAgents trata los archivos como entradas nativas en el mismo agente que ya gestiona voz, WhatsApp, web y móvil. Los archivos llegan al modelo como mensajes nativos, así que un solo agente gestiona todos los tipos de entrada en el mismo hilo de conversación.

En este artículo explicamos qué significa la multimodalidad en la plataforma, cómo se transfieren los archivos desde el dispositivo del cliente al contexto del modelo, qué soporta cada canal y cómo mantener el contexto entre sesiones cuando el cliente vuelve.

Canales y entradas

ElevenAgents está diseñado para los canales que las empresas ya usan para comunicarse con clientes: aplicaciones web y móviles, su plataforma de soporte, teléfono, SMS, email, WhatsApp y otros. La configuración del agente (prompt, modelo, herramientas, base de conocimiento y voz) se define una vez y se comparte en todos los canales. Solo varían dos cosas por canal: la capa de transporte y los tipos de entrada que soporta. Las aplicaciones web y móviles se conectan mediante el widget embebible, uno de los SDK o el WebSocket de Agents. Las conversaciones telefónicas se conectan mediante Twilio nativo, SIP trunking o integraciones nativas basadas en websocket. SMS se conecta 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 solo agente puede desplegarse en todos estos canales a la vez.

Las entradas de archivo (imágenes y PDFs) están disponibles actualmente en web, móvil y WhatsApp. El manejo de entradas es por tipo, no por canal: una foto y una nota de voz que llegan en la misma sesión de WhatsApp se procesan por rutas distintas antes de llegar al modelo. Independientemente del canal o tipo de entrada, todas convergen en la misma capa de preprocesado antes de pasar al modelo como contexto nativo, donde siguen uno de dos caminos.

Representación de la entrada: archivo vs. inline

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

Entradas basadas en archivo

Las imágenes y PDFs se pasan al modelo como referencias nativas de archivo, 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 con capacidad de visión o de documentos recibe el archivo original en su ventana de contexto, no una representación derivada. El requisito de integración es sencillo: captura el file_id que devuelve la ruta de subida y añádelo al mensaje. Si el mensaje se envía sin el file_id, el modelo no tiene referencia al archivo aunque la subida haya funcionado. El almacenamiento del archivo está vinculado a la conversación. Si necesitas que el archivo, los campos extraídos o una salida estructurada persistan más allá de la sesión, tu integración debe gestionarlo explícitamente. El mecanismo depende del canal y del caso de uso.

Inline

La segunda representación es inline y cubre todo lo demás. La voz y las notas de voz se transcriben. El texto escrito, el habla transcrita, las ubicaciones de WhatsApp y las tarjetas de contacto se normalizan a texto plano en la transcripción antes de que actúe el modelo. Una ubicación se convierte en coordenadas y una dirección opcional; un contacto se convierte en nombre y número de teléfono. Nada de esto se almacena como archivo ni genera una referencia de archivo. Estas entradas viven directamente en la transcripción.

Por qué importa la diferencia

La diferencia determina dónde tienes que trabajar la integración. El camino inline no requiere nada de tu parte durante la conversación: la plataforma normaliza estas entradas a texto y viven directamente en la transcripción. El camino basado en archivo tiene una integración distinta. En vez de convertir el contenido del archivo a texto antes de que actúe el modelo, el orquestador pasa el archivo original directamente a la ventana de contexto del modelo. El modelo trabaja sobre la estructura del archivo, no sobre una descripción o texto derivado, así que se mantienen relaciones espaciales, el formato visual y la maquetación del documento. Con esto en mente, el resto del artículo explica la implementación: cómo configurar el agente, cómo se mueven los archivos por cada canal y cómo mantener el contexto entre sesiones.

Configurar entrada multimodal

Para activar la entrada multimodal, empieza con la misma configuración de agente en web, móvil y WhatsApp. A partir de ahí, cómo se sube un archivo y cómo lo recuperas después depende del canal.

Activar entrada de archivos

Hay dos ajustes que debes activar en la configuración del agente antes de poder usar entrada de archivos. Primero, pon conversation_config.conversation.file_input.enabled en True, ya sea por API al crear el agente o en Ajustes > Ajustes avanzados > Entrada de archivos en el panel. Segundo, el agente debe estar configurado con un modelo que soporte visión y documentos. Solo activar la opción no sirve si el modelo no puede procesar imágenes o documentos; ambos deben estar configurados antes de probar.

SDK y WebSocket

La entrada de archivos en web o móvil requiere un cliente de chat personalizado construido sobre el SDK o una conexión directa por Agents WebSocket. El flujo es idéntico en los tres casos y el orden es obligatorio: el archivo debe subirse antes de enviar el mensaje, porque el mensaje hace referencia al identificador que devuelve la subida.

Primero sube 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 subida de archivos para ver la petición y respuesta completas:

Luego envía un mensaje por 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 SDKs simplifican la subida y la referencia en una sola llamada, gestionando el identificador internamente. Consulta la especificación de multimodal_message para ver el formato completo del mensaje. Como tu aplicación realiza la subida, ya tienes el archivo en ese momento. Si solo lo necesitas para la conversación actual, basta con subirlo y referenciar el identificador. Si necesitas conservarlo más allá de la sesión, lo más limpio es guardarlo desde tu aplicación al subirlo. También puedes recuperarlo después mediante el webhook post-call, explicado en la sección de contexto entre sesiones.

WhatsApp

En WhatsApp, tu aplicación no interviene en la subida. Cuando un cliente envía una imagen, documento o sticker, el archivo va primero a la infraestructura de Meta. Meta avisa a ElevenLabs mediante el webhook de la API de WhatsApp Business, y ElevenLabs usa las credenciales de tu cuenta conectada de WhatsApp Business para descargar el archivo de servidor a servidor, guarda su propia copia y la asocia a la conversación igual que en 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 subida, nunca tiene el archivo directamente. No hay una ruta de captura en el momento de la subida como en web y móvil. El archivo llega a tu sistema mediante el file_url en el webhook post-call, que apunta a la copia almacenada por ElevenLabs. La URL de medios de Meta solo se usa para la ingestión y nunca se expone externamente. Los detalles de recuperación, incluyendo las restricciones de tiempo para la descarga, se explican en la sección de contexto entre sesiones.

En WhatsApp, el cliente envía el archivo por chat. ElevenLabs lo recupera de Meta, lo almacena y asocia el file_id en la plataforma. Esto significa que no hay paso de subida en el lado del 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 por 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 el cliente ni de lo que resuelve el agente en una conversación pasa automáticamente a la siguiente. El agente entrega a tu sistema todo lo de una conversación completada mediante el webhook post-call, pero la memoria que conecta conversaciones está fuera de ElevenLabs. La continuidad depende de ti.

Ese límite arquitectónico merece la pena tenerlo en cuenta. Las conversaciones donde la entrada multimodal es más útil (un cliente que fotografía un objeto dañado, sube una póliza o comparte una ubicación) suelen no resolverse en una sola sesión. Un cliente que envía la foto de una pieza rota y pide que le llamen espera que el agente recuerde la foto cuando le devuelvan la llamada. Sin gestión explícita del contexto, el agente empieza de cero cada vez y el cliente tiene que repetirlo todo. La solución tiene dos partes. Cuando termina una conversación, el webhook post-call entrega la transcripción, los resultados del análisis, los campos de recogida de datos que hayas definido y las URLs de los archivos que hayan pasado por la sesión. Tu backend guarda lo relevante asociado a un identificador duradero del cliente, como el número de teléfono, el ID de usuario o la clave de cuenta. Cuando ese cliente vuelve, tu aplicación inyecta el contexto guardado al inicio de la sesión mediante variables dinámicas, así el agente empieza la conversación con lo que ya sabe. Para entradas basadas en archivo, la URL del archivo en el webhook apunta a la copia almacenada por ElevenLabs y es la única vía de recuperación tras cerrar la conversación. La copia de la plataforma está limitada a la sesión, así que si necesitas el archivo en una conversación futura o en tus propios sistemas, debes descargarlo del webhook antes de que caduque la ventana. La rapidez 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 devuelven. Todo lo intermedio es responsabilidad de tu sistema, y ahí está el trabajo real de integración en cualquier caso donde los clientes vuelven, escalan o retoman una resolución.

La inyección de contexto depende del canal

El mecanismo de inyección varía según el canal, pero el patrón es el mismo. En telefonía, ElevenLabs llama a tu servidor antes de conectar la llamada, dándote la oportunidad de buscar el número y devolver variables dinámicas como nombre, ID de pedido o nivel de cuenta antes de que hable el agente. En WhatsApp, un webhook previo al mensaje se activa en cada mensaje entrante, permitiéndote enriquecerlo con identidad y contexto de negocio desde tus sistemas antes de que lo procese el agente. En el resto de canales, los mismos campos se pasan en conversation_initiation_client_data al abrir la sesión. ElevenAgents no fusiona sesiones de distintos canales en un solo hilo. Una conversación en WhatsApp y una en web son sesiones separadas aunque sean del mismo cliente. Pero como la salida del webhook y la inyección de variables dinámicas funcionan igual en todos los canales, una sola capa de persistencia sirve para todos. Hazlo una vez y cubre todos los canales donde funcione el agente. La inyección de contexto gestiona datos en formato texto: nombres, IDs de pedido, resúmenes, campos estructurados. Los archivos son un caso aparte y requieren otro enfoque.

Cómo mantener archivos entre sesiones

Los archivos están vinculados a una conversación y no se conservan automáticamente. Qué mantener 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 se necesita la información. El agente interpreta el archivo subido en el turno en que llega, pero no guarda automáticamente esa interpretación en ningún sitio duradero. La salida estructurada viene de los datos post-call: la transcripción, el resumen y los campos de recogida de datos que definas. Si un cliente envía la foto de una junta de puerta rota y vuelve una semana después para seguir con la reclamación, el agente no necesita la foto otra vez. Solo necesita saber que la reclamación es por una junta de puerta rota. Extraes eso de los datos post-call, lo guardas con el identificador del cliente y lo inyectas como variable dinámica cuando vuelva. Un resumen breve o unos pocos campos estructurados suelen ser suficientes.

Si necesitas el archivo original, para tus registros, cumplimiento normativo o sistemas posteriores, el webhook post-call es la vía de recuperación. Cada archivo subido aparece en la transcripción como un evento file_input con una URL firmada. Esa URL es válida durante quince minutos, así que descarga y guarda el archivo cuando llegue el webhook, no lo dejes para después. Si pierdes esa ventana y la conversación sigue activa, la API GET conversation genera URLs nuevas como alternativa. Ten en cuenta que file_input puede no estar presente en algunos casos, como en modo sin retención, así que no asumas que siempre habrá una URL en cada turno con archivo.

Eso cubre todo el ciclo: un archivo entra en la sesión, el modelo lo procesa de forma nativa, la salida estructurada sale por el webhook y tu capa de persistencia decide qué sabe el agente la próxima vez.

Conclusión

La misma configuración de agente acepta imágenes y PDFs en web, móvil y WhatsApp sin necesidad de crear una integración distinta por canal. Los archivos se normalizan, se asocian al turno y se pasan al modelo como bloques nativos, no como resúmenes de texto, así que el formato visual, la estructura y la maquetación llegan intactos al modelo. El contexto entre sesiones sigue el mismo patrón en todos los canales: el webhook post-call saca el estado, las variables dinámicas lo devuelven.

Si estás creando sobre ElevenLabs Agents y quieres que tu agente trabaje con imágenes y documentos además de voz y texto, activa la entrada multimodal y cuéntanos tu experiencia.