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 gibt eine Eilbestellung auf – alles in einem Gespräch. Unternehmensabläufe enthalten regelmäßig Kontext, den Worte allein nicht vermitteln können. Die Informationen zur Lösung einer Anfrage können als Foto eines beschädigten Artikels oder als PDF einer Richtlinie vorliegen. Wenn diese direkt an den Agenten übermittelt werden, verkürzt das das Gespräch und beschleunigt die Lösung. Wenn ein Kunde etwas zeigen statt beschreiben kann, löst der Agent das Problem schneller, ohne dass der Kunde den Kanal wechseln muss. 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 übertragen diese Lösungsquote auf Situationen, in denen Kunden etwas zeigen statt beschreiben müssen. ElevenAgents behandelt Dateien als vollwertige 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ächsverlaufs verarbeitet. 

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

Kanäle und Eingaben 

ElevenAgents basiert auf den Kanälen, die Unternehmen bereits zur Kundenansprache nutzen: Web- und Mobilanwendungen, Support-Plattformen, Telefon, SMS, E-Mail, WhatsApp und weitere. Die Agentenkonfiguration (Prompt, Modell, Tools, Wissensdatenbank und Stimme) wird einmal definiert und über alle Kanäle hinweg geteilt. Pro Kanal unterscheiden sich zwei Dinge: 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 verbindet sich durch den Import eines WhatsApp-Business-Kontos und die Aktivierung der Integration für den Agenten. Ein einzelner Agent kann gleichzeitig über all diese Transportschichten bereitgestellt werden.

Dateieingaben (Bilder und PDFs) werden derzeit im Web, auf Mobilgeräten und in WhatsApp unterstützt. Die Eingabeverarbeitung ist typ- statt kanalbasiert: Ein Foto und eine Sprachnachricht, die in derselben WhatsApp-Sitzung eingehen, durchlaufen vor dem Modell völlig unterschiedliche Pipelines. 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 Wegen.

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 Modell mit Bild- oder Dokumentverarbeitung 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 in die Nachrichten-Payload ein. 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 bleiben muss – 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 erfolgt inline und umfasst alles andere. Sprache und Sprachnachrichten werden transkribiert. Eingegebener Text, transkribierte Sprache, WhatsApp-Standortmarkierungen und Kontaktkarten werden im Transkript in Klartext normalisiert, bevor das Modell ausgeführt wird. Eine Standortmarkierung wird zu Koordinaten und einer optionalen Adresse; ein Kontakt zu einem Namen und einer Telefonnummer. Keines dieser Elemente wird als Datei gespeichert oder erzeugt eine Dateireferenz. Diese Eingaben befinden sich direkt im Transkript.

Warum diese Unterscheidung wichtig ist

Die Aufteilung bestimmt, worauf sich Ihr Integrationsaufwand konzentriert. Der Inline-Pfad erfordert während des Gesprächs nichts von Ihnen: Die Plattform normalisiert diese Eingaben zu Text, und sie befinden sich direkt im Transkript. Der dateibasierte Pfad hat eine eigene Integrationsoberfläche. Statt Dateiinhalte in Text umzuwandeln, bevor das Modell ausgeführt wird, ü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 Dokumentformatierungen erhalten, die sonst verloren gingen. Vor diesem Hintergrund behandelt der weitere Beitrag die Implementierung: die Konfiguration des Agenten, den Weg von Dateien durch 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 wird und wie Sie sie anschließend abrufen, hängt dann vom Kanal ab.

Dateieingaben aktivieren

Damit 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 Modell konfiguriert sein, das Bilder und Dokumente verarbeiten kann. Das Flag allein bewirkt nichts, wenn das zugrunde liegende Modell keine Bild- oder Dokumentblöcke verarbeiten kann. Vor dem Testen müssen beide Einstellungen gesetzt sein.

SDK und WebSocket

