Obsługa obrazów i dokumentów w ElevenAgents

Kierownik budowy zauważa brak materiałów na placu budowy. Robi zdjęcie, wysyła je agentowi ds. zaopatrzenia na WhatsAppie i głosowo potwierdza adres dostawy. Agent analizuje zdjęcie, ustala, czego brakuje, i składa pilne zamówienie — wszystko w jednej rozmowie. Workflow w firmach często wymagają kontekstu, którego same słowa nie przekażą. Informacje potrzebne do rozwiązania zgłoszenia mogą mieć formę zdjęcia uszkodzonego przedmiotu lub PDF-a z polisą. Bezpośrednie przekazanie ich agentowi skraca rozmowę i przyspiesza rozwiązanie sprawy. Gdy klient może coś pokazać zamiast opisywać, agent szybciej diagnozuje problem, bez proszenia o zmianę kanału. Rohlik, jedna z największych internetowych platform spożywczych w Europie, obsługuje swojego agenta przez telefon, stronę, aplikację i WhatsApp w sześciu językach oraz automatycznie rozwiązuje 90% zapytań klientów. Dane multimodalne pozwalają utrzymać ten sam poziom skuteczności także wtedy, gdy klient musi coś pokazać, a nie opisać. ElevenAgents traktuje pliki jako pełnoprawne dane wejściowe tego samego agenta, który obsługuje już głos, WhatsApp, stronę i urządzenia mobilne. Pliki trafiają do modelu bazowego jako natywne wiadomości, więc jeden agent obsługuje każdy typ danych wejściowych w jednym wątku rozmowy. 

W tym artykule wyjaśniamy, czym jest multimodalność na platformie, jak pliki trafiają z urządzenia klienta do kontekstu modelu, co obsługuje każdy kanał oraz jak zachować kontekst między sesjami, gdy klient wraca.

Kanały i dane wejściowe 

ElevenAgents opiera się na kanałach, których firmy już używają, by docierać do klientów: aplikacjach webowych i mobilnych, platformach wsparcia, telefonie, SMS-ach, e-mailu, WhatsAppie i innych. Konfigurację agenta — prompt, model, narzędzia, bazę wiedzy i głos — definiujesz raz i współdzielisz we wszystkich kanałach. Zależnie od kanału różnią się dwie rzeczy: warstwa transportowa i obsługiwane typy danych wejściowych. Aplikacje webowe i mobilne łączą się przez osadzany widget, jedno z SDK lub Agents WebSocket. Rozmowy telefoniczne łączą się przez natywne Twilio, SIP trunking albo natywne integracje oparte na websocketach integracje. SMS-y łączą się przez natywną integrację Twilio. WhatsApp łączy się po zaimportowaniu konta WhatsApp Business i włączeniu integracji dla agenta. Jeden agent może działać równocześnie we wszystkich tych warstwach transportowych.

Dane wejściowe w postaci plików — obrazów i PDF-ów — są obecnie obsługiwane w kanale webowym, mobilnym i na WhatsAppie. Obsługa danych zależy od ich typu, a nie kanału: zdjęcie i wiadomość głosowa z tej samej sesji WhatsAppa przechodzą przez zupełnie inne potoki przetwarzania, zanim dotrą do modelu. Niezależnie od kanału i typu danych wejściowych wszystko trafia do tej samej warstwy wstępnego przetwarzania, a następnie do modelu jako natywny kontekst — jedną z dwóch ścieżek.

Reprezentacja danych wejściowych: plikowa a inline

Niezależnie od typu danych wejściowych i kanału platforma normalizuje je do jednej z dwóch wewnętrznych reprezentacji, zanim przekaże je do modelu. Ta klasyfikacja określa, jak dane są kodowane w oknie kontekstu modelu i co musi obsłużyć twoja integracja.

Dane wejściowe oparte na plikach

Obrazy i PDF-y są przekazywane do modelu jako natywne odwołania do plików, a nie podsumowania tekstowe. Platforma zapisuje plik, przypisuje mu file_id i wiąże ten identyfikator z turą użytkownika. Model obsługujący obrazy lub dokumenty otrzymuje surowy plik w swoim oknie kontekstu, a nie jego pochodną reprezentację. Wymóg dla integracji jest prosty: przechwyć file_id zwrócone przez endpoint przesyłania i dodaj je do payloadu wiadomości. Jeśli wiadomość zostanie wysłana bez file_id, model nie ma odwołania do pliku, nawet jeśli przesyłanie się udało. Pliki są przechowywane w zakresie danej rozmowy. Oznacza to, że wszystko, co ma przetrwać po sesji — sam plik, wyodrębnione pola lub dane strukturalne — musi zostać jawnie obsłużone przez twoją integrację. Sposób zależy od kanału i zastosowania.

