Processamento de Imagens e Documentos no ElevenAgents

Um supervisor de obra percebe a falta de materiais no canteiro. Ele tira uma foto, envia a imagem para o agente de compras no WhatsApp e confirma o endereço de entrega por voz. O agente processa a foto, identifica o que está faltando e faz um pedido urgente, tudo em uma única conversa. Fluxos de trabalho empresariais costumam envolver contextos que só palavras não transmitem. A informação necessária para resolver uma solicitação pode ser uma foto de um item danificado ou um PDF de uma política. Enviar isso diretamente para o agente torna a conversa mais objetiva e agiliza a resolução. Quando o cliente pode mostrar em vez de descrever, o agente resolve mais rápido sem pedir para trocar de canal.Rohlik, uma das maiores plataformas de supermercado online da Europa, opera seu agente por telefone, web, app e WhatsApp em seis idiomas e resolve automaticamente 90% das solicitações dos clientes. A entrada multimodal mantém esse índice mesmo quando o cliente precisa mostrar, não apenas contar. O ElevenAgents trata arquivos como entradas principais no mesmo agente que já atende voz, WhatsApp, web e app móvel. Os arquivos chegam ao modelo como mensagens nativas, então um único agente lida com todos os tipos de entrada em uma só conversa.

Este post explica o que é multimodalidade na plataforma, como os arquivos vão do dispositivo do cliente até o contexto do modelo, o que cada canal suporta e como manter o contexto entre sessões quando o cliente retorna.

Canais e Entradas

O ElevenAgents foi criado para os canais que as empresas já usam para falar com clientes: aplicativos web e móveis, plataforma de suporte, telefone, SMS, e-mail, WhatsApp e outros. A configuração do agente (prompt, modelo, ferramentas, base de conhecimento e voz) é feita uma vez e compartilhada em todos os canais. Dois pontos variam por canal: a camada de transporte e os tipos de entrada suportados. Aplicativos web e móveis conectam via widget incorporável, um dos SDKs ou o Agents WebSocket. Conversas por telefone conectam via Twilio nativo, SIP trunking ou integrações nativas baseadas em websocket. SMS conecta via integração nativa do Twilio. WhatsApp conecta importando uma conta WhatsApp Business e ativando a integração no agente. Um único agente pode ser usado em todos esses canais ao mesmo tempo.

Entradas de arquivo (imagens e PDFs) são suportadas atualmente na web, app móvel e WhatsApp. O processamento é feito por tipo de entrada, não por canal: uma foto e um áudio recebidos na mesma sessão do WhatsApp passam por fluxos diferentes antes de chegar ao modelo. Independentemente do canal ou tipo de entrada, tudo passa por uma camada de pré-processamento antes de ser enviado ao modelo como contexto nativo, seguindo um de dois caminhos.

Representação da entrada: arquivo vinculado vs. inline

Independente do tipo de entrada ou canal, a plataforma normaliza tudo em uma de duas representações internas antes de enviar ao modelo. Essa classificação define como a entrada é codificada na janela de contexto do modelo e o que sua integração precisa tratar antes.

Entradas vinculadas a arquivo

Imagens e PDFs são enviados ao modelo como referências nativas de arquivo, não como resumos em texto. A plataforma armazena o arquivo, atribui um file_id e vincula esse identificador ao turno do usuário. Um modelo com capacidade de visão ou documentos recebe o arquivo bruto no contexto, não uma representação derivada. O requisito de integração é simples: capture o file_id retornado pelo endpoint de upload e inclua no payload da mensagem. Se a mensagem for enviada sem o file_id, o modelo não terá referência ao arquivo, mesmo que o upload tenha sido feito. O armazenamento do arquivo é limitado à conversa. Ou seja, tudo que precisa durar além da sessão (o próprio arquivo, campos extraídos ou uma saída estruturada) deve ser tratado explicitamente pela sua integração. O mecanismo para isso varia conforme o canal e o caso de uso.

Inline

A segunda representação é inline e cobre todo o resto. Áudios e mensagens de voz são transcritos. Texto digitado, fala transcrita, localização e contatos do WhatsApp são normalizados para texto simples na transcrição antes do modelo rodar. Um pin de localização vira coordenadas e endereço opcional; um contato vira nome e telefone. Nada disso é armazenado como arquivo ou gera referência de arquivo. Essas entradas ficam direto na transcrição.

Por que essa distinção importa

