Bearbeta bilder och dokument i ElevenAgents

En arbetsledare upptäcker materialbrist på en byggarbetsplats. Han fotograferar den, skickar bilden till inköpsagenten på WhatsApp och bekräftar leveransadressen med rösten. Agenten behandlar bilden, identifierar vad som saknas och lägger en expressorder – allt i samma konversation. Arbetsflöden i företag 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 detta direkt till agenten kortar ner konversationen 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 nätbaserade matbutiksplattformar, använder sin agent via telefon, webb, app och WhatsApp på sex språk och löser 90 % av kundärendena automatiskt. Multimodala inmatningar utökar samma lösningsgrad till tillfällen då kunden behöver visa i stället för att berätta. ElevenAgents behandlar filer som förstahandsinmatningar i samma agent som redan hanterar röst, WhatsApp, webb och mobil. Filer når den underliggande modellen som inbyggda meddelanden, så att en enda agent hanterar alla typer av inmatning i en och 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 bevarar kontext mellan sessioner när en kund återkommer.

Kanaler och inmatningar 

ElevenAgents är byggt kring de kanaler som företag redan använder för att nå sina kunder: webb- och mobilapplikationer, supportplattformar, telefon, SMS, e-post, WhatsApp med flera. Agentkonfigurationen (prompt, modell, verktyg, kunskapsbas och röst) definieras en gång och delas mellan alla kanaler. Två saker varierar mellan kanalerna: transportlagret och vilka inmatningstyper det stöder. Webb- och mobilapplikationer ansluter via den inbäddningsbara widgeten, något 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 på agenten. En enda agent kan distribueras över alla dessa transportlager samtidigt.

Filinmatningar (bilder och PDF:er) stöds för närvarande på webb, mobil och WhatsApp. Inmatningar hanteras utifrån typ, inte kanal: ett foto och ett röstmeddelande som kommer in under samma WhatsApp-session behandlas genom helt olika pipelines innan de når modellen. Oavsett kanal eller inmatningstyp sammanförs alla inmatningar i samma förbehandlingslager innan de skickas till modellen som inbyggd kontext, där de följer en av två vägar.

Inmatningsrepresentation: filbaserad eller inline

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

Filbaserade inmatningar

Bilder och PDF:er skickas till modellen som inbyggda filreferenser, inte som 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 får den råa filen i sitt kontextfönster i stället för en härledd representation. Kravet för integrationen är enkelt: fånga file_id som upload-endpointen returnerar och inkludera den 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 strukturerad output – måste hanteras uttryckligen av din integration. Hur det görs varierar mellan kanaler och användningsfall.

Inline

Den andra representationen är inline och omfattar allt annat. Röst och röstmeddelanden transkriberas. Skriven text, transkriberat tal, platsnålar i WhatsApp och kontaktkort normaliseras alla till oformaterad text i transkriptionen 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 inmatningar finns direkt i transkriptionen.

Varför skillnaden är viktig

Uppdelningen avgör var du behöver lägga integrationsarbetet. Inline-vägen kräver inget av dig under konversationen: plattformen normaliserar dessa inmatningar till text och de finns direkt i transkriptionen. Den filbaserade vägen har ett eget integrationsgränssnitt. I stället för att omvandla filinnehållet 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 samband, visuell layout och dokumentformatering som annars skulle gå förlorade. Med den skillnaden i åtanke går resten av det här inlägget igenom implementeringen: hur du konfigurerar agenten, hur filer rör sig genom varje kanal och hur du bevarar kontext mellan sessioner.

Konfigurera multimodala inmatningar 

Att aktivera multimodala inmatningar 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 i efterhand på kanalen.

Aktivera filinmatning

Två inställningar måste finnas i agentkonfigurationen innan filinmatning fungerar. Ställ först in conversation_config.conversation.file_input.enabled på True, antingen via API:t när agenten skapas eller under Inställningar > Avancerade inställningar > Filinmatning i kontrollpanelen. För det andra måste agenten konfigureras med en modell som kan hantera bilder och dokument. Flaggan i sig gör ingenting om den underliggande modellen inte kan behandla bild- eller dokumentblock. Båda måste vara inställda före testning.

SDK och WebSocket