Inline

Druga reprezentacja to inline i obejmuje wszystko inne. Głos i wiadomości głosowe są transkrybowane. Wpisany tekst, transkrybowana mowa, pinezki lokalizacji WhatsAppa i wizytówki kontaktów są normalizowane do zwykłego tekstu w transkrypcie przed uruchomieniem modelu. Pinezka lokalizacji staje się współrzędnymi i opcjonalnym adresem, a kontakt — imieniem i nazwiskiem oraz numerem telefonu. Żadne z tych danych nie są zapisywane jako pliki ani nie tworzą odwołania do pliku. Trafiają bezpośrednio do transkryptu.

Dlaczego to rozróżnienie jest ważne

Ten podział określa, gdzie potrzebny jest wysiłek przy integracji. Ścieżka inline nie wymaga od ciebie niczego podczas rozmowy: platforma normalizuje te dane do tekstu i zapisuje je bezpośrednio w transkrypcie. Ścieżka oparta na plikach ma osobny zakres integracji. Orkiestrator nie konwertuje zawartości pliku na tekst przed uruchomieniem modelu, lecz przekazuje surowy plik bezpośrednio do okna kontekstu modelu. Model pracuje na strukturze pliku, a nie na pochodnej reprezentacji tekstowej czy opisie, zachowując relacje przestrzenne, układ wizualny i formatowanie dokumentu, które w innym przypadku zostałyby utracone. Mając to rozróżnienie na uwadze, w dalszej części opisujemy wdrożenie: konfigurację agenta, przepływ plików przez każdy kanał i zachowanie kontekstu między sesjami.

Konfiguracja danych multimodalnych 

Włączenie danych multimodalnych zaczyna się od tej samej konfiguracji agenta dla kanału webowego, mobilnego i WhatsAppa. Dalszy sposób przesyłania pliku i pobierania go później zależy od kanału.

Włączanie danych plikowych

Zanim dane plikowe zaczną działać, w konfiguracji agenta muszą być ustawione dwie rzeczy. Najpierw ustaw conversation_config.conversation.file_input.enabled na True, przez API podczas tworzenia agenta lub w panelu w Settings > Advanced Settings > File Input. Po drugie, agent musi korzystać z modelu obsługującego obrazy i dokumenty. Sama flaga nic nie zmieni, jeśli model bazowy nie może przetwarzać bloków obrazów lub dokumentów — przed testami ustaw oba elementy.

SDK i WebSocket

Dane plikowe w kanale webowym lub mobilnym wymagają własnego klienta czatu opartego na SDK albo surowego połączenia Agents WebSocket. Przepływ jest identyczny we wszystkich trzech przypadkach, a kolejność jest bezwzględnie wymagana: plik musisz przesłać przed wysłaniem wiadomości, ponieważ payload wiadomości odwołuje się do identyfikatora zwróconego przy przesyłaniu.

Najpierw prześlij plik:

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  

Pełne żądanie i odpowiedź znajdziesz w sekcji przesyłanie pliku:

Następnie wyślij przez połączenie wiadomość, która odwołuje się do zwróconego file_id:

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

SDK łączą przesyłanie i odwołanie w jedno wywołanie, obsługując identyfikator pliku wewnętrznie. Pełny format wiadomości znajdziesz w specyfikacji multimodal_message. Ponieważ to twoja aplikacja przesyła plik, masz go już w tym momencie. Jeśli potrzebujesz go tylko w bieżącej rozmowie, wystarczy przesłać go i podać identyfikator. Jeśli chcesz zachować go po sesji, najlepiej zapisać go w aplikacji podczas przesyłania. Możesz też pobrać go później przez webhook po rozmowie, opisany w sekcji o kontekście między sesjami.

WhatsApp

