Verarbeitung von Bildern und Dokumenten in ElevenAgents

Ein Bauleiter stellt auf einer Baustelle einen Materialmangel fest. Er fotografiert ihn, sendet das Bild per WhatsApp an den Beschaffungsagenten und bestätigt die Lieferadresse per Sprache. Der Agent verarbeitet das Foto, erkennt, was fehlt, und löst eine Eilbestellung aus – alles in einem Gespräch. Unternehmensabläufe enthalten regelmäßig Kontext, den Worte allein nicht vermitteln können. Die Informationen zur Bearbeitung einer Anfrage können als Foto eines beschädigten Artikels oder als PDF einer Richtlinie vorliegen. Wenn Sie diese direkt an den Agenten übergeben, verkürzt das das Gespräch und beschleunigt die Lösung. Wenn Kundinnen und Kunden etwas zeigen statt beschreiben können, findet der Agent schneller eine Lösung, ohne dass sie den Kanal wechseln müssen. Rohlik, eine der größten Online-Lebensmittelplattformen Europas, betreibt seinen Agenten in sechs Sprachen über Telefon, Web, App und WhatsApp und löst 90 % der Kundenanfragen automatisch. Multimodale Eingaben ermöglichen diese Lösungsquote auch in Situationen, in denen Kundinnen und Kunden etwas zeigen statt erklären müssen. ElevenAgents behandelt Dateien als gleichwertige Eingaben für denselben Agenten, der bereits Sprache, WhatsApp, Web und Mobilgeräte verarbeitet. Dateien erreichen das zugrunde liegende Modell als native Nachrichten, sodass ein einzelner Agent jeden Eingabetyp innerhalb eines Gesprächs-Threads verarbeitet. 

Dieser Beitrag erläutert, was Multimodalität auf der Plattform bedeutet, wie Dateien vom Gerät eines Kunden in den Kontext des Modells gelangen, welche Funktionen die einzelnen Kanäle unterstützen und wie Sie Kontext über Sitzungen hinweg übernehmen, wenn ein Kunde zurückkehrt.

Kanäle und Eingaben 

ElevenAgents basiert auf den Kanälen, über die Unternehmen Kundinnen und Kunden bereits erreichen: Web- und Mobilanwendungen, Supportplattformen, Telefon, SMS, E-Mail, WhatsApp und weitere. Die Agentenkonfiguration – Prompt, Modell, Tools, Wissensdatenbank und Stimme – wird einmal definiert und für alle Kanäle verwendet. Zwei Dinge unterscheiden sich je Kanal: die Transportschicht und die unterstützten Eingabetypen. Web- und Mobilanwendungen verbinden sich über das einbettbare Widget, eines der SDKs oder den Agents WebSocket. Telefongespräche verbinden sich über natives Twilio, SIP-Trunking oder native WebSocket-basierte Integrationen. SMS verbindet sich über die native Twilio-Integration. WhatsApp wird durch den Import eines WhatsApp-Business-Kontos und die Aktivierung der Integration für den Agenten verbunden. Ein einzelner Agent kann gleichzeitig über alle diese Transportwege bereitgestellt werden.

Dateieingaben – Bilder und PDFs – werden derzeit im Web, auf Mobilgeräten und über WhatsApp unterstützt. Die Eingabeverarbeitung ist typ-, nicht kanalbasiert: Ein Foto und eine Sprachnachricht, die in derselben WhatsApp-Sitzung eingehen, werden über völlig unterschiedliche Pipelines verarbeitet, bevor sie das Modell erreichen. Unabhängig von Kanal oder Eingabetyp laufen alle Eingaben in derselben Vorverarbeitungsschicht zusammen, bevor sie als nativer Kontext an das Modell übergeben werden. Dort folgen sie einem von zwei Pfaden.

Eingabedarstellung: dateibasiert oder inline

Unabhängig von Eingabetyp oder Kanal normalisiert die Plattform jede Eingabe in eine von zwei internen Darstellungen, bevor sie an das Modell übergeben wird. Diese Klassifizierung bestimmt, wie die Eingabe im Kontextfenster des Modells kodiert wird und was Ihre Integration vorgelagert verarbeiten muss.

Dateibasierte Eingaben

