Gestione di immagini e documenti in ElevenAgents

Un responsabile di cantiere nota una carenza di materiali. Scatta una foto, la invia all’agente acquisti su WhatsApp e conferma l’indirizzo di consegna a voce. L’agente elabora la foto, identifica cosa manca e ordina subito il materiale, tutto nella stessa conversazione. Nei workflow aziendali, il contesto spesso va oltre le parole. Le informazioni necessarie per risolvere una richiesta possono arrivare come foto di un oggetto danneggiato o come PDF di una polizza. Inviare questi file direttamente all’agente rende la conversazione più rapida e la risoluzione più veloce. Quando il cliente può mostrare invece di spiegare, l’agente trova la soluzione più in fretta senza chiedere di cambiare canale.Rohlik, una delle più grandi piattaforme di spesa online in Europa, gestisce il suo agente su telefono, web, app e WhatsApp in sei lingue e risolve automaticamente il 90% delle richieste dei clienti. L’input multimodale estende questo tasso di risoluzione anche ai casi in cui il cliente deve mostrare, non solo raccontare. ElevenAgents tratta i file come input di prima classe, sullo stesso agente che già gestisce voce, WhatsApp, web e mobile. I file arrivano al modello come messaggi nativi, così un unico agente gestisce ogni tipo di input all’interno della stessa conversazione.

In questo articolo vediamo cosa significa multimodalità sulla piattaforma, come i file passano dal dispositivo del cliente al contesto del modello, cosa supporta ogni canale e come mantenere il contesto tra una sessione e l’altra quando il cliente torna.

Canali e input

ElevenAgents è costruito attorno ai canali che le aziende già usano per raggiungere i clienti: applicazioni web e mobile, piattaforme di supporto, telefono, SMS, email, WhatsApp e altri ancora. La configurazione dell’agente (prompt, modello, strumenti, knowledge base e voce) si imposta una volta sola e si condivide su tutti i canali. Due aspetti cambiano a seconda del canale: il livello di trasporto e i tipi di input supportati. Le applicazioni web e mobile si collegano tramite il widget integrabile, uno degli SDK o l’Agents WebSocket. Le conversazioni telefoniche si collegano tramite Twilio nativo, SIP trunking o integrazioni native basate su websocket. Gli SMS passano tramite l’integrazione Twilio nativa. WhatsApp si collega importando un account WhatsApp Business e attivando l’integrazione sull’agente. Un singolo agente può essere attivo su tutti questi canali contemporaneamente.

Gli input file (immagini e PDF) sono attualmente supportati su web, mobile e WhatsApp. La gestione degli input è guidata dal tipo, non dal canale: una foto e una nota vocale ricevute nella stessa sessione WhatsApp seguono pipeline completamente diverse prima di arrivare al modello. Indipendentemente dal canale o dal tipo di input, tutti gli input convergono su uno stesso livello di pre-processing prima di essere passati al modello come contesto nativo, seguendo uno dei due percorsi possibili.

Rappresentazione degli input: file-backed vs. inline

A prescindere dal tipo di input o dal canale, la piattaforma normalizza ogni input in una delle due rappresentazioni interne prima di passarla al modello. Questa classificazione determina come l’input viene codificato nella finestra di contesto del modello e cosa deve gestire la tua integrazione a monte.

Input file-backed

Immagini e PDF vengono passati al modello come riferimenti a file nativi, non come riassunti testuali. La piattaforma memorizza il file, gli assegna un file_id e collega quell’identificativo al turno dell’utente. Un modello con capacità visive o documentali riceve il file grezzo nella sua finestra di contesto, non una rappresentazione derivata. Il requisito di integrazione è semplice: acquisisci il file_id restituito dall’endpoint di upload e includilo nel payload del messaggio. Se il messaggio viene inviato senza il file_id, il modello non ha alcun riferimento al file, anche se l’upload è andato a buon fine. L’archiviazione dei file è limitata alla conversazione. Quindi, tutto ciò che deve persistere oltre la sessione (il file stesso, i campi estratti o un output strutturato) deve essere gestito esplicitamente dalla tua integrazione. Il meccanismo varia in base al canale e al caso d’uso.

Inline

La seconda rappresentazione è inline e riguarda tutto il resto. Voce e note vocali vengono trascritte. Testo digitato, parlato trascritto, pin di posizione WhatsApp e schede contatto vengono tutti normalizzati in testo semplice nella trascrizione prima che il modello venga eseguito. Un pin di posizione diventa coordinate e, se presente, un indirizzo; un contatto diventa nome e numero di telefono. Nessuno di questi viene salvato come file o produce un riferimento a file. Questi input vivono direttamente nella trascrizione.

Perché questa distinzione è importante

