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 sozinhas 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 o PDF de uma apólice. Enviar isso diretamente ao agente encurta a conversa e acelera a resolução. Quando um 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, usa 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 contar. O ElevenAgents trata arquivos como entradas de primeira classe no mesmo agente que já atende por 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 conversa. 

Este post explica o que multimodalidade significa na plataforma, como os arquivos saem do dispositivo de um cliente e entram no 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 com base nos canais que as empresas já usam para atender 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. Duas coisas variam conforme 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. Conversas telefônicas se conectam pelo Twilio nativo, trunking SIP ou integrações nativas baseadas em websocket. O SMS se conecta pela integração nativa com o Twilio. O WhatsApp se conecta importando uma conta do WhatsApp Business e ativando a integração no agente. Um único agente pode ser implantado em todos esses meios de transporte ao mesmo tempo.

As entradas de arquivo (imagens e PDFs) são compatíveis atualmente com web, dispositivos móveis e WhatsApp. O tratamento das entradas é orientado pelo tipo, não pelo 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 as entradas convergem para a mesma camada de pré-processamento antes de serem passadas ao modelo como contexto nativo, onde seguem um de dois caminhos.

Representação da entrada: baseada em arquivo vs. em linha

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 tratar antes disso.

Entradas baseadas em arquivo

Imagens e PDFs são passados 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 associa esse identificador à interação do usuário. Um modelo capaz de processar imagens ou documentos recebe o arquivo bruto em sua janela de contexto, em vez de uma representação derivada. O requisito da integração é simples: capture o file_id retornado pelo endpoint de upload e inclua-o na carga útil 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 tudo o que precisar persistir além da sessão — o próprio arquivo, 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 resto. Voz e mensagens de voz são transcritas. Texto digitado, fala transcrita, localizações compartilhadas no WhatsApp e cartões de contato são todos normalizados como texto simples na transcrição antes de o modelo ser executado. Uma localização compartilhada se torna coordenadas e um endereço opcional; um contato se torna um nome e um número de telefone. Nenhum deles é armazenado como arquivo ou gera uma referência de arquivo. Essas entradas ficam diretamente na transcrição.

Por que essa distinção importa

A divisão determina onde fica o esforço de integração. O caminho em linha não exige nada de você durante a conversa: a plataforma normaliza essas entradas como 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 passa 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 textual 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 para web, dispositivos móveis e WhatsApp. A partir daí, a forma como um arquivo é enviado e recuperado depois depende do canal.

Ativando a entrada de arquivos

Duas configurações devem estar presentes no agente para que a entrada de arquivos funcione. Primeiro, defina conversation_config.conversation.file_input.enabled como True, pela API ao criar o agente ou em Configurações > Configurações avançadas > Entrada de arquivo no dashboard. Segundo, o agente deve ser configurado com um modelo capaz de processar imagens e documentos. A sinalização sozinha não faz nada se o modelo subjacente não puder processar blocos de imagem ou documento; ambos devem ser definidos antes dos testes.

SDK e WebSocket

A entrada de arquivos 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 deve ser enviado antes da mensagem, porque a carga útil 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:

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 abstraem as etapas de upload e referência em uma única chamada, tratando 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, ele já tem o arquivo nesse momento. Se você só precisa dele na conversa atual, enviá-lo e referenciar o identificador é suficiente. Se precisar mantê-lo além da sessão, a abordagem mais simples é armazená-lo no seu aplicativo 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, 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 trata o upload, ele nunca tem o arquivo diretamente. Não há uma maneira de 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. Os mecanismos de recuperação, incluindo 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, o armazena e associa o file_id no 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, seu aplicativo não chama POST /v1/convai/conversations/{id}/files nem envia multimodal_message por WebSocket. A ElevenLabs cuida da entrega, do armazenamento e da interação 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, é levado 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 a pena 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, 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 ligar de volta. Sem um gerenciamento explícito de contexto, o agente começa do zero todas as vezes, e o cliente precisa se repetir. O padrão que resolve isso tem duas partes. Quando uma conversa termina, o webhook pós-chamada entrega a transcrição, os resultados da análise, quaisquer campos de coleta de dados estruturados que você tenha definido e URLs de arquivos que passaram pela sessão. Seu backend armazena o que for relevante associado a um identificador duradouro do cliente, como número de telefone, ID de usuário ou chave da 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 na carga útil 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, então, se você precisar do arquivo em uma conversa futura ou nos seus próprios sistemas, deverá baixá-lo da carga útil do webhook antes que essa janela se encerre. A rapidez com que você precisa agir depende da política de retenção, explicada 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 em qualquer caso de uso em que os clientes retornam, escalam uma 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. Na telefonia, a ElevenLabs chama seu servidor antes de a ligação ser conectada, dando a você a oportunidade de identificar quem está ligando pelo número 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 de pré-mensagem é acionado a cada mensagem recebida, permitindo enriquecer a mensagem com identidade e contexto comercial 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 é aberta. O ElevenAgents não une sessões de diferentes canais 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 trata de todos eles. Crie-a uma vez, e ela atenderá todos os canais em que o agente opera. A injeção de contexto trata dados em formato de texto: nomes, IDs de pedidos, resumos e campos estruturados. Arquivos são um caso separado e exigem uma abordagem diferente.

Mantendo arquivos entre sessões

Os arquivos são limitados a uma conversa e não persistem automaticamente. O que manter para a próxima conversa depende de ela precisar das informações de um arquivo ou do próprio arquivo. Na maioria dos casos, apenas as informações são necessárias. O agente interpreta um arquivo enviado na interação em que ele chega, mas não grava essa interpretação automaticamente em nenhum local persistente. A saída estruturada vem dos dados pós-chamada: a transcrição, o resumo da transcrição e quaisquer campos de resultados da 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 precisa saber que a solicitação envolve uma vedação de porta rachada. Você extrai essa informação dos dados pós-chamada, armazena-a associada ao identificador do cliente e a injeta como variável dinâmica quando ele retorna. Um resumo curto ou alguns campos estruturados normalmente são suficientes.

Quando você precisar do arquivo original, 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, então baixe e armazene o arquivo quando o webhook chegar, em vez de adiar. Se você perder essa janela enquanto a conversa ainda existir, a API GET de conversa reemite URLs novas como alternativa. Planeje-se para que file_input esteja ausente em alguns casos, como no modo de retenção zero, em vez de presumir que toda interação baseada 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 por canal. Os arquivos são normalizados, associados à interação e passados ao modelo como blocos nativos, em vez de resumos de texto, para que o layout espacial, a estrutura visual e a formatação dos documentos 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 com voz e texto, ative a entrada multimodal e conte para nós o que você achou.