Processamento de Imagens e Documentos no ElevenAgents

Um supervisor de obra identifica a falta de materiais no canteiro. Ele tira uma foto, envia a imagem para o 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, por si só, não conseguem transmitir. As informações necessárias para resolver uma solicitação podem ser fornecidas como uma foto de um item danificado ou um PDF de uma apólice. Enviar isso diretamente ao agente torna a conversa mais objetiva e acelera a resolução. Quando um cliente pode mostrar em vez de descrever, o agente soluciona o problema mais rápido sem pedir que ele mude de canal. Rohlik, uma das maiores plataformas de supermercado online da Europa, disponibiliza seu agente por telefone, web, app e WhatsApp, em seis idiomas, e resolve 90% das solicitações de clientes automaticamente. A entrada multimodal estende essa mesma taxa de resolução aos momentos em que o cliente precisa mostrar, não apenas explicar. 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, permitindo que um único agente lide com todos os tipos de entrada em uma única conversa. 

Este post aborda o que 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 é desenvolvido em torno dos canais que as empresas já usam para atender seus 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) é definida uma vez e compartilhada entre todos os canais. Dois aspectos variam de acordo com o canal: a camada de transporte e os tipos de entrada compatíveis. Aplicativos web e móveis se conectam pelo widget incorporável, por um dos SDKs ou pelo WebSocket do Agents. As conversas de telefonia se conectam pelo Twilio nativo, trunking SIP 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 em todos esses meios de transporte ao mesmo tempo.

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

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

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

Entradas baseadas em arquivo

Imagens e PDFs são enviados ao modelo como referências de arquivo nativas, e não como resumos em texto. A plataforma armazena o arquivo, atribui a ele um file_id e associa 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 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 bem-sucedido. O armazenamento de arquivos é limitado à conversa. Isso significa que qualquer item que precise persistir 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.

Embutida

A segunda representação é embutida e abrange tudo o mais. Voz e mensagens de voz são transcritas. Texto digitado, fala transcrita, pins de localização do WhatsApp e cartões de contato são todos normalizados para texto simples na transcrição antes de o modelo ser executado. Um pin de localização se torna coordenadas e um endereço opcional; um contato se torna um nome e um número de telefone. Nenhum desses itens é 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 será necessário concentrar seu esforço de integração. O caminho embutido 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 distinta. Em vez de converter o conteúdo do arquivo em texto antes de o modelo ser executado, o orquestrador envia o arquivo bruto diretamente para a janela de contexto do modelo. O modelo trabalha com a estrutura do arquivo, em vez de uma representação ou descrição de texto derivada, preservando relações espaciais, layout visual e formatação de documentos que, de outra forma, seriam perdidos. Com essa distinção em mente, 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 na web, em dispositivos móveis e no WhatsApp. A partir daí, a forma de enviar um arquivo e recuperá-lo depois depende do canal.

Ativando a entrada de arquivo

Duas configurações devem estar definidas no agente para que a entrada de arquivo funcione. Primeiro, defina conversation_config.conversation.file_input.enabled como True, pela API durante a 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 compatível com visão e documentos. A sinalização por si só não faz nada se o modelo subjacente não puder processar blocos de imagem ou documento; ambas as configurações precisam ser definidas 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 sequência é obrigatória: o arquivo precisa ser enviado antes da mensagem, pois o payload 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 conferir a solicitação e a resposta completas:

Em seguida, 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 e processam internamente o identificador do arquivo. Consulte a especificação de multimodal_message para ver o formato completo da mensagem. Como seu aplicativo realiza o upload, o arquivo já está em mãos nesse momento. Se você só precisa dele para a conversa atual, basta enviá-lo e fazer referência ao identificador. Se precisar preservá-lo além da sessão, a abordagem mais simples é armazená-lo no seu aplicativo durante o upload. Também é possível recuperá-lo depois pelo webhook pós-chamada, abordado na seção sobre contexto entre sessões.

WhatsApp