La distinzione determina dove si concentra il lavoro di integrazione. Il percorso inline non richiede nulla durante la conversazione: la piattaforma normalizza questi input in testo e li inserisce direttamente nella trascrizione. Il percorso file-backed ha una superficie di integrazione distinta. Invece di convertire il contenuto del file in testo prima dell’elaborazione, l’orchestratore passa il file grezzo direttamente nella finestra di contesto del modello. Il modello lavora sulla struttura del file, non su una rappresentazione testuale derivata, preservando relazioni spaziali, layout visivo e formattazione che altrimenti andrebbero persi. Tenendo presente questa distinzione, il resto dell’articolo spiega come configurare l’agente, come i file si muovono su ogni canale e come mantenere il contesto tra le sessioni.

Configurazione dell’input multimodale

Per abilitare l’input multimodale, si parte dalla stessa configurazione dell’agente su web, mobile e WhatsApp. Da lì, la modalità di upload e recupero dei file dipende dal canale.

Abilitare l’input file

Prima che l’input file funzioni, servono due impostazioni nella configurazione dell’agente. Prima di tutto, imposta conversation_config.conversation.file_input.enabled su True, tramite API alla creazione dell’agente o da Impostazioni > Impostazioni avanzate > Input file nella dashboard. Poi, l’agente deve essere configurato con un modello che supporta immagini e documenti. Solo il flag non basta: se il modello non può elaborare immagini o documenti, non funzionerà; entrambi i requisiti devono essere soddisfatti prima di testare.

SDK e WebSocket

L’input file su web o mobile richiede un client chat personalizzato basato su SDK o una connessione Agents websocket raw. Il flusso è identico su tutti e tre e la sequenza è fondamentale: il file va caricato prima di inviare il messaggio, perché il payload del messaggio fa riferimento all’identificativo restituito dall’upload.

Carica prima il file:

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 documentazione upload file per la richiesta e la risposta complete:

Poi invia un messaggio sulla connessione che fa riferimento al file_id restituito:

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

Gli SDK astraggono i passaggi di upload e riferimento in una sola chiamata, gestendo internamente l’identificativo del file. Consulta la specifica multimodal_message per il formato completo del messaggio. Poiché l’upload lo esegue la tua applicazione, il file è già disponibile in quel momento. Se ti serve solo per la conversazione attuale, basta caricarlo e fare riferimento all’identificativo. Se invece deve persistere oltre la sessione, il modo più semplice è salvarlo dalla tua applicazione al momento dell’upload. Puoi anche recuperarlo dopo tramite il webhook post-call, descritto nella sezione sul contesto tra sessioni.

WhatsApp

Su WhatsApp, la tua applicazione non gestisce l’upload. Quando un cliente invia un’immagine, un documento o uno sticker, il file arriva prima all’infrastruttura di Meta. Meta notifica ElevenLabs tramite il webhook WhatsApp Business API, ed ElevenLabs usa le credenziali del tuo account WhatsApp Business collegato per scaricare il file server-to-server, ne salva una copia e lo collega alla conversazione come avviene per upload web o SDK. L’agente lo riceve come input multimodale e la trascrizione registra un evento file_input.

Poiché la tua applicazione non gestisce mai l’upload, non ha mai il file direttamente. Non esiste una modalità di acquisizione al momento dell’upload come su web e mobile. Il file arriva al tuo sistema tramite il file_url nel webhook post-call, che punta alla copia salvata da ElevenLabs. L’URL media di Meta serve solo per l’ingestione e non viene mai esposto esternamente. Le modalità di recupero, inclusi i vincoli sui tempi di download, sono spiegate nella sezione sul contesto tra sessioni.

Su WhatsApp, il cliente invia il file in chat. ElevenLabs lo recupera da Meta, lo salva e collega il file_id lato piattaforma. Questo significa che non c’è una fase di upload lato client. Diversamente da web e mobile, la tua applicazione non chiama POST /v1/convai/conversations/{id}/files né invia multimodal_message via WebSocket. ElevenLabs gestisce consegna, archiviazione e turno dell’agente.

Mantenere il contesto tra le sessioni

ElevenAgents gestisce ogni conversazione in modo indipendente. Niente di ciò che il cliente invia, né ciò che l’agente risolve durante una conversazione, viene trasferito automaticamente alla successiva. L’agente invia al tuo sistema tutto ciò che riguarda la conversazione completata tramite il webhook post-call, ma la memoria che attraversa le conversazioni vive fuori da ElevenLabs. La continuità dipende da te.

