Customer Agent API (Beta)

Czego się dowiesz?

Czym jest interfejs API Customer Agent, czym zajmuje się każda grupa i jak zacząć do niej dzwonić. API pozwala skonfigurować Customer Agenta, sprawdzić, co robi w środowisku produkcyjnym i uruchomić go w sposób programistyczny – bezpośrednio przez HTTP, razem z pozostałą częścią publicznego API Klaviyo.

Uwaga: API Customer Agent są w wersji beta. Punkty końcowe i schematy mogą się zmienić przed udostępnieniem ogólnym. Interfejsy API w wersji beta nie są przeznaczone do użytku produkcyjnego — szczegóły znajdziesz w zasadach wersjonowania i wycofywania Klaviyo.

Co umożliwia interfejs API

API Customer Agent obejmują cztery zadania:

1. Skonfiguruj agenta – przeczytaj lub zaktualizuj dane agenta oraz jego umiejętności, narzędzia, źródła wiedzy i sekrety.
2. Odczytuj konwersacje wwersji produkcyjnej – sporządzaj listę i kontroluj konwersacje z Customer Agentem.
3. Raportuj na temat skuteczności – wolumenu ściągań, wskaźnika rozwiązań i metryki na umiejętność.
4. Uruchamiaj agenta na jedną turę – wyślij zwrot konwersacji i uzyskaj odpowiedź agenta z powrotem. Jest to prymityw bez głowy – przydatny do osadzania agenta na własnej powierzchni.

Ponieważ te cztery zadania działają w ramach jednego API, możesz połączyć je w ciągłą pętlę treningową: pobierz to, co się wydarzyło, zdiagnozuj, co zadziałało, a co nie, a potem wdroż z powrotem zmiany konfiguracji. Dzięki bezpiecznie skonfigurowanej integracji API lub połączeniu MCP asystent AI, taki jak Claude lub ChatGPT, może pomóc czytać rozmowy, znajdować wzorce niepowodzeń i proponować zmiany w Twoich umiejętnościach, narzędziach, wiedzy i wytycznych.

Uwierzytelnianie i dostęp

Użyj prywatnego klucza API Klaviyo z zakresem agents, aby wywoływać te punkty końcowe. Customer Agent musi być już włączony na Twoim koncie.

Gdy tworzysz klucz, wybierasz poziom dostępu dla zakresu agents:

Wybierz tylko do odczytu, jeśli integracje ma tylko obserwować agenta (np. raportowanie pulpitu). Jeśli chcesz skonfigurować agenta lub uruchomić tury konwersacji, wybierz odczyt/zapis.

1. Przejdź do Ustawienia > Klucze API i kliknij Utwórz prywatny klucz API.
2. Wpisz nazwę prywatnego klucza API i wybierz klucz niestandardowy.
3. W wierszu Agenci wybierz Dostęp do odczytu lub Pełny dostęp dla swojej integracji, korzystając z powyższej tabeli.
4. Kliknij Utwórz, a następnie kliknij ikonę kopiowania i zapisz klucz w bezpiecznym miejscu. Nie możesz wyświetlić tego klucza ponownie po opuszczeniu strony potwierdzenia.

Aby dowiedzieć się więcej, zobacz jak utworzyć lub sklonować prywatny klucz API.

Wysyłaj żądania API ze swojego serwera do https://a.klaviyo.com i dołącz ten nagłówek autoryzacji. Nie umieszczaj klucza prywatnego w kodzie przeglądarki ani w aplikacjach skierowanych do klientów:

Authorization: Klaviyo-API-Key your-private-api-key

Każde żądanie musi również zawierać nagłówek wersji beta:

revision: 2026-10-15.pre

Bez nagłówka wersji beta wniosek zostanie odrzucony.

Limity szybkości

Limity szybkości zależą od grupy punktów końcowych:

• Agent, umiejętności, narzędzia, wiedza, tajemnice i odpowiedzi: limit skokowy 10 żądań na sekundę i limit stały 150 żądań na minutę.
• Konwersacje, wiadomości w konwersacjach i raporty: limit w serii 3 żądania na sekundę i stały limit 60 żądań na minutę.

Format żądania

Korzystaj z konwencji żądań JSON:API w Klaviyo, z osobnym formatem dla przesyłania plików:

• Typ treści: application/vnd.api+json dla żądań JSON. Użyj multipart/form-data dla POST /api/agent-knowledge-files.
• Stronicowane kolekcje używają page[cursor] i page[size] (domyślnie 50, maks. 100, tylko do przodu). Podążaj za links.next, aż będzie puste, aby pobrać pozostałe strony.
• Filtrowanie używa obsługiwanych pól i operatorów wymienionych w dokumentacji referencyjnej każdego punktu końcowego. Kolejność sortowania zależy od punktu końcowego: rozmowy są sortowane od najnowszych, wiadomości — od najstarszych, a umiejętności i narzędzia — według identyfikatora.