A separação define onde está o esforço de integração. O caminho inline não exige nada de você durante a conversa: a plataforma normaliza para texto e já inclui na transcrição. O caminho de arquivo tem uma superfície de integração diferente. Em vez de converter o conteúdo do arquivo para texto antes do modelo, o orquestrador envia o arquivo bruto direto para o contexto do modelo. O modelo trabalha com a estrutura do arquivo, não com uma descrição em texto, preservando relações espaciais, layout visual e formatação que seriam perdidos. Com isso em mente, o restante do post mostra como configurar o agente, como os arquivos passam por cada canal e como manter o contexto entre sessões.

Configurando Entrada Multimodal

Habilitar entrada multimodal começa com a mesma configuração de agente para web, app móvel e WhatsApp. A partir daí, como o arquivo é enviado e recuperado depende do canal.

Habilitando entrada de arquivo

Duas configurações precisam estar ativas no agente para entrada de arquivo funcionar. Primeiro, defina conversation_config.conversation.file_input.enabled como True, via API na criação do agente ou em Configurações > Configurações Avançadas > Entrada de Arquivo no painel. Segundo, o agente precisa estar configurado com um modelo que aceite imagens e documentos. Só ativar a flag não basta se o modelo não processar imagens ou documentos; ambos precisam estar configurados antes de testar.

SDK e WebSocket

A entrada de arquivo na web ou app móvel exige um chat personalizado usando o SDK ou uma conexão direta via Agents WebSocket. O fluxo é igual nos três casos, e a ordem é obrigatória: o arquivo deve ser enviado antes da mensagem, pois o payload da mensagem referencia o identificador retornado pelo upload.

Envie o arquivo primeiro:

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  

Veja a documentação de upload de arquivo para o exemplo completo de requisição e resposta:

Depois, envie uma mensagem na conexão referenciando o file_id:

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

Os SDKs simplificam o upload e a referência em uma única chamada, tratando o identificador internamente. Veja a especificação multimodal_message para o formato completo da mensagem. Como sua aplicação faz o upload, o arquivo já está disponível nesse momento. Se só precisar dele para a conversa atual, basta enviar e referenciar o identificador. Se precisar manter além da sessão, o ideal é armazenar no momento do upload. Também é possível recuperar depois pelo webhook pós-chamada, explicado na seção de contexto entre sessões.

WhatsApp

No WhatsApp, sua aplicação não participa do upload. Quando o cliente envia uma imagem, documento ou figurinha, o arquivo vai primeiro para a infraestrutura da Meta. A Meta notifica a ElevenLabs via webhook da API WhatsApp Business, e a ElevenLabs usa as credenciais da sua conta WhatsApp Business conectada para baixar o arquivo de servidor para servidor, armazena uma cópia e anexa à conversa do mesmo jeito que no upload web ou SDK. O agente recebe como entrada multimodal e a transcrição registra um evento file_input.

Como sua aplicação não faz o upload, ela nunca tem acesso direto ao arquivo. Não existe um caminho para capturar o arquivo no momento do envio, como na web e no app. O arquivo chega ao seu sistema pelo file_url no webhook pós-chamada, que aponta para a cópia armazenada pela ElevenLabs. A URL de mídia da Meta é usada só para ingestão e nunca é exposta externamente. Detalhes sobre recuperação, incluindo restrições de tempo para download, estão na seção de contexto entre sessões.

No WhatsApp, o cliente envia o arquivo no chat. A ElevenLabs recupera da Meta, armazena e anexa o file_id do lado da plataforma. Ou seja, não há etapa de upload no lado do cliente. Diferente da web e do app, sua aplicação não chama POST /v1/convai/conversations/{id}/files nem envia multimodal_message via WebSocket. A ElevenLabs cuida da entrega, armazenamento e do turno do agente.

Mantendo contexto entre sessões

O ElevenAgents trata cada conversa de forma independente. Nada que o cliente envia, nem o que o agente resolve durante a conversa, é levado automaticamente para a próxima. O agente entrega tudo do atendimento finalizado via webhook pós-chamada, mas a memória entre conversas fica fora do ElevenLabs. A continuidade é responsabilidade sua.

