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 fotot, identifierar vad som saknas och lägger en expressorder – allt i samma konversation. Arbetsflöden i företag innehåller ofta ett 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 av en policy. Genom att skicka detta direkt till agenten blir konversationen kortare och ärendet löses snabbare. När en kund kan visa i stället för att beskriva felsöker agenten snabbare utan att be kunden byta kanal. Rohlik, en av Europas största nätbaserade livsmedelsplattformar, använder sin agent via telefon, webb, app och WhatsApp på sex språk och löser 90 % av kundärendena automatiskt. Multimodal inmatning utökar samma lösningsgrad till situationer där kunden behöver visa, inte berätta. ElevenAgents behandlar filer som förstahandsinmatning i 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 inmatningstyper 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 behåller kontext mellan sessioner när en kund återkommer.

Kanaler och inmatningar 

ElevenAgents bygger på de kanaler som företag redan använder för att nå kunder: webb- och mobilapplikationer, deras supportplattform, telefon, SMS, e-post, WhatsApp och andra. Agentkonfigurationen (prompt, modell, verktyg, kunskapsbas och röst) definieras en gång och delas mellan alla kanaler. Två saker skiljer sig mellan kanalerna: transportlagret och vilka inmatningstyper som stöds. 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 för agenten. En och samma agent kan användas via alla dessa transportlager samtidigt.

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

Indatarepresentation: 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 som kan hantera bilder eller dokument tar emot rå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 returneras av uppladdningsändpunkten 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 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, platsnålar i WhatsApp och kontaktkort normaliseras alla till oformaterad text i transkriptet innan modellen körs. En platsnål blir koordinater och en valfri adress, och en kontakt blir ett namn och ett telefonnummer. Inget av detta lagras som filer eller skapar en filreferens. Dessa inmatningar finns direkt i transkriptet.

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 transkriptet. Den filbaserade vägen har en separat integrationsyta. I stället för att omvandla 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, och bevarar rumsliga relationer, visuell layout och dokumentformatering som annars skulle gå förlorade. Med den skillnaden i åtanke går resten av inlägget igenom implementeringen: hur du konfigurerar agenten, hur filer rör sig 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 sättet en fil laddas upp och hämtas i efterhand på kanalen.

Aktivera filinmatning

Två inställningar måste finnas i agentkonfigurationen innan filinmatning fungerar. Ange först conversation_config.conversation.file_input.enabled till True, antingen via API:et 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 ensam gör ingenting om den underliggande modellen inte kan bearbeta 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 som bygger på SDK:t eller en rå Agents-websocket-anslutning. Flödet är identiskt för alla tre, och ordningsföljden är ett hårt 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 ö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 sammanför stegen för uppladdning och referens 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 lagra den efter sessionen är det enklaste att spara den från din applikation vid uppladdningstillfället. Den kan också hämtas i efterhand via webhooken efter samtalet, vilket behandlas 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 sticker går filen först till Metas infrastruktur. Meta meddelar ElevenLabs genom WhatsApp Business API-webhooken, och ElevenLabs använder autentiseringsuppgifterna för ditt anslutna WhatsApp Business-konto för att ladda ned filen från server till server, lagrar en egen kopia och bifogar den till konversationen på samma sätt som vid en uppladdning från webb eller SDK. Agenten tar emot den som multimodal inmatning 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 hämta den vid uppladdningstillfället, som på webb och mobil. Filen når ditt system genom file_url i webhooken efter samtalet, som pekar på ElevenLabs lagrade kopia. Metas medie-URL används endast 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 bifogar file_id på plattformssidan. Det innebär att det inte finns något uppladdningssteg på klientsidan. Till skillnad från på webb och mobil anropar din applikation inte POST /v1/convai/conversations/{id}/files eller skickar multimodal_message via WebSocket. ElevenLabs hanterar leveransen, lagringen och agentens tur.

Behåll kontext mellan sessioner

ElevenAgents behandlar varje konversation separat. Inget som en kund skickar, och inget som agenten löser under en konversation, följer automatiskt med till nästa. Agenten överlämnar 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. De konversationer där multimodal inmatning är som viktigast – 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 minns fotot när kunden ringer tillbaka. Utan tydlig 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 samt fil-URL:er för alla filer som passerade genom sessionen. Din backend lagrar det relevanta mot en varaktig kundidentifierare, som ett telefonnummer, användar-ID eller kontonyckel. När kunden återkommer injicerar din applikation den lagrade kontexten i början av sessionen genom dynamiska variabler, så att agenten börjar konversationen med det den redan vet. För filbaserade inmatningar pekar särskilt fil-URL:en i webhookens payload på ElevenLabs lagrade kopia och är den enda hämtningsvägen när 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 ned 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 data. Dynamiska variabler för in den igen. Allt däremellan är ditt systems ansvar, och det är där det verkliga integrationsarbetet ligger för användningsfall där kunder återkommer, eskalerar eller fortsätter mitt i en lösning.

Att injicera kontext beror på kanalen

Injiceringsmekanismen varierar mellan kanaler, 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 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 komplettera 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 sammanfogar inte sessioner mellan 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 likadant i alla kanaler kan ett enda persistenslager hantera dem alla. Bygg det en gång, så täcker det varje kanal som agenten körs på. Kontextinjektion hanterar textformad 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 tas 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 den kommer in, men skriver inte automatiskt tolkningen till något varaktigt. Den strukturerade utdatan kommer från data efter samtalet: transkriptet, transkriptsammanfattningen och eventuella resultatsfä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 detta 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 register, efterlevnad eller nedströmsystem, ä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 ned 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 förutsätta att varje filbaserad tur har en URL.

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

Slutsats

Samma agentkonfiguration tar emot bilder och PDF:er via webb, mobil och WhatsApp utan 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 vid sidan av röst och text, aktivera multimodal inmatning och berätta vad du tycker.