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 ao agente de compras pelo 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. Os fluxos de trabalho empresariais costumam envolver contextos que as palavras sozinhas não conseguem transmitir. As informações necessárias para resolver uma solicitação podem ser enviadas como uma foto de um item danificado ou o PDF de uma apólice. Enviar isso diretamente ao agente torna a conversa mais curta e acelera a resolução. Quando o cliente pode mostrar em vez de descrever, o agente resolve o problema mais rápido sem pedir que ele mude 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 estende essa mesma taxa de resolução aos momentos em que o cliente precisa mostrar, não explicar. O ElevenAgents trata arquivos como entradas de primeira classe no mesmo agente que já lida com voz, WhatsApp, web e dispositivos móveis. Os arquivos chegam ao modelo subjacente como mensagens nativas, para que um único agente lide com todos os tipos de entrada em uma única sequência de conversa. 

Este post explica o que a multimodalidade significa na plataforma, como os arquivos passam do dispositivo do cliente para o contexto do modelo, o que cada canal oferece e como manter o contexto entre sessões quando um cliente retorna.

Canais e entradas 

O ElevenAgents foi criado em torno dos canais que as empresas já usam para falar com os clientes: aplicações web e móveis, plataformas de suporte, telefone, SMS, e-mail, WhatsApp e outros. A configuração do agente (prompt, modelo, ferramentas, base de conhecimento e voz) é definida uma vez e compartilhada entre todos os canais. Dois aspectos variam por canal: a camada de transporte e os tipos de entrada compatíveis. Aplicações web e móveis se conectam pelo widget incorporável, por um dos SDKs ou pelo WebSocket do Agents. Conversas telefônicas se conectam pelo Twilio nativo, SIP trunking ou por integrações nativas baseadas em WebSocket. O SMS se conecta pela integração nativa com o Twilio. O WhatsApp se conecta ao importar uma conta do WhatsApp Business e ativar a integração no agente. Um único agente pode ser implantado simultaneamente em todos esses meios de transporte.

As entradas de arquivo (imagens e PDFs) são compatíveis atualmente com web, dispositivos móveis e WhatsApp. O processamento de entradas é orientado por tipo, não por canal: uma foto e uma mensagem de voz recebidas na mesma sessão do WhatsApp são processadas por pipelines totalmente diferentes antes de chegar ao modelo. Independentemente do canal ou tipo de entrada, todas convergem na mesma camada de pré-processamento antes de serem transmitidas ao modelo como contexto nativo, onde seguem um de dois caminhos.

Representação de entrada: baseada em arquivo ou em linha

Independentemente do tipo de entrada ou canal, a plataforma normaliza cada entrada em uma de duas representações internas antes de transmiti-la ao modelo. Essa classificação determina como a entrada é codificada na janela de contexto do modelo e o que sua integração precisa tratar antes disso.

Entradas baseadas em arquivo

Imagens e PDFs são transmitidos ao modelo como referências nativas a arquivos, não como resumos de texto. A plataforma armazena o arquivo, atribui a ele um file_id e vincula esse identificador ao turno do usuário. Um modelo compatível com visão ou documentos recebe o arquivo bruto em sua janela de contexto, em vez de uma representação derivada. O requisito de integração é simples: capture o file_id retornado pelo endpoint de upload e inclua-o na carga 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 concluído. O armazenamento de arquivos é limitado à conversa. Isso significa que tudo que precisar persistir após a sessão — o arquivo em si, campos extraídos ou uma saída estruturada — deverá ser tratado explicitamente pela sua integração. O mecanismo para isso varia conforme o canal e o caso de uso.

Em linha

A segunda representação é em linha e abrange todo o restante. Voz e mensagens de voz são transcritas. Texto digitado, fala transcrita, pinos de localização do WhatsApp e cartões de contato são normalizados como texto simples na transcrição antes de o modelo ser executado. Um pino de localização se torna coordenadas e, opcionalmente, um endereço; um contato se torna um nome e um número de telefone. Nenhum deles é armazenado como arquivo nem gera uma referência de arquivo. Essas entradas ficam diretamente na transcrição.

Por que essa distinção é importante

Essa divisão determina onde estará o esforço de integração. O caminho em linha não exige nada de você durante a conversa: a plataforma normaliza essas entradas em texto, e elas ficam diretamente na transcrição. O caminho baseado em arquivo tem uma superfície de integração própria. Em vez de converter o conteúdo do arquivo em texto antes de o modelo ser executado, o orquestrador transmite o arquivo bruto diretamente para a janela de contexto do modelo. O modelo opera sobre a estrutura do arquivo, e não sobre uma representação ou descrição textual derivada, preservando relações espaciais, layout visual e formatação do documento que, de outra forma, seriam perdidos. Considerando essa distinção, o restante deste post aborda a implementação: como configurar o agente, como os arquivos passam por cada canal e como manter o contexto entre sessões.