punkt końcowy grupy

Agent

Na firmę przypada maksymalnie 1 Customer Agent. Wywołaj GET /api/customer-agents, aby znaleźć jego identyfikator, a następnie użyj tego identyfikatora w adresie URL dla GET lub PATCH. Lista jest pusta, jeśli Customer Agent nie jest włączony na koncie.

Umiejętności agenta

Możesz odczytywać gotowe i niestandardowe umiejętności. Tylko niestandardowe umiejętności można aktualizować lub usuwać. Ustaw status niestandardowej umiejętności na draft, aby ją przygotować lub wstrzymać, albo na live, aby ją aktywować.

Narzędzia agenta

Tylko niestandardowe narzędzia można aktualizować lub usuwać. Po utworzeniu zewnętrznego narzędzia HTTP powiąż je z niestandardową umiejętnością za pomocą relacji agent-tools tej umiejętności. Narzędzie nie jest dostępne dla tej umiejętności, dopóki nie zostanie powiązane.

Wiedza agenta

Twórz fragmenty tekstu, strony internetowe, pary Q&A lub foldery, ustawiając source.source_type na snippet, webpage, qa lub folder. Aby dodać file, użyj osobnego punktu końcowego przesyłania plików.

Sekrety agenta

Zaszyfrowane wpisy tajne używane przez narzędzia niestandardowe. Lista wyników zwraca tylko bezpieczne metadane – sama wartość sekretu nigdy nie jest zwracana.

Konwersacje

Czytaj rozmowy, które agent odbył z klientami, lub utwórz rozmowę, aby przejść ją za pomocą API. Jedna rozmowa może obejmować wiele wiadomości przez długi okres. Lista może zawierać rozmowy na żywo i podglądowe; użyj filter=equals(mode,"live"), aby ograniczyć ją do rozmów na żywo.

Raporty

Zbiorcze metryki, ograniczone do firmy wysyłającej żądanie. Oba poniższe raporty to punkty końcowe POST: przekaż parametry raportu w treści żądania. Wymagają uprawnienia agents:read, więc klucz tylko do odczytu może je uruchamiać.

Uruchom agenta

Jest to prymitywna procedura osadzania Customer Agenta we własnej powierzchni (aplikacji, Centrum pomocy lub panelu wsparcia stworzonego przez partnera).

Utwórz otwartą konwersację z POST /api/customer-agent-conversations przed uruchomieniem tury. Punkt końcowy odpowiedzi akceptuje tylko rozmowy utworzone przez API. Zamknięta rozmowa lub rozmowa, która została już przekierowana do Twojego zespołu, nie może przyjmować kolejnych odpowiedzi.

Co nadal wymaga interfejsu użytkownika Klaviyo?

Niektóre kroki konfiguracji nie są jeszcze dostępne w interfejsie API:

• Konfiguracja kanału (czat online, e-mail, SMS, WhatsApp) — Konfiguracja kanał działa w ustawieniach platformy Klaviyo.
• Staje się aktywna w każdym kanale — włącznik/wyłącznik na każdy kanał pozostaje w interfejsie użytkownika.
• Wybór Helpdesk — w Customer Agent otwórz kanał w sekcji Kanały i skonfiguruj sekcję Przekazanie. Aby poznać szczegóły, zobacz Zarządzanie ustawieniami Customer Agent.

Typowa organizacja pracy

Skonfiguruj raz, a potem zarządzaj

1. Utwórz prywatny klucz API z zakresem agents i dostępem do odczytu/zapisu w Klaviyo.
2. Pobierz bieżący stan — GET /api/customer-agents, aby znaleźć identyfikator agenta, a następnie pobierz agenta oraz listy umiejętności, narzędzi i wiedzy. Aby odczytać wszystkie strony, przejdź za linkami stronicowania.
3. Wprowadź zmiany — w razie potrzeby twórz lub aktualizuj umiejętności niestandardowe, narzędzia, wiedzę i sekrety. Powiąż nowe narzędzia z umiejętnościami, które z nich korzystają, i ustaw dla umiejętności niestandardowych status: live, gdy będziesz gotowy/gotowa je aktywować.
4. Sprawdź wydajność – wypisz ostatnie konwersacje i pobierz raport wartości, aby zobaczyć wyniki agenta.
5. Powtarzaj.

Trenuj swojego agenta w pętli

Interfejsy API mają na celu zamknięcie pętli między działaniami agenta w środowisku produkcyjnym a konfiguracją. Typowa pętla:

1. Pobierz ostatnie rozmowy — wykonaj GET dla conversations przefiltrowanych według created_at i status, dodając equals(mode,"live") do filtra dla rozmów produkcyjnych. Pobierz customer-agent-messages dla każdej rozmowy i podążaj za links.next, aby odczytać każdą stronę.
2. Zdiagnozuj – każdą konwersację klasyfikuj jako udaną lub nieudaną. Szukaj wzorców: czy eskalacje koncentrują się wokół tematu? Czy niektóre umiejętności są routowane, kiedy nie powinny? Czy agent nie posiada potrzebnej mu wiedzy?
3. Metryka „pull” – raport wartości dotyczący wolumenu i wskaźnika rozwiązań, plus raport wartości umiejętności dla podziału na umiejętności. Potwierdź wzorce blokad łącznie.
4. Zaproponuj zmiany – na podstawie wzorców niepowodzeń zdecyduj, co zmienić: edytuj instrukcje umiejętności, dodaj wycinek wiedzy, utwórz nowe niestandardowe narzędzie, zaostrz regułę tonów, dodaj wyzwalacz eskalacji wiadomości.
5. Zastosuj zmiany – POSTÓJ umiejętności, których one dotyczą, Opublikuj POST nowe źródła wiedzy itp.
6. Zapętl. Powtórz w następnym oknie konwersacji.

Możesz użyć asystenta AI, takiego jak Claude, ChatGPT lub Cursor, aby pobierać rozmowy, znajdować luki, proponować konkretne poprawki i wprowadzać zmiany za Twoją zgodą. Podłącz go przez serwer Klaviyo MCP lub własne integracje API i przechowuj prywatne klucze API w bezpiecznej konfiguracji, a nie w promptach. Serwer MCP obsługuje wiele z tych zadań, ale tworzenie lub aktualizowanie sekretów oraz przesyłanie plików wiedzy wymaga bezpośrednich wywołań API.

Osadź agenta na swojej własnej powierzchni

Użyj mode: preview do testowania bez rozliczeń i bez metryk produkcyjnych. mode: live służy do rzeczywistych interakcji kupujących i jest wliczane do rozliczeń oraz metryk produkcyjnych. Powyższe ostrzeżenie dotyczące używania wersji beta nadal obowiązuje.

1. Utwórz klucz o zakresie agenta (do odczytu/zapisu).
2. Utwórz konwersację — z twojego serwera wyślij żądanie POST do /api/customer-agent-conversations z wybranym mode. Zapisz zwrócony identyfikator rozmowy.
3. Otwórz konwersację w interfejsie użytkownika – zbierz opinie kupujących.
4. Uruchom turę — ze swojego serwera wyślij POST do /api/customer-agent-responses z parametrami mode, messages oraz zapisanym ID w data.relationships.conversation.data.id. Użyj typu relacji customer-agent-conversation. Uwzględnij historię rozmowy w messages, kończąc ją ostatnią wiadomością kupującego z role: user.
5. Renderuj odpowiedź — przetwarzaj zwrócone zdarzenia po kolei i wyświetlaj w interfejsie wiadomości agenta oraz wszystkie obsługiwane ustrukturyzowane dane. Obsłuż zdarzenia przekazania w swoich integracjach. API zwraca zdarzenia razem, bez strumieniowania; nie dostarcza ich przez kanał.
6. Powtórz dla każdej tury, używając tego samego identyfikatora rozmowy i trybu, gdy rozmowa jest otwarta. Po twardym lub cichym przekazaniu przestań prosić agenta o odpowiedzi i skieruj kupującego do Twojego zespołu wsparcia.

Najczęściej zadawane pytania

Czy istnieje serwer MCP?

Tak. Zdalnie hostowany serwer Klaviyo MCP zawiera narzędzia Customer Agent do umiejętności, narzędzi, wiedzy, metadanych sekretów, rozmów, raportów oraz uruchamiania agenta. Utworzenie rozmowy, utworzenie lub aktualizacja sekretów oraz przesłanie plików wiedzy wymagają bezpośrednich wywołań API. Zobacz serwer Klaviyo MCP.

Czy sytuacja jest na tyle stabilna, że można na niej budować?

Wersja beta oznacza, że schemat może ulec zmianie. Do ostatniej ostatniej można zadzwonić, ale nie zobowiązujemy się do długoterminowej stabilności. Nie wysyłaj integracji o znaczeniu krytycznym dla wersji beta.

Gdzie znajdę pełny schemat?

Pełna dokumentacja referencyjna znajduje się w portalu deweloperskim Klaviyo pod adresem https://developers.klaviyo.com/en/reference/. Punkty końcowe Customer Agent są dostępne w sekcji Beta API w wersji 2026-10-15.pre.

Powiązane artykuły