Esse limite arquitetural merece atenção. As conversas onde a entrada multimodal mais importa (cliente fotografando item danificado, enviando documento, compartilhando localização) geralmente não se resolvem em uma sessão só. Um cliente que envia foto de uma peça quebrada e agenda retorno espera que o agente lembre da foto quando ligar de novo. Sem gestão explícita de contexto, o agente começa do zero e o cliente repete tudo. O padrão para resolver isso tem dois lados. Ao encerrar a conversa, o webhook pós-chamada entrega a transcrição, resultados de análise, campos de coleta de dados definidos e URLs dos arquivos que passaram pela sessão. Seu backend armazena o que for relevante vinculado a um identificador durável do cliente, como telefone, ID de usuário ou chave de conta. Quando o cliente retorna, sua aplicação injeta o contexto salvo no início da sessão via variáveis dinâmicas, para o agente começar já sabendo o que precisa. Para arquivos, a URL no payload do webhook aponta para a cópia da ElevenLabs e é o único caminho de recuperação após o fim da conversa. A cópia da plataforma é limitada à sessão, então se precisar do arquivo em outra conversa ou sistema, baixe do webhook antes que expire. A urgência depende da política de retenção, detalhada na documentação de referência. O webhook leva o estado para fora. Variáveis dinâmicas trazem de volta. Todo o resto é responsabilidade do seu sistema, e é aí que está o trabalho real de integração para casos em que o cliente retorna, escala ou continua uma resolução.

Como injetar contexto depende do canal

O mecanismo de injeção varia por canal, mas o padrão é o mesmo. Para telefonia, a ElevenLabs chama seu servidor antes da ligação conectar, permitindo buscar o número e retornar variáveis dinâmicas como nome, ID de pedido ou nível de conta antes do agente falar. No WhatsApp, um webhook pré-mensagem dispara a cada mensagem recebida, permitindo enriquecer com identidade e contexto de negócio dos seus sistemas antes do agente processar. Nos demais casos, os mesmos campos são enviados em conversation_initiation_client_data na abertura da sessão. O ElevenAgents não une sessões de canais diferentes em um só histórico. Uma conversa no WhatsApp e outra na web são sessões separadas, mesmo com o mesmo cliente. Mas como o webhook e a injeção de variáveis dinâmicas funcionam igual em todos os canais, uma camada de persistência cobre todos. Implemente uma vez e cobre todos os canais do agente. A injeção de contexto trata dados em formato texto: nomes, IDs de pedido, resumos, campos estruturados. Arquivos são um caso à parte e exigem outro tratamento.

Levando arquivos para frente

Arquivos ficam restritos a uma conversa e não persistem automaticamente. O que levar adiante depende se a próxima conversa precisa da informação do arquivo ou do arquivo em si. Na maioria dos casos, só a informação basta. O agente interpreta o arquivo enviado no turno em que chega, mas não grava automaticamente essa interpretação em lugar durável. A saída estruturada vem dos dados pós-chamada: transcrição, resumo e campos de coleta definidos. Se o cliente envia foto de uma vedação quebrada e volta uma semana depois para acompanhar o pedido, o agente não precisa da foto de novo. Ele precisa saber que o pedido é sobre a vedação quebrada. Você extrai isso dos dados pós-chamada, armazena vinculado ao cliente e injeta como variável dinâmica quando ele retorna. Um resumo curto ou alguns campos estruturados geralmente resolvem.

Quando precisar do arquivo original, para registro, compliance ou outros sistemas, o webhook pós-chamada é o caminho de recuperação. Cada arquivo enviado aparece na transcrição como um evento file_input com uma URL assinada. Essa URL vale por quinze minutos, então baixe e armazene o arquivo assim que o webhook chegar. Se perder esse prazo enquanto a conversa ainda existir, a API GET conversation gera novas URLs como alternativa. Planeje para o file_input não aparecer em alguns casos, como no modo de retenção zero, em vez de assumir que todo turno com arquivo terá URL.

Isso cobre todo o ciclo: o arquivo entra na sessão, o modelo processa nativamente, a saída estruturada sai pelo webhook e sua camada de persistência decide o que o agente saberá na próxima vez.

Conclusão

A mesma configuração de agente aceita imagens e PDFs na web, app móvel e WhatsApp, sem precisar de uma implementação separada por canal. Os arquivos são normalizados, vinculados ao turno e enviados ao modelo como blocos nativos, não como resumos em texto, preservando layout, estrutura visual e formatação. O contexto entre sessões segue o mesmo padrão em todos os canais: o webhook pós-chamada leva o estado para fora, variáveis dinâmicas trazem de volta.

Se você está construindo com ElevenLabs Agents e quer que seu agente trabalhe com imagens e documentos junto com voz e texto, ative a entrada multimodal e conte para a gente o que achou.