Bearbeta bilder och dokument i ElevenAgents

En arbetsledare upptäcker brist på material på en byggarbetsplats. Han fotograferar det, skickar bilden till inköpsagenten på WhatsApp och bekräftar leveransadressen med rösten. Agenten bearbetar fotot, identifierar vad som saknas och gör en expressbeställning – allt i samma konversation. Företags arbetsflöden innehåller ofta sammanhang som ord ensamma inte kan förmedla. Informationen som behövs för att lösa ett ärende kan komma in som ett foto av en skadad vara eller en PDF med en policy. Att skicka det direkt till agenten gör konversationen kortare och snabbar upp lösningen. När en kund kan visa i stället för att beskriva kan agenten felsöka snabbare utan att be kunden byta kanal. Rohlik, en av Europas största onlineplattformar för dagligvaror, använder sin agent via telefon, webb, app och WhatsApp på sex språk och löser 90 % av kundförfrågningarna automatiskt. Multimodal inmatning ger samma lösningsgrad även i situationer där kunden behöver visa i stället för att berätta. ElevenAgents behandlar filer som förstklassiga indata för samma agent som redan hanterar röst, WhatsApp, webb och mobil. Filer når den underliggande modellen som inbyggda meddelanden, så en enda agent kan hantera alla indatatyper i samma konversationstråd. 

I det här inlägget går vi igenom vad multimodalitet innebär på plattformen, hur filer går från kundens enhet till modellens kontext, vad varje kanal stöder och hur du kan behålla kontext mellan sessioner när en kund återkommer.

Kanaler och indata 

ElevenAgents bygger på de kanaler som företag redan använder för att nå kunder: webb- och mobilappar, supportplattformar, telefon, SMS, e-post, WhatsApp med mera. Agentkonfigurationen (prompt, modell, verktyg, kunskapsbas och röst) definieras en gång och delas mellan alla kanaler. Två saker varierar mellan kanalerna: transportlagret och de indatatyper som stöds. Webb- och mobilappar ansluter via den inbäddningsbara widgeten, någon av SDK:erna eller Agents WebSocket. Telefonsamtal ansluter via inbyggd Twilio, SIP-trunking eller inbyggda WebSocket-baserade integrationer. SMS ansluter via den inbyggda Twilio-integrationen. WhatsApp ansluter genom att importera ett WhatsApp Business-konto och aktivera integrationen för agenten. En enda agent kan distribueras över alla dessa transportsätt samtidigt.

Filindata (bilder och PDF:er) stöds för närvarande på webben, i mobilen och i WhatsApp. Indatahanteringen styrs av typ, inte kanal: ett foto och ett röstmeddelande som kommer in i samma WhatsApp-session bearbetas via helt olika pipelines innan de når modellen. Oavsett kanal eller indatatyp sammanförs alla indata i samma förbehandlingslager innan de skickas till modellen som inbyggd kontext, där de följer en av två vägar.

Indatarepresentation: filbaserad eller inline

Oavsett indatatyp eller kanal normaliserar plattformen varje indata till en av två interna representationer innan den skickas till modellen. Klassificeringen avgör hur indatan kodas i modellens kontextfönster och vad din integration behöver hantera uppströms.

Filbaserade indata

Bilder och PDF:er skickas till modellen som inbyggda filreferenser, inte textsammanfattningar. Plattformen lagrar filen, tilldelar den ett file_id, och kopplar identifieraren till användarens tur. En modell med stöd för bild- eller dokumenthantering tar emot råfilen i sitt kontextfönster i stället för en härledd representation. Integrationskravet är enkelt: fånga upp file_id som returneras av uppladdningsändpunkten och inkludera det i meddelandets payload. Om meddelandet skickas utan file_id har modellen ingen referens till filen, oavsett om uppladdningen lyckades. Fillagringen är begränsad till konversationen. Det innebär att allt som behöver finnas kvar efter sessionen (själva filen, extraherade fält eller strukturerade utdata) måste hanteras uttryckligen av din integration. Hur du gör det varierar beroende på kanal och användningsfall.

Inline

Den andra representationen är inline och omfattar allt annat. Röst och röstmeddelanden transkriberas. Skriven text, transkriberat tal, WhatsApp-platsnålar och kontaktkort normaliseras alla till oformaterad text i transkriptet innan modellen körs. En platsnål blir koordinater och en valfri adress; en kontakt blir ett namn och ett telefonnummer. Inget av detta lagras som filer eller skapar en filreferens. Dessa indata finns direkt i transkriptet.

Varför skillnaden spelar roll