Configurando a entrada multimodal 

A ativação da entrada multimodal começa com a mesma configuração de agente em web, dispositivos móveis e WhatsApp. A partir daí, o modo como um arquivo é enviado e recuperado depois depende do canal.

Ativando a entrada de arquivo

Duas configurações precisam estar definidas no agente para que a entrada de arquivo funcione. Primeiro, defina conversation_config.conversation.file_input.enabled como True, seja pela API durante a criação do agente ou em Configurações > Configurações avançadas > Entrada de arquivo no dashboard. Segundo, o agente precisa estar configurado com um modelo compatível com visão e documentos. A flag sozinha não faz nada se o modelo subjacente não puder processar blocos de imagem ou documento; ambos devem estar configurados antes dos testes.

SDK e WebSocket

A entrada de arquivo na web ou em dispositivos móveis exige um cliente de chat personalizado criado com o SDK ou uma conexão WebSocket bruta do Agents. O fluxo é idêntico nos três casos, e a ordem é obrigatória: o arquivo precisa ser enviado antes da mensagem, pois a carga da mensagem faz referência ao identificador retornado pelo upload.

Primeiro, envie o arquivo:

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  

Consulte o upload de arquivo para ver a solicitação e a resposta completas:

Depois, envie pela conexão uma mensagem que faça referência ao file_id retornado:

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

Os SDKs reúnem as etapas de upload e referência em uma única chamada, lidando internamente com o identificador do arquivo. Consulte a სპეცificação de multimodal_message para ver o formato completo da mensagem. Como sua aplicação realiza o upload, o arquivo já está disponível nesse momento. Se você só precisa dele na conversa atual, basta enviá-lo e fazer referência ao identificador. Se precisar mantê-lo após a sessão, a abordagem mais simples é armazená-lo na sua aplicação no momento do upload. Ele também pode ser recuperado depois pelo webhook pós-chamada, abordado na seção sobre contexto entre sessões.

WhatsApp

No WhatsApp, sua aplicação não participa do upload. Quando um cliente envia uma imagem, documento ou figurinha, o arquivo vai primeiro para a infraestrutura da Meta. A Meta notifica a ElevenLabs pelo webhook da API do WhatsApp Business, e a ElevenLabs usa as credenciais da sua conta conectada do WhatsApp Business para baixar o arquivo de servidor para servidor, armazenar uma cópia própria e anexá-lo à conversa da mesma forma que em um upload pela web ou SDK. O agente o recebe como entrada multimodal, e a transcrição registra um evento file_input.

Como sua aplicação nunca processa o upload, ela não tem o arquivo diretamente. Não há como capturá-lo no momento do upload, como há na web e em dispositivos móveis. 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 apenas para ingestão e nunca é exposta externamente. A mecânica de recuperação, incluindo as limitações de tempo para download, é abordada na seção sobre contexto entre sessões.

No WhatsApp, o cliente envia o arquivo no chat. A ElevenLabs o recupera da Meta, armazena-o e anexa o file_id do lado da plataforma. Isso significa que não há uma etapa de upload no lado do cliente. Diferentemente da web e dos dispositivos móveis, sua aplicação não chama POST /v1/convai/conversations/{id}/files nem envia multimodal_message por WebSocket. A ElevenLabs cuida da entrega, do armazenamento e do turno do agente.

Mantendo o contexto entre sessões

O ElevenAgents processa cada conversa de forma independente. Nada que um cliente envia, nem nada que o agente resolve durante uma conversa, passa automaticamente para a próxima. O agente entrega ao seu sistema tudo de uma conversa concluída pelo webhook pós-chamada, mas a memória que se estende entre conversas fica fora dos limites da ElevenLabs. A continuidade é sua responsabilidade.