Dateieingaben im Web oder auf Mobilgeräten erfordern einen benutzerdefinierten Chat-Client auf Basis des SDK oder eine direkte Agents-WebSocket-Verbindung. Der Ablauf ist bei allen drei Varianten identisch, und die Reihenfolge ist zwingend: Die Datei muss hochgeladen werden, bevor die Nachricht gesendet wird, da die Nachrichten-Payload auf die vom Upload zurückgegebene Kennung verweist.

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 dann über die Verbindung eine Nachricht, 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 die Schritte für Upload und Referenz in einem einzelnen Aufruf zusammen und verarbeiten die Dateikennung intern. Die vollständige Nachrichtenstruktur finden Sie in der Spezifikation für multimodal_message. Da Ihre Anwendung den Upload durchführt, liegt ihr die Datei zu diesem Zeitpunkt bereits vor. Wenn Sie sie nur für das aktuelle Gespräch benötigen, genügt es, sie hochzuladen und auf die Kennung zu verweisen. Wenn sie über die Sitzung hinaus gespeichert werden soll, empfiehlt es sich, sie beim Upload aus Ihrer Anwendung heraus zu speichern. Sie kann auch später über den Post-Call-Webhook abgerufen werden, der im Abschnitt zum Kontext über Sitzungen hinweg behandelt wird.

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 lädt die Datei dann mit den Zugangsdaten Ihres verbundenen WhatsApp-Business-Kontos serverseitig herunter, 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 auch nie direkt vor. Es gibt keinen Weg, sie beim Upload zu erfassen, wie es im Web und auf Mobilgeräten möglich ist. Die Datei erreicht Ihr System über die file_url im Post-Call-Webhook, die auf die von ElevenLabs gespeicherte Kopie verweist. Die Medien-URL von Meta wird nur für die Aufnahme verwendet und niemals extern offengelegt. Die Abrufmechanik, einschließlich der zeitlichen Einschränkungen beim Download, 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 fügt die file_id plattformseitig hinzu. 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 auch keine multimodal_message über WebSocket. ElevenLabs übernimmt Zustellung, Speicherung und den Agenten-Turn.

Kontext über Sitzungen hinweg beibehalten

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

Diese Architekturgrenze sollten Sie bewusst bei der Planung berücksichtigen. Gespräche, bei denen multimodale Eingaben besonders wichtig sind – etwa wenn ein Kunde einen beschädigten Artikel fotografiert, ein Richtliniendokument hochlädt oder einen Standort teilt –, 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 der Agent sich bei seinem Rückruf an das Foto erinnert. Ohne explizites Kontextmanagement beginnt der Agent jedes Mal bei null, und der Kunde muss sich wiederholen. Das entsprechende Muster besteht aus zwei Teilen. Wenn ein Gespräch endet, liefert der Post-Call-Webhook das Transkript, Analyseergebnisse, alle von Ihnen definierten Felder zur strukturierten Datenerfassung und Datei-URLs für alle Dateien, die die Sitzung durchlaufen haben. Ihr Backend speichert relevante Informationen mit einer dauerhaften Kundenkennung wie Telefonnummer, Benutzer-ID oder Kontoschlüssel. Wenn der Kunde zurückkehrt, fügt Ihre Anwendung den gespeicherten Kontext über dynamische Variablen beim Sitzungsstart ein, sodass der Agent das Gespräch mit bereits vorhandenem Wissen beginnt. Bei dateibasierten Eingaben verweist insbesondere die Datei-URL in der Webhook-Payload auf die von ElevenLabs gespeicherte Kopie und ist nach Ende des Gesprächs der einzige Abrufweg. Die Kopie der Plattform ist auf die Sitzung beschränkt. Wenn Sie die Datei in einem zukünftigen Gespräch oder in Ihren 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 erläutert wird. Der Webhook übergibt Zustand nach außen. Dynamische Variablen bringen ihn zurück. Alles dazwischen liegt in der Verantwortung Ihres Systems – dort liegt die eigentliche Integrationsarbeit für jeden Anwendungsfall, bei dem Kunden zurückkehren, eskalieren oder eine Lösung fortsetzen.