W przypadku WhatsAppa twoja aplikacja nie uczestniczy w przesyłaniu. Gdy klient wysyła obraz, dokument lub naklejkę, plik najpierw trafia do infrastruktury Meta. Meta powiadamia ElevenLabs przez webhook WhatsApp Business API, a ElevenLabs używa danych dostępowych połączonego konta WhatsApp Business, by pobrać plik między serwerami, zapisuje własną kopię i dołącza ją do rozmowy tak samo jak po przesłaniu przez kanał webowy lub SDK. Agent otrzymuje go jako dane multimodalne, a transkrypt zapisuje zdarzenie file_input.

Ponieważ twoja aplikacja nigdy nie obsługuje przesyłania, nie ma też bezpośrednio pliku. Nie możesz przechwycić go przy przesyłaniu, jak w kanale webowym i mobilnym. Plik trafia do twojego systemu przez file_url w webhooku po rozmowie, który wskazuje kopię zapisaną przez ElevenLabs. Adres URL mediów Meta służy wyłącznie do pobrania pliku i nigdy nie jest udostępniany na zewnątrz. Mechanizm pobierania, w tym ograniczenia czasowe, opisujemy w sekcji o kontekście między sesjami.

Na WhatsAppie klient wysyła plik na czacie. ElevenLabs pobiera go z Meta, zapisuje i dołącza file_id po stronie platformy. Oznacza to, że nie ma kroku przesyłania po stronie klienta. W przeciwieństwie do kanału webowego i mobilnego twoja aplikacja nie wywołuje POST /v1/convai/conversations/{id}/files ani nie wysyła multimodal_message przez WebSocket. ElevenLabs obsługuje dostarczenie, przechowywanie i turę agenta.

Przenoszenie kontekstu między sesjami

ElevenAgents przetwarza każdą rozmowę niezależnie. Nic, co wyśle klient, ani nic, co agent rozwiąże podczas rozmowy, nie przechodzi automatycznie do kolejnej. Agent przekazuje twojemu systemowi wszystkie dane z zakończonej rozmowy przez webhook po rozmowie, ale pamięć obejmująca wiele rozmów znajduje się poza granicą ElevenLabs. To ty odpowiadasz za ciągłość.

Warto świadomie zaprojektować system wokół tej granicy architektonicznej. Rozmowy, w których dane multimodalne są najważniejsze — gdy klient fotografuje uszkodzony przedmiot, przesyła dokument polisy lub udostępnia lokalizację — często nie kończą się w jednej sesji. Klient, który wysyła zdjęcie uszkodzonej części i umawia rozmowę zwrotną, oczekuje, że agent zapamięta zdjęcie, gdy oddzwoni. Bez jawnego zarządzania kontekstem agent za każdym razem zaczyna od zera, a klient musi się powtarzać. Ten wzorzec ma dwie części. Gdy rozmowa się kończy, webhook po rozmowie przekazuje transkrypt, wyniki analizy, zdefiniowane pola zbierania danych strukturalnych oraz adresy URL plików, które przeszły przez sesję. Twój backend zapisuje istotne dane pod trwałym identyfikatorem klienta, takim jak numer telefonu, ID użytkownika lub klucz konta. Gdy klient wraca, aplikacja wstrzykuje zapisany kontekst na początku sesji przez zmienne dynamiczne, dzięki czemu agent rozpoczyna rozmowę z informacjami, które już zna. W przypadku danych opartych na plikach adres URL pliku w payloadzie webhooka wskazuje kopię zapisaną przez ElevenLabs i jest jedyną ścieżką pobrania po zamknięciu rozmowy. Kopia na platformie jest ograniczona do sesji, więc jeśli potrzebujesz pliku w przyszłej rozmowie lub we własnych systemach, pobierz go z payloadu webhooka, zanim to okno się zamknie. To, jak szybko musisz działać, zależy od polityki retencji opisanej w dokumentacji referencyjnej. Webhook przekazuje stan na zewnątrz. Zmienne dynamiczne przekazują go z powrotem. Za wszystko pomiędzy odpowiada twój system — i tam jest właściwa praca integracyjna w każdym przypadku, gdy klienci wracają, eskalują sprawę lub wznawiają jej rozwiązywanie.

Wstrzykiwanie kontekstu zależy od kanału