Uppdelningen avgör var din integrationsinsats behövs. Inline-vägen kräver inget från dig under konversationen: plattformen normaliserar dessa indata till text, och de finns direkt i transkriptet. Den filbaserade vägen har en egen integrationsyta. I stället för att konvertera filinnehåll till text innan modellen körs skickar orkestreraren råfilen direkt till modellens kontextfönster. Modellen arbetar med filens struktur i stället för en härledd textrepresentation eller beskrivning, vilket bevarar rumsliga relationer, visuell layout och dokumentformatering som annars skulle gå förlorade. Med den skillnaden i åtanke handlar resten av inlägget om implementeringen: hur du konfigurerar agenten, hur filer går genom varje kanal och hur du behåller kontext mellan sessioner.

Konfigurera multimodal inmatning 

Aktivering av multimodal inmatning börjar med samma agentkonfiguration för webb, mobil och WhatsApp. Därefter beror hur en fil laddas upp och hur du hämtar den efteråt på kanalen.

Aktivera filindata

Två inställningar måste vara på plats i agentkonfigurationen innan filindata fungerar. Ställ först in conversation_config.conversation.file_input.enabled på True, antingen via API:et när agenten skapas eller under Inställningar > Avancerade inställningar > Filindata i kontrollpanelen. Dessutom måste agenten konfigureras med en modell som stöder bilder och dokument. Flaggan ensam gör ingenting om den underliggande modellen inte kan bearbeta bild- eller dokumentblock; båda måste vara inställda innan du testar.

SDK och WebSocket

Filindata på webben eller i mobilen kräver en anpassad chattklient som bygger på SDK:n eller en rå Agents WebSocket-anslutning. Flödet är identiskt för alla tre, och ordningsföljden är ett krav: filen måste laddas upp innan meddelandet skickas, eftersom meddelandets payload refererar till identifieraren som uppladdningen returnerar.

Ladda först upp filen:

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  

Se filuppladdning för hela begäran och svaret:

Skicka sedan ett meddelande via anslutningen som refererar till det returnerade file_id:

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

SDK:erna sammanför uppladdnings- och referensstegen till ett enda anrop och hanterar filidentifieraren internt. Se specifikationen för multimodal_message för hela meddelandeformatet. Eftersom din applikation utför uppladdningen har du redan filen vid den tidpunkten. Om du bara behöver den för den aktuella konversationen räcker det att ladda upp den och referera till identifieraren. Om du behöver behålla den efter sessionen är det enklast att lagra den från din applikation vid uppladdningstillfället. Den kan också hämtas efteråt via webhooken efter samtalet, som beskrivs i avsnittet om kontext mellan sessioner.

WhatsApp

I WhatsApp spelar din applikation ingen roll i uppladdningen. När en kund skickar en bild, ett dokument eller en dekal går filen först till Metas infrastruktur. Meta meddelar ElevenLabs via WhatsApp Business API-webhooken, och ElevenLabs använder autentiseringsuppgifterna för ditt anslutna WhatsApp Business-konto för att ladda ner filen server till server, lagrar en egen kopia och kopplar den till konversationen på samma sätt som vid en webb- eller SDK-uppladdning. Agenten tar emot den som multimodal indata och transkriptet registrerar en file_input-händelse.

Eftersom din applikation aldrig hanterar uppladdningen har den aldrig filen direkt. Det finns ingen väg att fånga den vid uppladdningstillfället, som på webben och i mobilen. Filen når ditt system via file_url i webhooken efter samtalet, som pekar på ElevenLabs lagrade kopia. Metas media-URL används endast för inhämtning och exponeras aldrig externt. Hämtningsmekaniken, inklusive tidsbegränsningar för nedladdning, beskrivs i avsnittet om kontext mellan sessioner.

I WhatsApp skickar kunden filen i chatten. ElevenLabs hämtar den från Meta, lagrar den och kopplar file_id på plattformssidan. Det innebär att det inte finns något uppladdningssteg på klientsidan. Till skillnad från webb och mobil anropar din applikation inte POST /v1/convai/conversations/{id}/files eller skickar multimodal_message över WebSocket. ElevenLabs hanterar leverans, lagring och agentens tur.

Behåll kontext mellan sessioner

ElevenAgents bearbetar varje konversation oberoende. Inget som en kund skickar, och inget som agenten löser under en konversation, förs automatiskt över till nästa. Agenten lämnar över allt från en avslutad konversation till ditt system via webhooken efter samtalet, men minnet som sträcker sig över konversationer finns utanför ElevenLabs gräns. Det är du som ansvarar för kontinuiteten.

