Afbeeldingen en documenten verwerken in ElevenAgents

Een bouwopzichter ziet een tekort aan materialen op een bouwplaats. Hij maakt er een foto van, stuurt die via WhatsApp naar de inkoopagent en bevestigt het afleveradres met zijn stem. De agent verwerkt de foto, stelt vast wat er ontbreekt en plaatst met spoed een bestelling, allemaal binnen één gesprek. Workflows voor ondernemingen bevatten regelmatig context die woorden alleen niet kunnen overbrengen. De informatie die nodig is om een verzoek af te handelen, kan worden ingevoerd als een foto van een beschadigd item of een pdf van een polis. Door die informatie rechtstreeks aan de agent door te geven, wordt het gesprek korter en de afhandeling sneller. Als een klant iets kan laten zien in plaats van beschrijven, kan de agent problemen sneller oplossen zonder te vragen van kanaal te wisselen. Rohlik, een van de grootste online supermarktplatforms van Europa, zet zijn agent in via telefoon, web, app en WhatsApp in zes talen en handelt 90% van de klantvragen automatisch af. Multimodale invoer breidt diezelfde afhandelingssnelheid uit naar momenten waarop een klant iets moet laten zien in plaats van vertellen. ElevenAgents behandelt bestanden als volwaardige invoer voor dezelfde agent die al spraak, WhatsApp, web en mobiel afhandelt. Bestanden bereiken het onderliggende model als native berichten, zodat één agent elk invoertype binnen één gespreksthread afhandelt. 

In dit artikel lees je wat multimodaliteit op het platform betekent, hoe bestanden van het apparaat van een klant in de context van het model terechtkomen, wat elk kanaal ondersteunt en hoe je context tussen sessies behoudt wanneer een klant terugkomt.

Kanalen en invoer 

ElevenAgents is gebouwd rond de kanalen die ondernemingen al gebruiken om klanten te bereiken: web- en mobiele applicaties, hun supportplatform, telefoon, sms, e-mail, WhatsApp en andere. De agentconfiguratie (prompt, model, tools, kennisbank en stem) wordt één keer gedefinieerd en gedeeld door alle kanalen. Per kanaal verschillen twee zaken: de transportlaag en de invoertypen die deze ondersteunt. Web- en mobiele applicaties maken verbinding via de insluitbare widget, een van de SDK's of de Agents WebSocket. Telefoniegesprekken maken verbinding via native Twilio, SIP-trunking of native websocketgebaseerde integraties. Sms maakt verbinding via de native Twilio-integratie. WhatsApp maakt verbinding door een WhatsApp Business-account te importeren en de integratie voor de agent in te schakelen. Eén agent kan tegelijkertijd via al deze transportlagen worden ingezet.