Mechanizm wstrzykiwania różni się zależnie od kanału, ale podstawowy wzorzec jest spójny. W telefonii ElevenLabs wywołuje twój serwer przed połączeniem rozmowy, dając ci możliwość wyszukania dzwoniącego po numerze i zwrócenia zmiennych dynamicznych, takich jak imię, ID zamówienia czy poziom konta, zanim agent się odezwie. Na WhatsAppie webhook przed wiadomością uruchamia się przy każdej wiadomości przychodzącej, co pozwala wzbogacić ją o tożsamość i kontekst biznesowy z twoich systemów, zanim agent ją przetworzy. W innych przypadkach te same pola przekazujesz w conversation_initiation_client_data podczas otwierania sesji. ElevenAgents nie łączy sesji z różnych kanałów w jeden wątek. Rozmowa na WhatsAppie i rozmowa w kanale webowym to oddzielne sesje, nawet jeśli dotyczą tego samego klienta. Jednak ponieważ dane z webhooka i wstrzykiwanie zmiennych dynamicznych działają identycznie we wszystkich kanałach, jedna warstwa trwałego zapisu obsługuje je wszystkie. Zbuduj ją raz, a obejmie każdy kanał, w którym działa agent. Wstrzykiwanie kontekstu obsługuje dane tekstowe: imiona, ID zamówień, podsumowania i pola strukturalne. Pliki to osobny przypadek, wymagający innego podejścia.

Przenoszenie plików

Pliki są ograniczone do jednej rozmowy i nie są zachowywane automatycznie. To, co należy przenieść dalej, zależy od tego, czy kolejna rozmowa potrzebuje informacji z pliku, czy samego pliku. W większości przypadków wystarczą informacje. Agent interpretuje przesłany plik w turze, w której go otrzymuje, ale nie zapisuje automatycznie tej interpretacji w trwałym miejscu. Dane strukturalne pochodzą z danych po rozmowie: transkryptu, podsumowania transkryptu i zdefiniowanych przez ciebie pól wyników zbierania danych. Jeśli klient wyśle zdjęcie pękniętej uszczelki drzwi i wróci tydzień później, by dopytać o zgłoszenie, agent nie potrzebuje ponownie zdjęcia. Musi wiedzieć, że zgłoszenie dotyczy pękniętej uszczelki drzwi. Wyodrębniasz to z danych po rozmowie, zapisujesz pod identyfikatorem klienta i wstrzykujesz jako zmienną dynamiczną, gdy klient wróci. Zwykle wystarczy krótkie podsumowanie lub kilka pól strukturalnych.

Gdy potrzebujesz oryginalnego pliku — do własnych rejestrów, celów zgodności lub systemów downstream — ścieżką pobrania jest webhook po rozmowie. Każdy przesłany plik pojawia się w transkrypcie jako zdarzenie file_input z podpisanym adresem URL pliku. Ten adres URL jest ważny przez piętnaście minut, więc pobierz i zapisz plik, gdy webhook dotrze, zamiast odkładać to na później. Jeśli przegapisz to okno, gdy rozmowa nadal istnieje, jako rozwiązanie zapasowe API GET conversation ponownie wystawi aktualne adresy URL. Uwzględnij, że file_input może nie występować w niektórych przypadkach, takich jak tryb zerowej retencji, zamiast zakładać, że każda tura oparta na pliku zawiera adres URL.

To cały cykl życia: plik trafia do sesji, model natywnie na nim pracuje, dane strukturalne wychodzą przez webhook, a twoja warstwa trwałego zapisu decyduje, co agent będzie wiedział następnym razem.

Podsumowanie

Ta sama konfiguracja agenta przyjmuje obrazy i PDF-y w kanale webowym, mobilnym i na WhatsAppie, bez osobnej implementacji dla każdego kanału. Pliki są normalizowane, wiązane z turą i przekazywane do modelu jako natywne bloki, a nie podsumowania tekstowe, dzięki czemu model otrzymuje nienaruszony układ przestrzenny, strukturę wizualną i formatowanie dokumentu. Kontekst między sesjami działa tak samo w każdym kanale: webhook po rozmowie przekazuje stan na zewnątrz, a zmienne dynamiczne przekazują go z powrotem.

Jeśli tworzysz rozwiązanie z ElevenLabs Agents i chcesz, by twój agent pracował z obrazami i dokumentami obok głosu i tekstu, włącz dane multimodalne i daj nam znać, co o tym myślisz.