Procesar imágenes y documentos en ElevenAgents

Un supervisor de obra detecta que faltan materiales en una obra. Les 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 qué falta y realiza un pedido urgente, todo en una misma conversación. Los flujos de trabajo empresariales suelen incluir 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 agiliza la resolución. Cuando un cliente puede mostrar algo en vez de describirlo, el agente resuelve el problema más rápido sin pedirle que cambie de canal. Rohlik, una de las mayores plataformas de supermercados 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 los que un cliente necesita mostrar algo, no explicarlo. ElevenAgents trata los archivos como entradas principales 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 todo tipo de entradas en un mismo hilo de conversación. 

En este artículo explicamos 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 utilizan para contactar con 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 conocimientos y voz) se define una vez y se comparte en 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, SIP trunking 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 puede desplegarse simultáneamente en todos estos transportes.

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 flujos completamente distintos antes de llegar al modelo. Independientemente del canal o del tipo de entrada, todas convergen en la misma capa de preprocesamiento antes de pasarse al modelo como contexto nativo, donde siguen una de dos rutas.

Representación de las entradas: respaldadas por archivo 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 antes de ese punto.

Entradas respaldadas por archivo

Las imágenes y los PDF se pasan al modelo como referencias de archivo 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 tiene ninguna referencia al archivo, aunque la carga se haya realizado correctamente. El almacenamiento de archivos se limita a la conversación. Esto significa que tu integración debe gestionar explícitamente todo lo que deba conservarse después de la sesión —el propio archivo, campos extraídos o una salida estructurada—. 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 e incluye todo lo demás. La voz y las notas de voz se transcriben. El texto escrito, el habla transcrita, las ubicaciones compartidas en WhatsApp y las tarjetas de contacto se normalizan como texto sin formato en la transcripción antes de que se ejecute el modelo. Una ubicación se convierte en coordenadas y una dirección opcional; un contacto, en un nombre y un número de teléfono. Ninguna de estas entradas se almacena como archivo ni genera una referencia de archivo. Estas entradas se incluyen directamente en la transcripción.

Por qué importa la diferencia

Esta división determina dónde debes centrar el esfuerzo de integración. La ruta en línea no requiere nada por tu parte durante la conversación: la plataforma normaliza estas entradas como texto y se incluyen directamente en la transcripción. La ruta respaldada por archivo 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 opera sobre la estructura del archivo, no sobre una representación o descripción textual derivada, y así conserva las relaciones espaciales, la disposición visual y el formato del documento que, de otro modo, se perderían. Teniendo en cuenta esta diferencia, el resto del artículo aborda 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 la entrada multimodal 

La activación de la entrada multimodal comienza con la misma configuración de agente en web, móvil y WhatsApp. A partir de ahí, la forma de cargar un archivo y recuperarlo después depende del canal.

Activar la entrada de archivos

Antes de que funcione la entrada de archivos, deben configurarse dos opciones en el agente. Primero, establece conversation_config.conversation.file_input.enabled en True, ya sea mediante la API al crear el agente o en Configuración > Configuración avanzada > Entrada de archivos del panel de control. Segundo, el agente debe estar configurado con un modelo capaz de procesar imágenes y documentos. La opción por sí sola no sirve de nada si el modelo subyacente no puede procesar bloques de imágenes o documentos; debes configurar ambos antes de realizar pruebas.

SDK y WebSocket

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

Primero, carga 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 por la conexión un mensaje 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, la forma más sencilla 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 explicamos en la sección sobre el contexto entre sesiones.

WhatsApp

En WhatsApp, tu aplicación no interviene 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 avisa a ElevenLabs mediante el webhook de la API de WhatsApp Business, y ElevenLabs utiliza las credenciales de tu cuenta de WhatsApp Business conectada para descargar el archivo de servidor a servidor, almacenar su propia copia y adjuntarlo a la conversación igual que en una carga web o mediante 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 existe una 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 solo se utiliza para la ingestión y nunca se expone externamente. La mecánica de recuperación, incluidas las limitaciones de tiempo para la descarga, se explica 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 en la plataforma. Esto significa que no hay ningún paso de carga del 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 mediante 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, se traslada automáticamente a la siguiente. El agente entrega a tu sistema toda la información de 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 depende de ti.

Conviene diseñar deliberadamente en torno a este 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 única 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 lo resuelve tiene dos partes. Cuando termina 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 duradero del cliente, como un número de teléfono, un ID de usuario o una clave de cuenta. Cuando el cliente vuelve, tu aplicación inyecta el contexto almacenado al inicio de la sesión mediante variables dinámicas, para que el agente comience la conversación con lo que ya sabe. En concreto, para las entradas respaldadas por archivo, 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 se limita a la sesión, así que, si necesitas el archivo en una conversación futura o en tus propios sistemas, debes descargarlo desde la carga útil del webhook antes de que se cierre ese plazo. 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 ambos puntos es responsabilidad de tu sistema, y ahí es donde se concentra el verdadero trabajo de integración para cualquier caso de uso en el que los clientes vuelven, escalan una consulta 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. Para telefonía, ElevenLabs llama a tu servidor antes de que se conecte la llamada, lo que te permite buscar a quien llama por su número y devolver variables dinámicas como el nombre, el ID de 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 identidad y contexto empresarial de tus sistemas antes de que el agente lo procese. En otros casos, los mismos campos se pasan en conversation_initiation_client_data cuando se inicia la sesión. ElevenAgents no fusiona las sesiones de distintos canales en un único hilo. Una conversación de WhatsApp y una conversación web son sesiones independientes, aunque impliquen 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. Créala una vez y cubrirá todos los canales en los que funciona el agente. La inyección de contexto gestiona datos en formato de texto: nombres, ID de pedido, resúmenes y campos estructurados. Los archivos son un caso aparte y requieren un enfoque distinto.

Mantener los archivos para futuras sesiones

Los archivos se limitan a una conversación y no persisten automáticamente. Lo que debes conservar depende de si la siguiente conversación necesita la información del 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 resumen breve 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 dejarlo para más tarde. Si se te pasa ese plazo mientras la conversación sigue existiendo, la API GET de conversación vuelve a emitir URL nuevas como alternativa. Ten en cuenta que file_input puede no aparecer en algunos casos, como el modo de retención cero, en lugar de asumir que cada turno respaldado por archivo incluye una URL.

Esto abarca todo el ciclo de vida: un archivo entra en la sesión, el modelo opera sobre él de forma nativa, la salida estructurada sale mediante 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 PDF en web, móvil y WhatsApp sin necesidad de un desarrollo 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 además de voz y texto, activa la entrada multimodal y cuéntanos qué te parece.