Filinmatning på webb eller mobil kräver en anpassad chattklient byggd på SDK:t eller en rå Agents-websocketanslutning. 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 den fullständiga begäran och responsen:

Skicka sedan ett meddelande över 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 samlar uppladdnings- och referensstegen i ett enda anrop och hanterar filidentifieraren internt. Se specifikationen för multimodal_message för det fullständiga 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 spara den efter sessionen är det enklast att lagra den från din applikation vid uppladdningen. Den kan också hämtas i efterhand via webhooken efter samtalet, vilket tas upp i avsnittet om kontext mellan sessioner.

WhatsApp

På WhatsApp har din applikation ingen del 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 inloggningsuppgifterna 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 uppladdning från webb eller SDK. Agenten tar emot den som multimodal inmatning och transkriptionen registrerar en file_input-händelse.

Eftersom din applikation aldrig hanterar uppladdningen får den aldrig filen direkt. Det finns ingen väg att fånga den vid uppladdningen, som det finns på webb och mobil. Filen når ditt system via file_url i webhooken efter samtalet, som pekar på ElevenLabs lagrade kopia. Metas medie-URL används bara för inläsning och exponeras aldrig externt. Hämtningsmekaniken, inklusive tidsbegränsningar för nedladdning, behandlas i avsnittet om kontext mellan sessioner.

På WhatsApp skickar kunden filen i chatten. ElevenLabs hämtar den från Meta, lagrar den och kopplar file_id på plattformssidan. Det betyder 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 och skickar inte multimodal_message via WebSocket. ElevenLabs hanterar leverans, lagring och agentens tur.

Bevara kontext mellan sessioner

ElevenAgents behandlar varje konversation oberoende. Ingenting som en kund skickar, och ingenting agenten löser under en konversation, följer automatiskt med till nästa. Agenten skickar 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 medvetet utforma kring. Konversationerna där multimodala inmatningar är viktigast – en kund som 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 minns 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 transkriptionen, analysresultat, eventuella fält för strukturerad datainsamling som du har definierat samt fil-URL:er för filer som passerade genom sessionen. Din backend lagrar det som är relevant mot en beständig kundidentifierare, till exempel ett telefonnummer, användar-ID eller kontonyckel. När kunden återkommer injicerar din applikation den lagrade kontexten vid sessionens start via dynamiska variabler, så att agenten börjar konversationen med det den redan vet. Särskilt för filbaserade inmatningar pekar fil-URL:en i webhookens payload på ElevenLabs lagrade kopia och är den enda hämtningsvägen efter att konversationen har avslutats. 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 tidsfö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 ligger i alla användningsfall där kunder återkommer, eskalerar eller fortsätter mitt i en lösning.

Att injicera kontext beror på kanalen

Injektionsmekanismen varierar mellan kanaler, men det underliggande mönstret är konsekvent. För telefoni anropar ElevenLabs din server innan samtalet kopplas upp, vilket ger dig möjlighet att slå upp uppringaren via numret och returnera dynamiska variabler som namn, order-ID eller kontonivå innan agenten talar. På WhatsApp utlöses en webhook före meddelandet för varje inkommande meddelande, så att du kan berika det med identitets- och affärskontext från dina system innan agenten behandlar det. I övriga fall skickas samma fält i conversation_initiation_client_data när sessionen öppnas. ElevenAgents slår inte ihop 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 webhook-output och injicering av dynamiska variabler fungerar identiskt 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 som ska följa med 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 kommer in, men skriver inte automatiskt tolkningen till någon beständig plats. Den strukturerade outputen kommer från data efter samtalet: transkriptionen, transkriptionssammanfattningen 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 mot 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 arkiv, regelefterlevnad eller system längre ned i flödet, är webhooken efter samtalet hämtningsvägen. Varje uppladdad fil visas i transkriptionen 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 tidsfö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 har en URL.

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

Slutsats

Samma agentkonfiguration tar emot bilder och PDF:er via webb, mobil och WhatsApp utan att du behöver en separat implementation för varje kanal. Filer normaliseras, kopplas till turen och skickas till modellen som inbyggda block i stället för textsammanfattningar, så att 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 multimodala inmatningar och berätta gärna vad du tycker.