Die Kontexteinbindung hängt vom Kanal ab

Der Einbindungsmechanismus variiert je nach Kanal, das zugrunde liegende Muster bleibt jedoch gleich. Bei Telefonie ruft ElevenLabs Ihren Server an, bevor die Verbindung hergestellt wird. So können Sie den Anrufer anhand seiner Nummer nachschlagen 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 in conversation_initiation_client_data beim Öffnen der Sitzung übergeben. ElevenAgents führt Sitzungen über verschiedene Kanäle hinweg nicht zu einem einzelnen Verlauf zusammen. Ein WhatsApp-Gespräch und ein Web-Gespräch sind separate Sitzungen, selbst wenn sie denselben Kunden betreffen. Da die Webhook-Ausgabe und die Einbindung dynamischer Variablen jedoch über alle Kanäle hinweg identisch funktionieren, kann eine einzige Persistenzschicht alle abdecken. Erstellen Sie sie einmal, und sie deckt jeden Kanal ab, auf dem der Agent läuft. Die Kontexteinbindung verarbeitet textförmige Daten: Namen, Bestell-IDs, Zusammenfassungen und strukturierte Felder. Dateien sind ein separater Fall und erfordern einen anderen Ansatz.

Dateien weiterführen

Dateien sind auf ein Gespräch beschränkt und bleiben nicht automatisch erhalten. Was Sie weiterführen sollten, hängt davon ab, ob das nächste Gespräch die Information aus einer Datei oder die Datei selbst benötigt. In den meisten Fällen wird nur die Information benötigt. Der Agent interpretiert eine hochgeladene Datei in dem Turn, in dem sie eingeht, schreibt diese Interpretation aber nicht automatisch an einen dauerhaften Ort. Die strukturierte Ausgabe stammt aus den Post-Call-Daten: dem Transkript, der Transkriptzusammenfassung und allen von Ihnen definierten Feldern für Datenerfassungsergebnisse. Wenn ein Kunde ein Foto einer gerissenen Türdichtung sendet und eine Woche später zurückkehrt, um den Schadenfall weiterzuverfolgen, benötigt der Agent das Foto nicht erneut. Er muss wissen, dass der Schadenfall eine gerissene Türdichtung betrifft. Sie extrahieren dies aus den Post-Call-Daten, speichern es mit der Kundenkennung und fügen es beim Zurückkehren des Kunden als dynamische Variable ein. Eine kurze Zusammenfassung oder einige strukturierte Felder reichen in der Regel aus.

Wenn Sie die Originaldatei doch benötigen – für eigene Unterlagen, Compliance oder nachgelagerte Systeme –, ist der Post-Call-Webhook der Abrufweg. 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 eingeht, statt dies aufzuschieben. Wenn Sie dieses Zeitfenster verpassen, während das Gespräch noch besteht, stellt die GET-Conversation-API als Fallback neue URLs aus. Planen Sie ein, dass file_input in manchen Fällen, etwa im Modus ohne Datenaufbewahrung, nicht vorhanden ist. Gehen Sie nicht davon aus, dass jeder dateibasierte Turn eine URL enthält.

Damit ist der gesamte Lebenszyklus abgedeckt: Eine Datei gelangt in die Sitzung, das Modell verarbeitet sie nativ, die strukturierte Ausgabe verlässt die Sitzung ü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 pro Kanal eine separate Implementierung erforderlich ist. Dateien werden normalisiert, mit dem Turn verknüpft und als native Blöcke statt als Textzusammenfassungen an das Modell übergeben. So erreichen räumliches Layout, visuelle Struktur und Dokumentformatierung das Modell unverändert. Der Kontext über Sitzungen hinweg folgt auf jedem Kanal demselben Muster: Der Post-Call-Webhook übergibt Zustand nach außen, dynamische Variablen bringen ihn zurück.

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