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 przez WhatsApp i głosowo potwierdza adres dostawy. Agent analizuje zdjęcie, ustala, czego brakuje, i składa pilne zamówienie — wszystko w jednej rozmowie. W firmowych workflow często pojawia się kontekst, którego nie da się przekazać samymi słowami. Informacja potrzebna do rozwiązania sprawy może mieć formę zdjęcia uszkodzonego przedmiotu lub PDF-a z regulaminem. Bezpośrednie przekazanie jej 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 internetowych platform spożywczych w Europie, obsługuje swojego agenta przez telefon, stronę internetową, aplikację i WhatsApp w sześciu językach, automatycznie rozwiązując 90% zapytań klientów. Dane multimodalne pozwalają utrzymać ten sam poziom rozwiązywania spraw tam, gdzie klient musi coś pokazać, a nie opisać. 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 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 działa w kanałach, których firmy już używają do kontaktu z klientami: aplikacjach webowych i mobilnych, platformach wsparcia, przez telefon, SMS, e-mail, WhatsApp 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 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 lub 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 jednocześnie działać we wszystkich tych warstwach transportowych.

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

Reprezentacja danych wejściowych: plikowa a inline

Niezależnie od typu danych wejściowych czy kanału platforma normalizuje każde dane 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 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 przechowuje plik, przypisuje mu file_id, a następnie wiąże ten identyfikator z turą użytkownika. Model obsługujący obraz lub dokument otrzymuje surowy plik w swoim oknie kontekstu zamiast jego pochodnej reprezentacji. Wymóg integracyjny jest prosty: przechwyć file_id zwrócony przez endpoint przesyłania i uwzględnij go w payloadzie wiadomości. Jeśli wiadomość zostanie wysłana bez file_id, model nie ma odwołania do pliku, nawet jeśli przesłanie się powiodło. Przechowywanie plików jest ograniczone do rozmowy. Oznacza to, że wszystko, co ma przetrwać poza sesją — 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 pozostałe. Głos i wiadomości głosowe są transkrybowane. Wpisany tekst, transkrybowana mowa, pinezki lokalizacji WhatsApp i wizytówki kontaktów są normalizowane do zwykłego tekstu w transkrypcie, zanim uruchomi się model. Pinezka lokalizacji staje się współrzędnymi i opcjonalnym adresem, a kontakt — nazwą i numerem telefonu. Żadne z nich nie jest przechowywane jako plik ani nie tworzy odwołania do pliku. Te dane znajdują się bezpośrednio w transkrypcie.

Dlaczego to rozróżnienie jest ważne

Ten podział określa, gdzie trzeba włożyć wysiłek w integrację. Ścieżka inline nie wymaga od ciebie niczego podczas rozmowy: platforma normalizuje te dane do tekstu i umieszcza je bezpośrednio w transkrypcie. Ścieżka oparta na plikach ma odrębny punkt integracji. Zamiast konwertować zawartość pliku do tekstu przed uruchomieniem modelu, orkiestrator przekazuje surowy plik bezpośrednio do okna kontekstu 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 rozróżnienie na uwadze, w dalszej części opisujemy wdrożenie: jak skonfigurować agenta, jak pliki przechodzą przez poszczególne kanały 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 WhatsApp. Dalej sposób przesyłania pliku i jego późniejszego pobierania zależy od kanału.

Włączanie danych plikowych

Aby dane plikowe działały, w konfiguracji agenta muszą być włączone dwa ustawienia. 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. Samo ustawienie nic nie daje, jeśli model bazowy nie potrafi przetwarzać bloków obrazu lub dokumentu — przed testami trzeba ustawić oba.

SDK i WebSocket

Dane plikowe w webie lub na urządzeniach mobilnych wymagają własnego klienta czatu zbudowanego na SDK albo surowego połączenia Agents WebSocket. Przepływ jest identyczny we wszystkich trzech przypadkach, a kolejność jest kluczowa: plik należy przesłać przed wysłaniem wiadomości, ponieważ jej payload 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  

Zobacz przesyłanie pliku — pełne żądanie i odpowiedź:

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ą kroki przesłania i odwołania w jedno wywołanie, obsługując identyfikator pliku wewnętrznie. Zobacz specyfikację multimodal_message — znajdziesz tam pełny format wiadomości. 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 plik ma przetrwać 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 WhatsApp twoja aplikacja nie bierze udziału 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, aby pobrać plik między serwerami, zapisuje własną kopię i dołącza ją do rozmowy tak samo jak przy przesłaniu z webu lub SDK. Agent otrzymuje go jako dane multimodalne, a transkrypt rejestruje zdarzenie file_input.

