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 przez WhatsApp do agenta ds. zaopatrzenia i głosowo potwierdza adres dostawy. Agent przetwarza zdjęcie, rozpoznaje, czego brakuje, i składa pilne zamówienie — wszystko w jednej rozmowie. Workflow w firmach często zawierają kontekst, którego nie da się przekazać samymi słowami. Informacje potrzebne do obsługi zgłoszenia mogą mieć formę zdjęcia uszkodzonego przedmiotu lub PDF-a z polisą. Przekazanie ich bezpośrednio agentowi skraca rozmowę i przyspiesza rozwiązanie sprawy. Gdy klient może coś pokazać zamiast opisywać, agent szybciej rozwiązuje problem, bez proszenia go o zmianę kanału. Rohlik, jedna z największych europejskich platform spożywczych online, obsługuje swojego agenta przez telefon, stronę internetową, aplikację i WhatsApp — w sześciu językach — oraz automatycznie rozwiązuje 90% zapytań klientów. Dane multimodalne rozszerzają ten sam poziom skuteczności na sytuacje, w których klient musi coś pokazać, a nie opowiedzieć. ElevenAgents traktuje pliki jako pełnoprawne dane wejściowe dla tego samego agenta, który obsługuje już głos, WhatsApp, web 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 wpisie wyjaśniamy, co multimodalność oznacza na platformie, jak pliki trafiają z urządzenia klienta do kontekstu modelu, co obsługuje każdy kanał i 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 kontaktować się z klientami: 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 udostępniasz we wszystkich kanałach. W zależności od kanału zmieniają się dwie rzeczy: warstwa transportowa oraz 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 lub natywne integracje oparte na WebSocketach integracje. SMS-y łączą się przez natywną integrację z Twilio. WhatsApp łączy się po zaimportowaniu konta WhatsApp Business i włączeniu integracji dla agenta. Jeden agent może być jednocześnie wdrożony we wszystkich tych kanałach.

Dane wejściowe w postaci plików — obrazy i PDF-y — są obecnie obsługiwane w webie, na urządzeniach mobilnych i w WhatsAppie. Obsługa danych zależy od ich typu, a nie kanału: zdjęcie i wiadomość głosowa otrzymane w tej samej sesji WhatsAppa są przetwarzane zupełnie innymi ścieżkami, zanim dotrą do modelu. Niezależnie od kanału i typu danych wejściowych wszystkie trafiają do tej samej warstwy wstępnego przetwarzania, a potem jako natywny kontekst do modelu, gdzie podążają jedną z dwóch ścieżek.

Reprezentacja danych wejściowych: pliki i dane inline

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

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 kontekstowym, a nie jego pochodną reprezentację. Wymóg integracyjny jest prosty: przechwyć file_id zwrócone przez endpoint przesyłania i dołącz je do payloadu wiadomości. Jeśli wiadomość zostanie wysłana bez file_id, model nie ma odwołania do pliku — nawet jeśli przesłanie się udało. Pliki są przechowywane w zakresie rozmowy. Oznacza to, że wszystko, co ma przetrwać po sesji — sam plik, wyodrębnione pola czy uporządkowany wynik — musi zostać jawnie obsłużone przez twoją integrację. Mechanizm 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 transkrypcji, zanim uruchomi się model. Pinezka lokalizacji staje się współrzędnymi i opcjonalnym adresem, a kontakt — imieniem i nazwiskiem oraz numerem telefonu. Żadne z nich nie są zapisywane jako pliki ani nie generują odwołania do pliku. Te dane wejściowe trafiają bezpośrednio do transkrypcji.

Dlaczego to rozróżnienie jest ważne

Ten podział określa, na czym skupisz pracę nad integracją. Ścieżka inline nie wymaga od ciebie niczego w trakcie rozmowy: platforma normalizuje te dane wejściowe do tekstu, który trafia bezpośrednio do transkrypcji. Ścieżka oparta na plikach ma osobny punkt integracji. Zamiast konwertować zawartość pliku do tekstu przed uruchomieniem modelu, orkiestrator przekazuje surowy plik bezpośrednio do okna kontekstowego modelu. Model działa 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 na uwadze, dalsza część wpisu opisuje wdrożenie: jak skonfigurować agenta, jak pliki przechodzą przez każdy kanał i jak zachować kontekst między sesjami.

