Procesar imágenes y documentos en ElevenAgents

El encargado de una obra detecta que faltan materiales. Les hace una foto, la envía por WhatsApp al agente de compras y confirma por voz la dirección de entrega. 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 introducirse 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 lugar 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, 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 amplía esa misma tasa de resolución a los casos en los que un cliente necesita mostrar algo, no contarlo. 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 en 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 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 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 puede desplegarse simultáneamente en todos estos transportes.

Actualmente, las entradas de archivos (imágenes y PDF) son compatibles con la 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 canales de procesamiento 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 enviarse al modelo como contexto nativo, donde siguen una de dos rutas.

Representación de entradas: basadas en archivos 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 basadas en archivos

Las imágenes y los PDF se pasan al modelo como referencias nativas a archivos, 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 procesamiento de 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 completado correctamente. El almacenamiento de archivos está limitado al ámbito de la conversación. Esto significa que todo lo que deba conservarse más allá de la sesión —el propio archivo, los 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, la voz transcrita, las ubicaciones enviadas por 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 esta 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 basada en archivos tiene una superficie de integración distinta. En lugar de convertir el contenido del archivo en texto antes de ejecutar el modelo, el orquestador pasa el archivo sin procesar directamente a la ventana de contexto del modelo. El modelo trabaja sobre la estructura del archivo, en lugar de una representación o descripción de texto derivada, y 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 de la publicación 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 

Activar 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 aplicarse dos ajustes en la configuración del 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. Segundo, el agente debe configurarse con un modelo que admita visión y documentos. El indicador por sí solo no hace nada si el modelo subyacente no puede procesar bloques de imagen o documento; ambos deben estar configurados 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 un requisito estricto: el archivo debe cargarse antes de enviar el mensaje, ya que 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:

A continuación, 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 única llamada y gestionan internamente el identificador del archivo. Consulta la especificación de multimodal_message para ver el formato completo del mensaje. Como tu aplicación realiza la carga, ya dispone del 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 cargarlo. También puedes recuperarlo después mediante el webhook posterior a la llamada, explicado 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 notifica a ElevenLabs a través del webhook de la API de WhatsApp Business, y ElevenLabs utiliza las credenciales de tu cuenta conectada de WhatsApp Business para descargar el archivo de servidor a servidor, almacenar su propia copia y adjuntarlo 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, nunca tiene el archivo directamente. No existe una vía para capturarlo en el momento de la carga como ocurre en web y móvil. El archivo llega a tu sistema mediante el campo 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 ingestión y nunca se expone externamente. La mecánica de recuperación, incluidas las restricciones de tiempo de 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 en el cliente. A diferencia de la 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 se encarga de 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 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 teniendo en cuenta este límite arquitectónico. Las conversaciones en las que la entrada multimodal es más importante —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 resuelve esto 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 de cliente persistente, 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 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 basadas en archivos, 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 tras el cierre de 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 desde la carga útil del webhook antes de que se cierre ese periodo. La rapidez con la que debes actuar depende de la política de retención, explicada en la documentación de referencia. El webhook saca el estado; las variables dinámicas lo vuelven a introducir. Todo lo que hay entre ambos es responsabilidad de tu sistema, y ahí se concentra el verdadero trabajo de integración en cualquier caso de uso en que clientes vuelvan, escalen una incidencia o retomen 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 permite buscar al interlocutor 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 información de identidad y contexto empresarial de tus sistemas antes de que el agente lo procese. En otros casos, se pasan los mismos campos en conversation_initiation_client_data al abrirse la sesión. ElevenAgents no combina las sesiones de distintos 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, dado que 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 los gestiona todos. Créala una vez y cubrirá todos los canales en los que se ejecute el agente. La inyección de contexto gestiona datos con formato de texto: nombres, ID de pedido, resúmenes y campos estructurados. Los archivos son un caso distinto y requieren otro enfoque.

Conservar los archivos para después

Los archivos se limitan 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 del archivo o el archivo en sí. En la mayoría de 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 persistente. 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 la junta agrietada de una puerta y vuelve una semana después para hacer seguimiento de la reclamación, el agente no necesita otra vez la foto. Necesita saber que la reclamación trata de 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 pierdes ese plazo mientras la conversación sigue existiendo, la API GET de conversación vuelve a emitir URL nuevas como alternativa. Debes prever que file_input no esté presente en algunos casos, como en el modo de retención cero, en lugar de asumir que cada turno basado en archivos 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 mediante el 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 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, de modo 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 vuelven a introducir.

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.