Ponieważ twoja aplikacja nigdy nie obsługuje przesyłania, nie ma też bezpośrednio pliku. Nie ma możliwości przechwycenia go podczas 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ę przechowywaną przez ElevenLabs. Adres URL mediów Meta służy tylko 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.

W WhatsApp klient wysyła plik na czacie. ElevenLabs pobiera go z Meta, zapisuje i przypisuje file_id po stronie platformy. Oznacza to, że nie ma 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.

Przenoszenie kontekstu między sesjami

ElevenAgents przetwarza każdą rozmowę niezależnie. Nic, co wysyła klient, 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 granicą ElevenLabs. Ciągłość należy do ciebie.

Warto świadomie zaprojektować tę granicę architektury. Rozmowy, w których dane multimodalne mają największe znaczenie — gdy klient fotografuje uszkodzony przedmiot, przesyła dokument z regulaminem 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 oddzwonienie, oczekuje, że agent będzie pamię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 składa się z dwóch części. Po zakończeniu rozmowy webhook po rozmowie dostarcza transkrypt, wyniki analizy, zdefiniowane przez ciebie pola zbierania danych strukturalnych 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, identyfikator 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ę z tym, co już wie. W przypadku danych opartych na plikach adres URL pliku w payloadzie webhooka wskazuje kopię przechowywaną przez ElevenLabs i jest jedyną drogą 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, musisz pobrać go z payloadu webhooka, zanim to okno się zamknie. To, jak szybko trzeba działać, zależy od zasad retencji opisanych w dokumentacji referencyjnej. Webhook wynosi stan na zewnątrz. Zmienne dynamiczne wnoszą go z powrotem. Wszystko pomiędzy jest odpowiedzialnością twojego systemu — i właśnie tam znajduje się główna praca integracyjna w każdym zastosowaniu, w którym klienci wracają, eskalują sprawę lub wznawiają jej rozwiązanie.

Wstrzykiwanie kontekstu zależy od kanału

Mechanizm wstrzykiwania różni się zależnie od kanału, ale podstawowy wzorzec jest stały. 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ę, identyfikator zamówienia lub poziom konta, zanim agent się odezwie. W WhatsApp webhook przed wiadomością uruchamia się przy każdej wiadomości przychodzącej, co pozwala wzbogacić ją o dane tożsamości i kontekst biznesowy z twoich systemów, zanim agent ją przetworzy. W pozostałych przypadkach te same pola są przekazywane w conversation_initiation_client_data podczas otwierania sesji. ElevenAgents nie łączy sesji z różnych kanałów w jeden wątek. Rozmowa w WhatsApp i rozmowa w webie to osobne 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, identyfikatory zamówień, podsumowania i pola strukturalne. Pliki to osobny przypadek, wymagający innego podejścia.

Przenoszenie plików dalej

Pliki są ograniczone do jednej rozmowy i nie są automatycznie zachowywane. 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 wystarczy informacja. 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, jego podsumowania oraz 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, aby sprawdzić status zgłoszenia, 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 przy identyfikatorze klienta i wstrzykujesz jako zmienną dynamiczną, gdy klient wraca. Zwykle wystarcza krótkie podsumowanie lub kilka pól strukturalnych.

Gdy potrzebujesz oryginalnego pliku — do własnych rejestrów, zgodności z przepisami 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 jest ważny przez piętnaście minut, więc pobierz i zapisz plik po otrzymaniu webhooka, zamiast odkładać to na później. Jeśli przegapisz to okno, gdy rozmowa nadal istnieje, API GET conversation ponownie wystawi świeże adresy URL jako rozwiązanie awaryjne. Uwzględnij, że file_input może nie występować 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 cały cykl życia: plik trafia do sesji, model przetwarza go natywnie, dane strukturalne wychodzą przez webhook, a twoja warstwa trwałego 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 WhatsApp, bez osobnego wdrożenia 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 wynosi stan na zewnątrz, a zmienne dynamiczne wnoszą go z powrotem.

Jeśli tworzysz w ElevenLabs Agents i chcesz, aby 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.