Bilder und PDFs werden dem Modell als native Dateireferenzen übergeben, nicht als Textzusammenfassungen. Die Plattform speichert die Datei, weist ihr eine file_id zu und verknüpft diese Kennung mit dem Turn des Nutzers. Ein bild- oder dokumentfähiges Modell erhält die Rohdatei in seinem Kontextfenster statt einer abgeleiteten Darstellung. Die Anforderung an die Integration ist einfach: Erfassen Sie die vom Upload-Endpunkt zurückgegebene file_id und fügen Sie sie der Nachrichten-Payload hinzu. Wird die Nachricht ohne file_id gesendet, hat das Modell keinen Verweis auf die Datei – unabhängig davon, ob der Upload erfolgreich war. Die Dateispeicherung ist auf das Gespräch beschränkt. Alles, was über die Sitzung hinaus bestehen soll – die Datei selbst, extrahierte Felder oder eine strukturierte Ausgabe –, muss daher explizit von Ihrer Integration verarbeitet werden. Der Mechanismus dafür variiert je nach Kanal und Anwendungsfall.

Inline

Die zweite Darstellung ist inline und umfasst alles andere. Sprache und Sprachnachrichten werden transkribiert. Eingegebener Text, transkribierte Sprache, WhatsApp-Standortmarkierungen und Kontaktkarten werden vor der Ausführung des Modells im Transkript zu Klartext normalisiert. Eine Standortmarkierung wird zu Koordinaten und einer optionalen Adresse, ein Kontakt zu einem Namen und einer Telefonnummer. Keine dieser Eingaben wird als Datei gespeichert oder erzeugt eine Dateireferenz. Sie liegen direkt im Transkript vor.

Warum diese Unterscheidung wichtig ist

Die Trennung bestimmt, wohin Ihr Integrationsaufwand fließt. Der Inline-Pfad erfordert während des Gesprächs nichts von Ihnen: Die Plattform normalisiert diese Eingaben zu Text, der direkt im Transkript liegt. Der dateibasierte Pfad hat eine eigene Integrationsoberfläche. Statt Dateiinhalte vor der Modellausführung in Text umzuwandeln, übergibt der Orchestrator die Rohdatei direkt an das Kontextfenster des Modells. Das Modell arbeitet mit der Struktur der Datei statt mit einer abgeleiteten Textdarstellung oder Beschreibung. So bleiben räumliche Beziehungen, visuelles Layout und Dokumentformatierung erhalten, die sonst verloren gingen. Vor diesem Hintergrund behandelt der Rest dieses Beitrags die Implementierung: die Konfiguration des Agenten, den Dateifluss über die einzelnen Kanäle und die Übernahme von Kontext über Sitzungen hinweg.

Multimodale Eingaben einrichten 

Die Aktivierung multimodaler Eingaben beginnt mit derselben Agentenkonfiguration für Web, Mobilgeräte und WhatsApp. Wie eine Datei hochgeladen und später abgerufen wird, hängt dann vom Kanal ab.

Dateieingaben aktivieren

Bevor Dateieingaben funktionieren, müssen zwei Einstellungen in der Agentenkonfiguration gesetzt sein. Setzen Sie zuerst conversation_config.conversation.file_input.enabled auf True, entweder über die API bei der Agentenerstellung oder im Dashboard unter Einstellungen > Erweiterte Einstellungen > Dateieingabe. Zweitens muss der Agent mit einem bild- und dokumentfähigen Modell konfiguriert sein. Das Flag allein bewirkt nichts, wenn das zugrunde liegende Modell keine Bild- oder Dokumentblöcke verarbeiten kann. Beides muss vor dem Testen gesetzt sein.

SDK und WebSocket

Dateieingaben im Web oder auf Mobilgeräten erfordern einen benutzerdefinierten Chat-Client auf Basis des SDKs oder eine direkte Agents-WebSocket-Verbindung. Der Ablauf ist für alle drei identisch, und die Reihenfolge ist zwingend: Die Datei muss vor dem Senden der Nachricht hochgeladen werden, weil die Nachrichten-Payload auf die Kennung verweist, die der Upload zurückgibt.

Laden Sie zuerst die Datei hoch:

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  

Die vollständige Anfrage und Antwort finden Sie unter Datei-Upload:

Senden Sie anschließend eine Nachricht über die Verbindung, die auf die zurückgegebene file_id verweist:

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

Die SDKs fassen Upload und Referenzierung in einem einzigen Aufruf zusammen und verwalten die Dateikennung intern. Die vollständige Nachrichtenstruktur finden Sie in der Spezifikation für multimodal_message. Da Ihre Anwendung den Upload ausführt, liegt ihr die Datei zu diesem Zeitpunkt bereits vor. Benötigen Sie sie nur für das aktuelle Gespräch, genügt der Upload mit Verweis auf die Kennung. Soll sie über die Sitzung hinaus bestehen bleiben, speichern Sie sie am besten beim Upload direkt aus Ihrer Anwendung. Sie kann anschließend auch über den Post-Call-Webhook abgerufen werden, wie im Abschnitt zum Kontext über Sitzungen hinweg beschrieben.

WhatsApp