Konfiguracja danych multimodalnych 

Włączenie danych multimodalnych zaczyna się od tej samej konfiguracji agenta dla webu, urządzeń mobilnych i WhatsAppa. Dalej sposób przesyłania pliku i jego późniejszego pobierania zależy od kanału.

Włączanie danych wejściowych plików

Zanim dane wejściowe plików zaczną działać, w konfiguracji agenta muszą być ustawione dwie opcje. 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 być skonfigurowany z modelem obsługującym obrazy i dokumenty. Sama flaga nic nie daje, jeśli model bazowy nie przetwarza bloków obrazów lub dokumentów; przed testowaniem musisz ustawić oba elementy.

SDK i WebSocket

Dane wejściowe plików w webie lub na urządzeniach mobilnych 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 trzeba przesłać przed wysłaniem wiadomości, ponieważ payload wiadomości odwołuje się do identyfikatora zwróconego przez przesyłanie.

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ść odwołującą 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ą kroki przesyłania i odwołania w jedno wywołanie, wewnętrznie obsługując identyfikator pliku. 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 odwołać się do identyfikatora. Jeśli chcesz zachować go po sesji, najlepiej zapisać go z 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 WhatsAppie 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 logowania połączonego konta WhatsApp Business, by pobrać plik między serwerami, zapisać własną kopię i dołączyć go do rozmowy tak samo jak przy przesłaniu przez web lub SDK. Agent otrzymuje go jako dane multimodalne, a w transkrypcji zapisywane jest zdarzenie file_input.

Ponieważ twoja aplikacja nigdy nie obsługuje przesyłania, nie ma też bezpośrednio pliku. Nie możesz przechwycić go w momencie przesyłania, jak w webie i na urządzeniach mobilnych. Plik trafia do twojego systemu przez file_url w webhooku po rozmowie, który wskazuje kopię zapisaną przez ElevenLabs. Adres URL multimediów Meta służy tylko do pobrania i nigdy nie jest udostępniany na zewnątrz. Mechanika pobierania, w tym ograniczenia czasowe, jest opisana w sekcji o kontekście między sesjami.

W WhatsAppie klient wysyła plik na czacie. ElevenLabs pobiera go z Meta, zapisuje i przypisuje file_id po stronie platformy. Nie ma więc kroku przesyłania po stronie klienta. W przeciwieństwie do webu i urządzeń mobilnych 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.

Zachowywanie kontekstu między sesjami

ElevenAgents przetwarza każdą rozmowę niezależnie. Nic, co klient wyśle, ani nic, co agent rozwiąże podczas rozmowy, nie przechodzi automatycznie do kolejnej. Agent przekazuje twojemu systemowi wszystko z zakończonej rozmowy przez webhook po rozmowie, ale pamięć obejmująca wiele rozmów pozostaje poza ElevenLabs. Ciągłość należy do ciebie.

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 z polisą lub udostępnia lokalizację — często nie kończą się w jednej sesji. Klient, który wysłał zdjęcie uszkodzonej części i umówił oddzwonienie, oczekuje, że agent zapamięta zdjęcie, gdy klient zadzwoni ponownie. Bez jawnego zarządzania kontekstem agent za każdym razem zaczyna od zera, a klient musi się powtarzać. Ten wzorzec ma dwie części. Po zakończeniu rozmowy webhook po rozmowie przekazuje transkrypcję, wyniki analizy, zdefiniowane pola zbierania uporządkowanych danych oraz adresy URL plików, które przeszły przez sesję. Twój backend zapisuje istotne dane przy trwałym identyfikatorze 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 zaczyna rozmowę od tego, co już wie. W przypadku danych wejściowych opartych na plikach adres URL pliku w payloadzie webhooka wskazuje kopię przechowywaną przez ElevenLabs i jest jedyną ścieżką pobierania po zamknięciu rozmowy. Kopia platformy jest ograniczona do sesji, więc jeśli potrzebujesz pliku w przyszłej rozmowie lub we własnych systemach, musisz pobrać go z payloadu webhooka, zanim to okno się zamknie. To, jak szybko trzeba działać, zależy od polityki retencji opisanej w dokumentacji referencyjnej. Webhook przekazuje stan na zewnątrz. Zmienne dynamiczne przekazują go z powrotem. Wszystko pomiędzy jest odpowiedzialnością twojego systemu — i tam znajduje się właściwa praca integracyjna w każdym przypadku, gdy klienci wracają, eskalują sprawę lub wznawiają jej obsługę.