Vale projetar deliberadamente em torno desse limite arquitetural. As conversas em que a entrada multimodal mais importa — um cliente fotografando um item danificado, enviando um documento de apólice ou compartilhando uma localização — muitas vezes não são resolvidas em uma única sessão. Um cliente que envia a foto de uma peça quebrada e agenda um retorno espera que o agente se lembre da foto quando ele voltar a ligar. Sem um gerenciamento explícito de contexto, o agente começa do zero todas as vezes, e o cliente precisa se repetir. Esse padrão tem duas partes. Quando uma conversa termina, o webhook pós-chamada entrega a transcrição, os resultados da análise, todos os campos de coleta de dados estruturados que você definiu e URLs dos arquivos que passaram pela sessão. Seu backend armazena o que for relevante associado a um identificador durável do cliente, como número de telefone, ID de usuário ou chave da conta. Quando esse cliente retorna, sua aplicação injeta o contexto armazenado no início da sessão por meio de variáveis dinâmicas, para que o agente comece a conversa com o que já sabe. Especificamente para entradas baseadas em arquivo, a URL do arquivo na carga do webhook aponta para a cópia armazenada pela ElevenLabs e é a única forma de recuperação depois que a conversa é encerrada. A cópia da plataforma é limitada à sessão; portanto, se você precisar do arquivo em uma conversa futura ou nos seus próprios sistemas, deverá baixá-lo a partir da carga do webhook antes que essa janela se encerre. A rapidez com que você precisa agir depende da política de retenção, abordada na documentação de referência. O webhook leva o estado para fora. As variáveis dinâmicas o trazem de volta. Tudo o que acontece entre essas etapas é responsabilidade do seu sistema, e é aí que está o verdadeiro trabalho de integração para qualquer caso de uso em que os clientes retornam, escalam a solicitação ou retomam uma resolução em andamento.

A injeção de contexto depende do canal

O mecanismo de injeção varia conforme o canal, mas o padrão subjacente é consistente. Para telefonia, a ElevenLabs chama seu servidor antes de a ligação ser conectada, permitindo que você busque quem está ligando pelo número e retorne variáveis dinâmicas, como nome, ID do pedido ou nível da conta, antes de o agente falar. No WhatsApp, um webhook anterior à mensagem é acionado a cada mensagem recebida, permitindo enriquecê-la com identidade e contexto de negócio dos seus sistemas antes de o agente processá-la. Caso contrário, os mesmos campos são transmitidos em conversation_initiation_client_data quando a sessão é iniciada. O ElevenAgents não une sessões entre canais em uma única sequência. Uma conversa no WhatsApp e uma conversa na web são sessões separadas, mesmo que envolvam o mesmo cliente. Mas, como a saída do webhook e a injeção de variáveis dinâmicas funcionam de forma idêntica em todos os canais, uma única camada de persistência atende a todos eles. Crie-a uma vez, e ela abrangerá todos os canais em que o agente opera. A injeção de contexto trata dados em formato de texto: nomes, IDs de pedido, resumos e campos estruturados. Arquivos são um caso à parte e exigem uma abordagem diferente.

Mantendo arquivos para sessões futuras

Os arquivos são limitados a uma conversa e não persistem automaticamente. O que levar adiante depende de a próxima conversa precisar das informações de um arquivo ou do arquivo em si. Na maioria dos casos, ela precisa apenas das informações. O agente interpreta um arquivo enviado no turno em que ele chega, mas não grava automaticamente essa interpretação em nenhum lugar permanente. A saída estruturada vem dos dados pós-chamada: a transcrição, o resumo da transcrição e quaisquer campos de resultados de coleta de dados que você definir. Se um cliente enviar a foto de uma vedação de porta rachada e retornar uma semana depois para acompanhar a solicitação, o agente não precisará da foto novamente. Ele precisará saber que a solicitação diz respeito a uma vedação de porta rachada. Você extrai isso dos dados pós-chamada, armazena associado ao identificador do cliente e injeta como uma variável dinâmica quando ele retornar. Um breve resumo ou alguns campos estruturados normalmente são suficientes.

Quando você precisar do arquivo original, seja para seus próprios registros, conformidade ou sistemas posteriores, o webhook pós-chamada será o caminho de recuperação. Cada arquivo enviado aparece na transcrição como um evento file_input com uma URL de arquivo assinada. Essa URL é válida por quinze minutos, então baixe e armazene o arquivo quando o webhook chegar, em vez de deixar para depois. Se você perder essa janela enquanto a conversa ainda existir, a API GET de conversa emitirá novas URLs como alternativa. Planeje para que file_input esteja ausente em alguns casos, como no modo de retenção zero, em vez de pressupor que todo turno baseado em arquivo terá uma URL.

Isso abrange todo o ciclo de vida: um arquivo entra na sessão, o modelo opera sobre ele de forma nativa, 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, em dispositivos móveis e no WhatsApp, sem exigir uma implementação separada para cada canal. Os arquivos são normalizados, vinculados ao turno e transmitidos ao modelo como blocos nativos, e não como resumos de texto. Assim, o layout espacial, a estrutura visual e a formatação do documento chegam intactos ao modelo. O contexto entre sessões segue o mesmo padrão em todos os canais: o webhook pós-chamada leva o estado para fora, e as variáveis dinâmicas o trazem de volta.

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