Bei WhatsApp ist Ihre Anwendung nicht am Upload beteiligt. Wenn ein Kunde ein Bild, Dokument oder einen Sticker sendet, gelangt die Datei zunächst in die Infrastruktur von Meta. Meta benachrichtigt ElevenLabs über den WhatsApp-Business-API-Webhook. ElevenLabs verwendet dann die Anmeldedaten Ihres verbundenen WhatsApp-Business-Kontos, um die Datei serverseitig herunterzuladen, speichert eine eigene Kopie und hängt sie – wie bei einem Web- oder SDK-Upload – an das Gespräch an. Der Agent erhält sie als multimodale Eingabe und das Transkript zeichnet ein file_input-Ereignis auf.

Da Ihre Anwendung den Upload nie verarbeitet, hält sie die Datei nie direkt. Anders als im Web und auf Mobilgeräten gibt es keinen Weg, sie beim Upload zu erfassen. Die Datei gelangt über die file_url im Post-Call-Webhook in Ihr System; diese verweist auf die gespeicherte Kopie von ElevenLabs. Die Medien-URL von Meta wird nur für die Aufnahme verwendet und nie extern bereitgestellt. Die Abrufmechanik einschließlich der zeitlichen Download-Beschränkungen wird im Abschnitt zum Kontext über Sitzungen hinweg behandelt.

Bei WhatsApp sendet der Kunde die Datei im Chat. ElevenLabs ruft sie von Meta ab, speichert sie und hängt die file_id plattformseitig an. Daher gibt es keinen clientseitigen Upload-Schritt. Anders als im Web und auf Mobilgeräten ruft Ihre Anwendung nicht POST /v1/convai/conversations/{id}/files auf und sendet keine multimodal_message über WebSocket. ElevenLabs übernimmt Zustellung, Speicherung und den Agenten-Turn.

Kontext über Sitzungen hinweg übernehmen

ElevenAgents verarbeitet jedes Gespräch unabhängig. Weder Inhalte, die ein Kunde sendet, noch Ergebnisse, die der Agent während eines Gesprächs erzielt, werden automatisch in das nächste Gespräch übernommen. Der Agent übergibt Ihrem System über den Post-Call-Webhook alles aus einem abgeschlossenen Gespräch. Der Gesprächsübergreifende Speicher liegt jedoch außerhalb der Grenze von ElevenLabs. Die Kontinuität liegt in Ihrer Verantwortung.

Diese Architekturgrenze sollten Sie bewusst in Ihr Design einbeziehen. Die Gespräche, in denen multimodale Eingaben besonders wichtig sind – etwa wenn Kunden einen beschädigten Artikel fotografieren, ein Richtliniendokument hochladen oder einen Standort teilen –, werden oft nicht in einer einzigen Sitzung gelöst. Ein Kunde, der ein Foto eines defekten Teils sendet und einen Rückruf vereinbart, erwartet, dass sich der Agent beim Rückruf an das Foto erinnert. Ohne explizites Kontextmanagement beginnt der Agent jedes Mal bei null und der Kunde muss sich wiederholen. Das passende Muster besteht aus zwei Teilen. Wenn ein Gespräch endet, liefert der Post-Call-Webhook das Transkript, Analyseergebnisse, alle definierten Felder zur strukturierten Datenerfassung sowie Datei-URLs für Dateien aus der Sitzung. Ihr Backend speichert relevante Informationen anhand einer dauerhaften Kundenkennung wie Telefonnummer, Nutzer-ID oder Kontoschlüssel. Kehrt der Kunde zurück, fügt Ihre Anwendung den gespeicherten Kontext beim Sitzungsstart über dynamische Variablen ein. So beginnt der Agent das Gespräch mit dem Wissen, das er bereits hat. Bei dateibasierten Eingaben verweist die Datei-URL in der Webhook-Payload auf die gespeicherte Kopie von ElevenLabs und ist nach dem Ende des Gesprächs der einzige Abrufweg. Die Kopie der Plattform ist auf die Sitzung beschränkt. Wenn Sie die Datei in einem künftigen Gespräch oder in eigenen Systemen benötigen, müssen Sie sie vor Ablauf dieses Zeitfensters aus der Webhook-Payload herunterladen. Wie schnell Sie handeln müssen, hängt von der Aufbewahrungsrichtlinie ab, die in der Referenzdokumentation beschrieben wird. Der Webhook übergibt den Status nach außen. Dynamische Variablen bringen ihn zurück. Alles dazwischen liegt in der Verantwortung Ihres Systems – und dort steckt die eigentliche Integrationsarbeit für Anwendungsfälle, in denen Kunden zurückkehren, eskalieren oder eine laufende Lösung fortsetzen.

Der Kontext-Import hängt vom Kanal ab