Den arkitektoniska gränsen är värd att utforma medvetet kring. De konversationer där multimodal inmatning är viktigast – när en kund fotograferar en skadad vara, laddar upp ett policydokument eller delar en plats – löses ofta inte i en enda session. En kund som skickar ett foto av en trasig del och bokar ett återuppringningssamtal förväntar sig att agenten kommer ihåg fotot när kunden ringer tillbaka. Utan uttrycklig kontexthantering börjar agenten från noll varje gång och kunden måste upprepa sig. Mönstret som löser detta har två delar. När en konversation avslutas levererar webhooken efter samtalet transkriptet, analysresultat, eventuella fält för strukturerad datainsamling som du har definierat och fil-URL:er för alla filer som passerade genom sessionen. Din backend lagrar det som är relevant kopplat till en beständig kundidentifierare, till exempel ett telefonnummer, användar-ID eller kontonyckel. När kunden återkommer injicerar din applikation den lagrade kontexten vid sessionsstart via dynamiska variabler, så att agenten börjar konversationen med det den redan vet. För filbaserade indata specifikt pekar fil-URL:en i webhookens payload på ElevenLabs lagrade kopia och är den enda hämtningsvägen efter att konversationen har stängts. Plattformens kopia är begränsad till sessionen, så om du behöver filen i en framtida konversation eller i dina egna system måste du ladda ner den från webhookens payload innan det fönstret stängs. Hur snabbt du behöver agera beror på lagringspolicyn, som beskrivs i referensdokumentationen. Webhooken för ut tillståndet. Dynamiska variabler för det tillbaka. Allt däremellan är ditt systems ansvar, och det är där det verkliga integrationsarbetet finns för användningsfall där kunder återkommer, eskalerar eller fortsätter mitt i en lösning.

Att injicera kontext beror på kanalen

Injektionsmekanismen varierar beroende på kanal, men det underliggande mönstret är konsekvent. För telefoni anropar ElevenLabs din server innan samtalet ansluts, vilket ger dig möjlighet att slå upp den som ringer utifrån numret och returnera dynamiska variabler som namn, order-ID eller kontonivå innan agenten börjar tala. I WhatsApp utlöses en webhook före meddelandet för varje inkommande meddelande, så att du kan berika det med identitets- och verksamhetskontext från dina system innan agenten bearbetar det. Annars skickas samma fält i conversation_initiation_client_data när sessionen öppnas. ElevenAgents slår inte samman sessioner från olika kanaler till en enda tråd. En WhatsApp-konversation och en webbkonversation är separata sessioner även om de gäller samma kund. Men eftersom webhookutdata och injicering av dynamiska variabler fungerar på samma sätt i alla kanaler kan ett enda beständighetslager hantera dem alla. Bygg det en gång så täcker det varje kanal som agenten körs på. Kontextinjektion hanterar textbaserad data: namn, order-ID:n, sammanfattningar och strukturerade fält. Filer är ett separat fall och kräver en annan metod.

Ta med filer vidare

Filer är begränsade till en konversation och sparas inte automatiskt. Vad du ska ta med vidare beror på om nästa konversation behöver informationen från en fil eller själva filen. I de flesta fall behövs bara informationen. Agenten tolkar en uppladdad fil i den tur då den anländer men skriver inte automatiskt tolkningen till någon beständig plats. De strukturerade utdata kommer från data efter samtalet: transkriptet, transkriptsammanfattningen och eventuella resultatfält för datainsamling som du definierar. Om en kund skickar ett foto av en sprucken dörrtätning och återkommer en vecka senare för att följa upp ärendet behöver agenten inte fotot igen. Den behöver veta att ärendet gäller en sprucken dörrtätning. Du extraherar det från data efter samtalet, lagrar det kopplat till kundidentifieraren och injicerar det som en dynamisk variabel när kunden återkommer. En kort sammanfattning eller några strukturerade fält räcker vanligtvis.

När du behöver originalfilen, för egna register, efterlevnad eller efterföljande system, är webhooken efter samtalet hämtningsvägen. Varje uppladdad fil visas i transkriptet som en file_input-händelse med en signerad fil-URL. Den URL:en är giltig i femton minuter, så ladda ner och lagra filen när webhooken kommer i stället för att vänta. Om du missar det fönstret medan konversationen fortfarande finns kvar utfärdar GET conversation API nya URL:er som reserv. Planera för att file_input kan saknas i vissa fall, till exempel i läget utan lagring, i stället för att anta att varje filbaserad tur innehåller en URL.

Det täcker hela livscykeln: en fil kommer in i sessionen, modellen arbetar med den direkt, strukturerade utdata lämnar via webhooken och ditt beständighetslager avgör vad agenten vet nästa gång.

Slutsats

Samma agentkonfiguration accepterar bilder och PDF:er på webb, mobil och WhatsApp utan att du behöver bygga separat för varje kanal. Filer normaliseras, kopplas till turen och skickas till modellen som inbyggda block i stället för textsammanfattningar, så rumslig layout, visuell struktur och dokumentformatering når modellen intakta. Kontext mellan sessioner följer samma mönster i varje kanal: webhooken efter samtalet för ut tillståndet och dynamiska variabler för det tillbaka.

Om du bygger med ElevenLabs Agents och vill att din agent ska kunna arbeta med bilder och dokument tillsammans med röst och text, aktivera multimodal inmatning och berätta gärna vad du tycker.