Questo confine architetturale va progettato con attenzione. Le conversazioni in cui l’input multimodale è più importante (un cliente che fotografa un oggetto danneggiato, carica un documento, condivide una posizione) spesso non si risolvono in una sola sessione. Un cliente che invia la foto di un pezzo rotto e programma una richiamata si aspetta che l’agente ricordi la foto quando richiama. Senza una gestione esplicita del contesto, l’agente riparte da zero ogni volta e il cliente deve ripetersi. Il pattern che risolve questo problema ha due fasi. Quando una conversazione termina, il webhook post-call consegna la trascrizione, i risultati dell’analisi, eventuali campi di raccolta dati strutturati che hai definito e gli URL dei file passati nella sessione. Il tuo backend salva ciò che serve associandolo a un identificativo cliente durevole come numero di telefono, ID utente o chiave account. Quando il cliente torna, la tua applicazione inietta il contesto salvato all’avvio della sessione tramite variabili dinamiche, così l’agente inizia la conversazione già informato. Per gli input file-backed, l’URL del file nel payload del webhook punta alla copia salvata da ElevenLabs ed è l’unico modo per recuperarlo dopo la chiusura della conversazione. La copia della piattaforma è limitata alla sessione, quindi se ti serve il file in una conversazione futura o nei tuoi sistemi, devi scaricarlo dal payload del webhook prima che la finestra si chiuda. La rapidità richiesta dipende dalla retention policy, spiegata nella documentazione di riferimento. Il webhook porta fuori lo stato. Le variabili dinamiche lo riportano dentro. Tutto il resto è responsabilità del tuo sistema: qui si concentra il vero lavoro di integrazione per ogni caso in cui i clienti tornano, chiedono escalation o riprendono una richiesta in sospeso.

L’iniezione del contesto dipende dal canale

Il meccanismo di iniezione varia a seconda del canale, ma il pattern di base è sempre lo stesso. Per la telefonia, ElevenLabs chiama il tuo server prima che la chiamata venga collegata, dandoti la possibilità di identificare il chiamante tramite numero e restituire variabili dinamiche come nome, ID ordine o livello account prima che l’agente risponda. Su WhatsApp, un webhook pre-messaggio si attiva a ogni messaggio in ingresso, permettendoti di arricchirlo con identità e contesto aziendale dai tuoi sistemi prima che l’agente lo elabori. Negli altri casi, gli stessi campi vengono passati in conversation_initiation_client_data all’apertura della sessione. ElevenAgents non unisce le sessioni tra canali in un unico thread. Una conversazione WhatsApp e una web sono sessioni separate anche se coinvolgono lo stesso cliente. Ma poiché l’output del webhook e l’iniezione delle variabili dinamiche funzionano allo stesso modo su tutti i canali, un unico layer di persistenza li gestisce tutti. Costruiscilo una volta sola e copre ogni canale su cui gira l’agente. L’iniezione del contesto gestisce dati testuali: nomi, ID ordine, riassunti, campi strutturati. I file sono un caso a parte e richiedono una gestione diversa.

Gestire i file tra le sessioni

I file sono limitati a una conversazione e non vengono mantenuti automaticamente. Cosa portare avanti dipende se la conversazione successiva ha bisogno delle informazioni contenute nel file o del file stesso. Nella maggior parte dei casi, basta l’informazione. L’agente interpreta il file caricato nel turno in cui arriva, ma non salva automaticamente questa interpretazione in modo permanente. L’output strutturato arriva dai dati post-call: trascrizione, riassunto della trascrizione e campi raccolti che hai definito. Se un cliente invia la foto di una guarnizione rotta e torna dopo una settimana per seguire la pratica, l’agente non ha bisogno di nuovo della foto. Deve solo sapere che la pratica riguarda una guarnizione rotta. Tu estrai questa informazione dai dati post-call, la salvi associata all’identificativo cliente e la inietti come variabile dinamica quando il cliente torna. Di solito basta un breve riassunto o pochi campi strutturati.

Quando invece ti serve il file originale, per archiviazione, conformità o sistemi a valle, il webhook post-call è la via di recupero. Ogni file caricato appare nella trascrizione come evento file_input con un URL firmato. L’URL è valido per quindici minuti, quindi scarica e salva il file appena arriva il webhook, senza rimandare. Se perdi questa finestra mentre la conversazione è ancora attiva, la API GET conversation può generare nuovi URL come fallback. Prevedi che file_input possa mancare in alcuni casi, come in modalità zero-retention, invece di dare per scontato che ogni turno file-backed abbia sempre un URL.

Questo copre tutto il ciclo di vita: un file entra nella sessione, il modello lo elabora nativamente, l’output strutturato esce tramite webhook e il tuo layer di persistenza decide cosa l’agente saprà la volta successiva.

Conclusione

La stessa configurazione dell’agente accetta immagini e PDF su web, mobile e WhatsApp senza bisogno di una build separata per ogni canale. I file vengono normalizzati, collegati al turno e passati al modello come blocchi nativi, non come riassunti testuali, così layout, struttura visiva e formattazione arrivano intatti al modello. Il contesto tra sessioni segue lo stesso schema su ogni canale: il webhook post-call porta fuori lo stato, le variabili dinamiche lo riportano dentro.

Se stai sviluppando su ElevenLabs Agents e vuoi che il tuo agente lavori con immagini e documenti insieme a voce e testo, abilita l’input multimodale e facci sapere cosa ne pensi.