Wstrzykiwanie kontekstu zależy od kanału

Mechanizm wstrzykiwania różni się zależnie od kanału, ale jego podstawowy wzorzec pozostaje taki sam. W telefonii ElevenLabs wywołuje twój serwer, zanim połączenie zostanie zestawione, dając ci możliwość wyszukania dzwoniącego po numerze i zwrócenia zmiennych dynamicznych, takich jak imię, ID zamówienia lub poziom konta, zanim agent się odezwie. W WhatsAppie webhook przed wiadomością uruchamia się przy każdej wiadomości przychodzącej, dzięki czemu możesz wzbogacić ją o dane identyfikacyjne i kontekst biznesowy z twoich systemów, zanim przetworzy ją agent. W pozostałych przypadkach te same pola przekazywane są w conversation_initiation_client_data przy otwarciu sesji. ElevenAgents nie łączy sesji z różnych kanałów w jeden wątek. Rozmowa na WhatsAppie i rozmowa w webie to oddzielne sesje, nawet jeśli dotyczą tego samego klienta. Ponieważ jednak dane wyjściowe webhooka i wstrzykiwanie zmiennych dynamicznych działają identycznie we wszystkich kanałach, jedna warstwa trwałego przechowywania 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 uporządkowane pola. Pliki to osobny przypadek i wymagają innego podejścia.

Przenoszenie plików dalej

Pliki są ograniczone do jednej rozmowy i nie są zachowywane automatycznie. To, co przenieść dalej, zależy od tego, czy kolejna rozmowa potrzebuje informacji z pliku, czy samego pliku. W większości przypadków potrzebna jest tylko informacja. Agent interpretuje przesłany plik w turze, w której go otrzymuje, ale nie zapisuje tej interpretacji automatycznie w trwałym miejscu. Uporządkowane dane wyjściowe pochodzą z danych po rozmowie: transkrypcji, jej podsumowania 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 już zdjęcia. Musi wiedzieć, że zgłoszenie dotyczy pękniętej uszczelki drzwi. Wyodrębniasz to z danych po rozmowie, zapisujesz przy identyfikatorze klienta i wstrzykujesz jako zmienną dynamiczną, gdy klient wraca. Zwykle wystarczy krótkie podsumowanie lub kilka uporządkowanych pól.

Gdy potrzebujesz oryginalnego pliku — do własnych archiwów, celów zgodności lub systemów downstream — ścieżką pobierania jest webhook po rozmowie. Każdy przesłany plik pojawia się w transkrypcji 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 nadejdzie, zamiast odkładać to na później. Jeśli przegapisz to okno, gdy rozmowa nadal istnieje, API GET conversation ponownie wystawi aktualne adresy URL jako rozwiązanie awaryjne. Uwzględnij, że file_input może nie wystąpić w niektórych przypadkach, na przykład w trybie zerowej retencji, zamiast zakładać, że każda tura oparta na pliku zawiera adres URL.

To obejmuje cały cykl życia: plik trafia do sesji, model pracuje na nim natywnie, uporządkowane dane wyjściowe opuszczają system przez webhook, a twoja warstwa przechowywania decyduje, co agent będzie wiedział następnym razem.

Podsumowanie

Ta sama konfiguracja agenta obsługuje obrazy i PDF-y w webie, na urządzeniach mobilnych i w 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 układ przestrzenny, struktura wizualna i formatowanie dokumentu docierają do modelu bez zmian. Kontekst między sesjami działa tak samo w każdym kanale: webhook po rozmowie przekazuje stan na zewnątrz, a zmienne dynamiczne wprowadzają go z powrotem.

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