Bestandsinvoer (afbeeldingen en pdf's) wordt momenteel ondersteund op web, mobiel en WhatsApp. De invoerverwerking wordt bepaald door het type, niet door het kanaal: een foto en spraakbericht die in dezelfde WhatsApp-sessie binnenkomen, worden via volledig verschillende pijplijnen verwerkt voordat ze het model bereiken. Ongeacht kanaal of invoertype komen alle invoeritems samen in dezelfde voorverwerkingslaag voordat ze als native context aan het model worden doorgegeven, waar ze een van twee paden volgen.

Invoerrepresentatie: bestandsgebaseerd versus inline

Ongeacht het invoertype of kanaal normaliseert het platform alle invoer naar een van twee interne representaties voordat deze aan het model wordt doorgegeven. Die classificatie bepaalt hoe de invoer wordt gecodeerd in het contextvenster van het model en wat je integratie upstream moet afhandelen.

Bestandsgebaseerde invoer

Afbeeldingen en pdf's worden aan het model doorgegeven als native bestandsreferenties, niet als tekstsamenvattingen. Het platform slaat het bestand op, wijst er een file_id aan toe en koppelt die identifier aan de beurt van de gebruiker. Een model dat afbeeldingen of documenten kan verwerken, ontvangt het onbewerkte bestand in zijn contextvenster in plaats van een afgeleide representatie. De integratievereiste is eenvoudig: leg de file_id vast die het uploadendpoint terugstuurt en neem deze op in de message payload. Als het bericht zonder de file_id wordt verzonden, heeft het model geen referentie naar het bestand, ongeacht of de upload is geslaagd. Bestandsopslag is beperkt tot het gesprek. Dat betekent dat alles wat na de sessie moet blijven bestaan (het bestand zelf, geëxtraheerde velden of gestructureerde output) expliciet door je integratie moet worden afgehandeld. Hoe je dit doet, verschilt per kanaal en use case.

Inline

De tweede representatie is inline en omvat al het overige. Spraak en spraakberichten worden getranscribeerd. Getypte tekst, getranscribeerde spraak, WhatsApp-locatiepins en contactkaarten worden allemaal genormaliseerd naar platte tekst in het transcript voordat het model draait. Een locatiepin wordt coördinaten en een optioneel adres; een contact wordt een naam en telefoonnummer. Geen van deze wordt opgeslagen als bestand of levert een bestandsreferentie op. Deze invoeritems staan rechtstreeks in het transcript.

Waarom het onderscheid belangrijk is

De scheiding bepaalt waar je integratie-inspanning naartoe gaat. Het inlinepad vereist tijdens het gesprek niets van je: het platform normaliseert deze invoeritems naar tekst en ze staan rechtstreeks in het transcript. Het bestandsgebaseerde pad heeft een eigen integratieoppervlak. In plaats van bestandsinhoud naar tekst te converteren voordat het model draait, geeft de orchestrator het onbewerkte bestand rechtstreeks door aan het contextvenster van het model. Het model werkt met de structuur van het bestand in plaats van een afgeleide tekstrepresentatie of beschrijving, waardoor ruimtelijke relaties, visuele lay-out en documentopmaak behouden blijven die anders verloren zouden gaan. Met dat onderscheid in gedachten behandelt de rest van dit artikel de implementatie: hoe je de agent configureert, hoe bestanden door elk kanaal bewegen en hoe je context tussen sessies behoudt.

Multimodale invoer instellen 

Het inschakelen van multimodale invoer begint met dezelfde agentconfiguratie voor web, mobiel en WhatsApp. Daarna hangt het van het kanaal af hoe een bestand wordt geüpload en hoe je het achteraf ophaalt.

Bestandsinvoer inschakelen

Er moeten twee instellingen in de agentconfiguratie zijn ingesteld voordat bestandsinvoer werkt. Stel eerst conversation_config.conversation.file_input.enabled in op True, via de API bij het maken van de agent of onder Instellingen > Geavanceerde instellingen > Bestandsinvoer in het dashboard. Ten tweede moet de agent zijn geconfigureerd met een model dat afbeeldingen en documenten kan verwerken. De vlag alleen doet niets als het onderliggende model geen afbeeldings- of documentblokken kan verwerken; beide moeten zijn ingesteld voordat je test.

SDK en WebSocket

Bestandsinvoer op web of mobiel vereist een aangepaste chatclient die is gebouwd op de SDK of een onbewerkte Agents-websocketverbinding. De flow is identiek voor alle drie, en de volgorde is strikt vereist: het bestand moet worden geüpload voordat het bericht wordt verzonden, omdat de message payload verwijst naar de identifier die de upload terugstuurt.

Upload eerst het bestand:

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  

Bekijk de bestandsupload voor de volledige request en response:

Stuur vervolgens via de verbinding een bericht dat verwijst naar de geretourneerde file_id:

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

De SDK's bundelen de upload- en referentiestappen in één aanroep en handelen de bestandsidentifier intern af. Bekijk de multimodal_message-specificatie voor de volledige berichtindeling. Omdat je applicatie de upload uitvoert, heb je het bestand op dat moment al in handen. Als je het alleen voor het huidige gesprek nodig hebt, is uploaden en naar de identifier verwijzen voldoende. Als je het na de sessie wilt bewaren, kun je het het beste vanuit je applicatie opslaan op het moment van uploaden. Je kunt het ook achteraf ophalen via de post-call webhook, zoals behandeld in het gedeelte over context tussen sessies.

WhatsApp

Op WhatsApp speelt je applicatie geen rol bij de upload. Wanneer een klant een afbeelding, document of sticker verstuurt, gaat het bestand eerst naar de infrastructuur van Meta. Meta stelt ElevenLabs hiervan op de hoogte via de WhatsApp Business API-webhook, waarna ElevenLabs de inloggegevens van je gekoppelde WhatsApp Business-account gebruikt om het bestand server-naar-server te downloaden, een eigen kopie op te slaan en deze op dezelfde manier aan het gesprek te koppelen als bij een web- of SDK-upload. De agent ontvangt het als multimodale invoer en het transcript registreert een file_input-event.

Omdat je applicatie de upload nooit afhandelt, heeft deze het bestand nooit rechtstreeks in handen. Er is geen manier om het tijdens de upload vast te leggen, zoals op web en mobiel. Het bestand bereikt je systeem via de file_url in de post-call webhook, die verwijst naar de opgeslagen kopie van ElevenLabs. De media-URL van Meta wordt alleen voor opname gebruikt en nooit extern beschikbaar gesteld. De ophaalmechanismen, waaronder tijdsbeperkingen voor downloaden, worden behandeld in het gedeelte over context tussen sessies.

Op WhatsApp stuurt de klant het bestand in de chat. ElevenLabs haalt het op bij Meta, slaat het op en koppelt de file_id aan de kant van het platform. Dit betekent dat er geen client-side uploadstap is. Anders dan op web en mobiel roept je applicatie geen POST /v1/convai/conversations/{id}/files aan en verstuurt deze geen multimodal_message via WebSocket. ElevenLabs verzorgt de bezorging, opslag en de beurt van de agent.

Context tussen sessies behouden

ElevenAgents verwerkt elk gesprek onafhankelijk. Niets wat een klant verstuurt, en niets wat de agent tijdens een gesprek afhandelt, wordt automatisch meegenomen naar het volgende gesprek. De agent geeft je systeem alles uit een afgerond gesprek via de post-call webhook, maar het geheugen dat gesprekken overspant, bevindt zich buiten de grenzen van ElevenLabs. Jij bent verantwoordelijk voor de continuïteit.

Het is de moeite waard om bewust rond die architecturale grens te ontwerpen. De gesprekken waarin multimodale invoer het belangrijkst is (een klant die een beschadigd item fotografeert, een polisdocument uploadt of een locatie deelt) worden vaak niet binnen één sessie afgehandeld. Een klant die een foto van een kapot onderdeel stuurt en een terugbelafspraak maakt, verwacht dat de agent die foto onthoudt wanneer de klant terugbelt. Zonder expliciet contextbeheer begint de agent telkens vanaf nul en moet de klant zich herhalen. Het patroon dat dit oplost, bestaat uit twee delen. Wanneer een gesprek eindigt, levert de post-call webhook het transcript, analyseresultaten, alle gestructureerde velden voor gegevensverzameling die je hebt gedefinieerd en bestands-URL's voor alle bestanden die door de sessie zijn gegaan. Je backend slaat wat relevant is op bij een duurzame klantidentifier, zoals een telefoonnummer, gebruikers-ID of accountsleutel. Wanneer die klant terugkomt, injecteert je applicatie de opgeslagen context bij het begin van de sessie via dynamische variabelen, zodat de agent het gesprek begint met wat deze al weet. Specifiek voor bestandsgebaseerde invoer verwijst de bestands-URL in de webhook payload naar de opgeslagen kopie van ElevenLabs en is dit na het sluiten van het gesprek de enige ophaalmogelijkheid. De kopie van het platform is beperkt tot de sessie; als je het bestand nodig hebt in een toekomstig gesprek of in je eigen systemen, moet je het downloaden uit de webhook payload voordat dat venster sluit. Hoe snel je moet handelen, hangt af van het retentiebeleid, dat wordt behandeld in de referentiedocumentatie. De webhook voert status uit. Dynamische variabelen voeren deze weer in. Alles daartussenin is de verantwoordelijkheid van je systeem, en daar ligt het echte integratiewerk voor elke use case waarin klanten terugkomen, escaleren of een afhandeling halverwege voortzetten.

Context injecteren hangt af van het kanaal

Het injectiemechanisme verschilt per kanaal, maar het onderliggende patroon is consistent. Voor telefonie roept ElevenLabs je server aan voordat de oproep verbinding maakt, zodat je de beller op nummer kunt opzoeken en dynamische variabelen, zoals naam, order-ID of accountniveau, kunt terugsturen voordat de agent spreekt. Op WhatsApp wordt bij elk inkomend bericht een pre-message webhook geactiveerd, zodat je deze kunt verrijken met identiteits- en bedrijfscontext uit je systemen voordat de agent het verwerkt. Anders worden dezelfde velden doorgegeven in conversation_initiation_client_data wanneer de sessie wordt geopend. ElevenAgents voegt sessies van verschillende kanalen niet samen tot één thread. Een WhatsApp-gesprek en een webgesprek zijn afzonderlijke sessies, zelfs als ze dezelfde klant betreffen. Maar omdat de webhookoutput en injectie van dynamische variabelen identiek werken voor alle kanalen, kan één persistentielaag ze allemaal afhandelen. Bouw deze één keer en deze dekt elk kanaal waarop de agent draait. Contextinjectie verwerkt tekstvormige gegevens: namen, order-ID's, samenvattingen en gestructureerde velden. Bestanden zijn een afzonderlijk geval en vereisen een andere aanpak.

Bestanden meenemen

Bestanden zijn beperkt tot één gesprek en blijven niet automatisch bewaard. Wat je meeneemt, hangt ervan af of het volgende gesprek de informatie uit een bestand of het bestand zelf nodig heeft. In de meeste gevallen is alleen de informatie nodig. De agent interpreteert een geüpload bestand in de beurt waarin het binnenkomt, maar schrijft die interpretatie niet automatisch ergens duurzaam weg. De gestructureerde output komt uit de post-callgegevens: het transcript, de transcriptsamenvatting en alle velden met resultaten van gegevensverzameling die je definieert. Als een klant een foto van een gebarsten deurafdichting stuurt en een week later terugkomt om de claim op te volgen, heeft de agent de foto niet opnieuw nodig. De agent moet weten dat de claim een gebarsten deurafdichting betreft. Je haalt dat uit de post-callgegevens, slaat het op bij de klantidentifier en injecteert het als dynamische variabele wanneer de klant terugkomt. Een korte samenvatting of enkele gestructureerde velden is doorgaans voldoende.

Wanneer je wel het originele bestand nodig hebt, voor je eigen administratie, compliance of downstreamsystemen, is de post-call webhook de ophaalroute. Elk geüpload bestand verschijnt in het transcript als een file_input-event met een ondertekende bestands-URL. Die URL is vijftien minuten geldig, dus download en sla het bestand op zodra de webhook binnenkomt in plaats van dit uit te stellen. Als je dat venster mist terwijl het gesprek nog bestaat, geeft de GET conversation API als terugvaloptie nieuwe URL's uit. Houd er rekening mee dat file_input in sommige gevallen, zoals de modus zonder retentie, kan ontbreken, in plaats van aan te nemen dat elke bestandsgebaseerde beurt een URL bevat.

Dit omvat de volledige levenscyclus: een bestand komt de sessie binnen, het model werkt er native mee, gestructureerde output verlaat de sessie via de webhook en je persistentielaag bepaalt wat de agent de volgende keer weet.

Conclusie

Dezelfde agentconfiguratie accepteert afbeeldingen en pdf's via web, mobiel en WhatsApp, zonder een aparte build per kanaal. Bestanden worden genormaliseerd, gekoppeld aan de beurt en als native blokken aan het model doorgegeven in plaats van als tekstsamenvattingen, zodat de ruimtelijke lay-out, visuele structuur en documentopmaak intact bij het model aankomen. Context tussen sessies volgt op elk kanaal hetzelfde patroon: de post-call webhook voert status uit en dynamische variabelen voeren deze weer in.

Bouw je met ElevenLabs Agents en wil je dat je agent naast spraak en tekst ook met afbeeldingen en documenten werkt, schakel dan multimodale invoer in en laat ons weten wat je ervan vindt.