No WhatsApp, seu aplicativo 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, armazena sua própria cópia e a anexa à 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 seu aplicativo nunca processa o upload, ele nunca tem o arquivo diretamente. Não há como capturá-lo no momento do upload, como ocorre 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. Os mecanismos de recuperação, incluindo as restrições de prazo para download, são abordados 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 no lado da plataforma. Isso significa que não há uma etapa de upload no lado do cliente. Ao contrário da web e de dispositivos móveis, seu aplicativo não chama POST /v1/convai/conversations/{id}/files nem envia multimodal_message pelo WebSocket. A ElevenLabs processa a entrega, o armazenamento e o 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 abrange conversas fica fora dos limites da ElevenLabs. A responsabilidade pela continuidade é sua.

Vale a pena planejar deliberadamente em torno desse limite arquitetural. As conversas em que a entrada multimodal mais importa — quando um cliente fotografa um item danificado, envia um documento de apólice ou compartilha 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 ligar novamente. Sem um gerenciamento explícito de contexto, o agente começa do zero todas as vezes, e o cliente precisa repetir tudo. O padrão para resolver isso 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 de arquivos que passaram pela sessão. Seu backend armazena o que for relevante associado a um identificador durável do cliente, como um número de telefone, ID de usuário ou chave de conta. Quando esse cliente retorna, seu aplicativo injeta o contexto armazenado no início da sessão por meio de variáveis dinâmicas, para que o agente inicie a conversa com o que já sabe. Especificamente para entradas baseadas em arquivo, a URL do arquivo no payload do webhook aponta para a cópia armazenada pela ElevenLabs e é o único caminho de recuperação após o encerramento da conversa. 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 do payload do webhook antes que esse período termine. A rapidez com que você precisa agir depende da política de retenção, descrita na documentação de referência. O webhook leva o estado para fora. As variáveis dinâmicas o trazem de volta. Tudo entre esses dois pontos é responsabilidade do seu sistema, e é aí que está o verdadeiro trabalho de integração para qualquer caso de uso em que os clientes retornem, escalem ou retomem 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 chamada ser conectada, dando a você a oportunidade de buscar o número do chamador e retornar variáveis dinâmicas, como nome, ID do pedido ou nível da conta, antes de o agente falar. No WhatsApp, um webhook pré-mensagem é acionado a cada mensagem recebida, permitindo enriquecer a mensagem com informações de identidade e contexto de negócio dos seus sistemas antes que o agente a processe. Caso contrário, os mesmos campos são enviados em conversation_initiation_client_data quando a sessão é aberta. O ElevenAgents não mescla sessões de canais diferentes em uma única conversa. 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 cuida de todos eles. Crie-a uma vez, e ela abrangerá todos os canais em que o agente opera. A injeção de contexto lida com dados em formato de texto: nomes, IDs de pedido, resumos e campos estruturados. Arquivos são um caso separado e exigem uma abordagem diferente.

Transportando arquivos para a próxima sessão

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 do arquivo ou do próprio arquivo. Na maioria dos casos, basta levar as informações. O agente interpreta um arquivo enviado no turno em que ele chega, mas não registra 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 todos os campos de resultado de coleta de dados que você definir. Se um cliente enviar uma foto de uma vedação de porta rachada e voltar uma semana depois para acompanhar a solicitação, o agente não precisa da foto novamente. Ele precisa saber que a solicitação é sobre 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 retorna. Um resumo curto ou alguns campos estruturados geralmente são suficientes.

Quando você precisa do arquivo original, seja para seus próprios registros, conformidade ou sistemas posteriores, 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 de arquivo assinada. Essa URL é válida por quinze minutos, portanto baixe e armazene o arquivo quando o webhook chegar, em vez de deixar para depois. Se você perder esse período 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 presumir 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 nele 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, associados ao turno e enviados ao modelo como blocos nativos, em vez de resumos em texto, para que o layout espacial, a estrutura visual e a formatação do documento cheguem 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 de voz e texto, ative a entrada multimodal e conte para nós o que você acha.