Der Importmechanismus variiert je nach Kanal, doch das zugrunde liegende Muster ist einheitlich. Bei Telefonie ruft ElevenLabs Ihren Server auf, bevor die Verbindung hergestellt wird. So können Sie den Anrufer über seine Nummer identifizieren und dynamische Variablen wie Name, Bestell-ID oder Kontostufe zurückgeben, bevor der Agent spricht. Bei WhatsApp wird für jede eingehende Nachricht ein Pre-Message-Webhook ausgelöst. Damit können Sie sie mit Identitäts- und Geschäftskontext aus Ihren Systemen anreichern, bevor der Agent sie verarbeitet. Andernfalls werden dieselben Felder beim Öffnen der Sitzung in conversation_initiation_client_data übergeben. ElevenAgents führt Sitzungen aus verschiedenen Kanälen nicht zu einem einzigen Thread zusammen. Ein WhatsApp-Gespräch und ein Web-Gespräch sind getrennte Sitzungen, selbst wenn sie denselben Kunden betreffen. Da Webhook-Ausgabe und die Übergabe dynamischer Variablen jedoch auf allen Kanälen identisch funktionieren, genügt eine einzige Persistenzschicht für alle. Sie wird einmal erstellt und deckt jeden Kanal ab, auf dem der Agent läuft. Der Kontext-Import verarbeitet textförmige Daten: Namen, Bestell-IDs, Zusammenfassungen und strukturierte Felder. Dateien sind ein separater Fall und erfordern einen anderen Ansatz.

Dateien übernehmen

Dateien sind auf ein Gespräch beschränkt und bleiben nicht automatisch erhalten. Was Sie übernehmen sollten, hängt davon ab, ob das nächste Gespräch die Informationen aus einer Datei oder die Datei selbst benötigt. In den meisten Fällen werden nur die Informationen benötigt. Der Agent interpretiert eine hochgeladene Datei in dem Turn, in dem sie eingeht, speichert diese Interpretation aber nicht automatisch dauerhaft. Die strukturierte Ausgabe stammt aus den Post-Call-Daten: dem Transkript, der Transkriptzusammenfassung und allen von Ihnen definierten Ergebnissen der Datenerfassung. Sendet ein Kunde ein Foto einer gerissenen Türdichtung und meldet sich eine Woche später zum Schadenfall zurück, braucht der Agent das Foto nicht erneut. Er muss wissen, dass der Schadenfall eine gerissene Türdichtung betrifft. Extrahieren Sie dies aus den Post-Call-Daten, speichern Sie es anhand der Kundenkennung und fügen Sie es bei der Rückkehr als dynamische Variable ein. Eine kurze Zusammenfassung oder einige strukturierte Felder reichen in der Regel aus.

Wenn Sie die Originaldatei für eigene Unterlagen, Compliance oder nachgelagerte Systeme benötigen, erfolgt der Abruf über den Post-Call-Webhook. Jede hochgeladene Datei erscheint im Transkript als file_input-Ereignis mit einer signierten Datei-URL. Diese URL ist fünfzehn Minuten gültig. Laden Sie die Datei daher herunter und speichern Sie sie, sobald der Webhook eintrifft, statt dies aufzuschieben. Verpassen Sie dieses Zeitfenster, während das Gespräch noch besteht, stellt die GET-Conversation-API als Fallback neue URLs aus. Planen Sie ein, dass file_input in einigen Fällen, etwa im Modus ohne Datenaufbewahrung, fehlen kann, statt davon auszugehen, dass jeder dateibasierte Turn eine URL enthält.

Damit ist der vollständige Lebenszyklus abgedeckt: Eine Datei gelangt in die Sitzung, das Modell verarbeitet sie nativ, die strukturierte Ausgabe verlässt das System über den Webhook, und Ihre Persistenzschicht entscheidet, was der Agent beim nächsten Mal weiß.

Fazit

Dieselbe Agentenkonfiguration akzeptiert Bilder und PDFs über Web, Mobilgeräte und WhatsApp, ohne dass je Kanal eine separate Implementierung erforderlich ist. Dateien werden normalisiert, an den Turn gebunden und als native Blöcke statt als Textzusammenfassungen an das Modell übergeben. So erreichen räumliches Layout, visuelle Struktur und Dokumentformatierung das Modell vollständig. Der Kontext über Sitzungen hinweg folgt auf jedem Kanal demselben Muster: Der Post-Call-Webhook übergibt den Status nach außen, dynamische Variablen bringen ihn zurück.

Wenn Sie mit ElevenLabs Agents arbeiten und Ihr Agent neben Sprache und Text auch mit Bildern und Dokumenten arbeiten soll, aktivieren Sie multimodale Eingaben und teilen Sie uns Ihre Meinung mit.