Jak utworzyć narzędzie

Czego się dowiesz?

Jak połączyć Customer Agent z punktem końcowym HTTP za pomocą narzędzia niestandardowego, opisać, kiedy należy go używać, przetestować je oraz skonfigurować, czy Customer Agent może używać go bezpośrednio, czy tylko za pośrednictwem umiejętności.

Kilka słów na początek

Potrzebne będą:

• Włączono funkcję Customer Agent
• Punkt końcowy HTTP dostępny przez publiczną nazwę hosta. Adresy sieci prywatnej, localhost oraz adresy URL, które używają adresu IP zamiast nazwy hosta, nie są obsługiwane. Jeśli punkt końcowy wymaga klucza API lub tokena, zapiszesz go jako sekret (zobacz kroki 1 i 6).
• Plan określający, kiedy Customer Agent powinien używać tego narzędzia, wraz z wymaganymi kontrolami zgodności z zasadami.

Możesz utworzyć narzędzie i je przetestować, zanim zdecydujesz, jak będzie używane w rozmowach. Ustaw jego uprawnienia w sekcji Konektory: Zawsze zezwalaj na bezpośrednie użycie, Tylko w umiejętnościach do użycia za pośrednictwem umiejętności, która je zawiera, lub Zablokowane, aby uniemożliwić użycie. Jeśli potrzebujesz instrukcji dotyczących organizacji pracy, zobacz Jak utworzyć umiejętność.

Czym jest w pełni niestandardowe narzędzie

W pełni niestandardowe narzędzie to żądanie HTTP, które Customer Agent może wykonać w trakcie rozmowy. Użyj jednego, gdy narzędzia dostępne w Customer Agent nie obejmują tego, czego potrzebujesz — na przykład gdy chcesz wyszukać zamówienie w swoim własnym systemie zarządzania zamówieniami zamiast w Shopify, sprawdzić stany magazynowe w niestandardowym systemie magazynowym lub utworzyć zgłoszenie w systemie helpdesk, z którym Klaviyo nie integruje się natywnie.

Aby poznać podstawową koncepcję, zobacz Zrozumienie narzędzi.

Kiedy w pełni niestandardowe narzędzie należy tworzyć?

Sięgnij po w pełni spersonalizowane narzędzie, gdy:

• Potrzebujesz danych w czasie rzeczywistym z systemu, z którym Klaviyo nie ma zintegrowanej integracji
• Chcesz, aby Customer Agent wykonał działanie w systemie zewnętrznym (anulował subskrypcję w swoim systemie, utworzył zgłoszenie, zaktualizował rekord)
• Istniejące narzędzie nie pasuje – na przykład do zamówień używasz niestandardowego OMS zamiast Shopify

Jeśli informacje nie zmieniają się często i są takie same dla każdego klienta, dodaj je jako treść. Narzędzia przeznaczone są do dynamicznych danych i działań dotyczących poszczególnych klientów i klientek.

Skonfiguruj it

1. Otwórz stronę Narzędzia niestandardowe

1. Przejdź do Customer Agent > Konektory, a następnie otwórz kartę Niestandardowe.
2. Jeśli Twój punkt końcowy wymaga poświadczenia, przejdź do Sekrety i kliknij Dodaj sekret. Wpisz Nazwa i Wartość sekretu, a następnie kliknij Dodaj sekret. Pomiń ten krok, jeśli sekret jest już zapisany lub punkt końcowy go nie wymaga.
3. Kliknij Utwórz narzędzie.

2. Nazwij i opisz narzędzie

• Nazwa narzędzia — Krótki identyfikator, np. „Pobierz stany magazynowe” lub „Utwórz zgłoszenie zwrotu”.
• Opis – w języku naturalnym wyjaśnia, do czego służy narzędzie i kiedy go używać. Customer Agent czyta ten opis, aby zdecydować, czy użyć narzędzia do danego zgłoszenia. Bądź konkretny.

Przykładowy opis:

Pobiera z systemu magazynowego dane o stanie zapasów w czasie rzeczywistym dla danego produktu. Używaj, gdy kupujący pyta, czy dany produkt jest dostępny.

Niejasny przykładowy opis (unikaj):

Pobiera informacje o produkcie.

3. Skonfiguruj żądanie HTTP

• Metoda HTTP — GET, POST, PUT, DELETE lub PATCH.
• Szablon URL — Pełny adres URL punktu końcowego. Możesz dodać symbole zastępcze dla wartości dynamicznych (zobacz krok 5).
• Nagłówki — Wszelkie nagłówki wymagane przez punkt końcowy, w tym Content-Type i nagłówki uwierzytelniania.
• Parametry zapytania — Jeśli twój punkt końcowy oczekuje wartości w ciągu zapytania, wpisz tutaj ich nazwy i wartości. Możesz użyć symboli zastępczych dla tych wartości (zobacz krok 5).

4. Skonfiguruj treść żądania (dla POST, PUT, PATCH)

W sekcji Szablon treści podaj obiekt JSON. Użyj symboli zastępczych dla wartości, które Customer Agent ma uzupełnić w czasie wykonywania.

Przykładowa treść:

{
"customer_id": "{{profile_id}}",
"sku": "{{product_sku}}"
}

5. Zdefiniuj zmienne dla wartości dynamicznych

Każdy symbol zastępczy musi mieć odpowiadającą mu zmienną w sekcji Variables. Dla przykładowej treści powyżej:

1. Kliknij Dodaj zmienne i wpisz profile_id jako Nazwę zmiennej. Ustaw Źródło na profil Klaviyo, a Właściwość Klaviyo na Identyfikator Klaviyo. Zapewnia to uwierzytelniony identyfikator profilu Klaviyo kupującego.
2. Dodaj kolejną zmienną o nazwie product_sku. Ustaw Source na Dynamic Variable, wybierz String jako Type i opisz SKU, które Customer Agent powinien podać, w polu Description. Wybierz Required, jeśli punkt końcowy tego wymaga.

Powtórz to dla innych wartości, których potrzebuje twój punkt końcowy, takich jak order_id. Nazwy zmiennych muszą dokładnie odpowiadać ich placeholderom. Zmienna o nazwie conversation_id nie jest automatycznie uzupełniana bieżącym identyfikatorem rozmowy.

Użyj zmiennych jako symboli zastępczych, takich jak {{profile_id}} i {{product_sku}}, w adresie URL, nagłówkach, parametrach zapytania lub treści. Narzędzia, które używają zmiennych Klaviyo Profile, wymagają uwierzytelnionego klienta; brak wymaganej wartości profilu uniemożliwia uruchomienie żądania.

6. Uwierzytelnianie

Jeśli Twój punkt końcowy wymaga klucza API, tokena bearer lub innych danych uwierzytelniających, przechowuj je jako sekret. Sekrety są szyfrowane, ich wartości nigdy nie są wyświetlane w Customer Agent i nie można ich ponownie wyświetlić po zapisaniu.

1. W swoim narzędziu w sekcji Zmienne kliknij Dodaj zmienne. Nadaj zmiennej nazwę (na przykład api_key), ustaw Źródło na Sekret i wybierz zapisany sekret.
2. Odwołuj się do zmiennej wszędzie tam, gdzie punkt końcowy oczekuje danych uwierzytelniających: w nagłówku, w adresie URL, w parametrze zapytania lub w treści żądania. Na przykład dodaj nagłówek o nazwie Authorization z wartością Bearer {{api_key}}.

Aby wykonać rotację klucza, otwórz menu wiersza sekretu, kliknij Aktualizuj, wpisz wartość zastępczą, a następnie kliknij Aktualizuj. Każde narzędzie, które używa sekretu, pobiera nową wartość. Kolumna Używane przez pokazuje, które narzędzia odwołują się do każdego sekretu, więc sprawdź ją, zanim usuniesz któryś z nich.

7. Zapisz i przetestuj narzędzie

Przed zapisaniem sprawdź Limit czasu (sekundy) i Maksymalną liczbę ponownych prób w sekcji Ustawienia. Możesz ustawić ogólny limit czasu na poziomie 1–10 sekund oraz 0–3 ponowne próby w przypadku tymczasowych błędów. Jeśli narzędzie zmienia dane, upewnij się, że twój punkt końcowy może bezpiecznie obsłużyć ponowione żądanie.

Kliknij Zapisz, aby utworzyć narzędzie. Zapisane narzędzie otwiera się z sekcją Test.

Testy wysyłają prawdziwe żądania do Twojego punktu końcowego i mogą zmieniać dane. Użyj profilu testowego i rekordów testowych. Zapisz i uruchom test zapisuje też wszelkie zmiany w narzędziu, w tym w narzędziu używanym już przez umiejętności na żywo.

W Test wpisz przykładowe wartości dla zmiennych dynamicznych. Wybierz testowy profil w sekcji Profil, jeśli narzędzie korzysta ze zmiennych profilu Klaviyo. Kliknij Zapisz i uruchom test.

Przejrzyj Odpowiedź i sprawdź, czy:

• Odpowiedź wróciła pomyślnie
• Odpowiedź zawiera dane, których potrzebuje twoja organizacja pracy
• Oczekiwane przypadki błędów zwracają przydatne kody statusu i komunikaty

8. Skonfiguruj uprawnienia i dowolną niestandardową umiejętność

1. Otwórz Customer Agent > Konektory > Niestandardowe i sprawdź uprawnienia narzędzia. Wybierz Zawsze zezwalaj, aby umożliwić bezpośrednie użycie, Tylko w umiejętnościach, aby ograniczyć użycie do umiejętności, lub Zablokowane, aby uniemożliwić użycie. Zmiany uprawnień zapisują się natychmiast.
2. W przypadku organizacji pracy, która wymaga konkretnych instrukcji, otwórz lub utwórz umiejętność niestandardową. W sekcji Jak odpowiadać wpisz / w miejscu, w którym narzędzie ma zostać użyte, a następnie wybierz je. Wyjaśnij, kiedy należy ją wywołać, jakie wartości przekazać, jakie kontrole zasad wykonać oraz jak obsługiwać wyniki lub błędy. Zestaw narzędzi z ustawieniem „Tylko w umiejętnościach” musi zostać uwzględniony w umiejętności.
3. W przypadku niestandardowej umiejętności przetestuj wersję roboczą, a potem kliknij Opublikuj lub Zaktualizuj, gdy wszystko będzie gotowe. Przetestuj też bezpośrednie użycie narzędzia w Playground, jeśli dla narzędzia ustawiono opcję Zawsze zezwalaj.

Dowiedz się więcej o uprawnieniach narzędzia.

Użyj Composer, aby skonfigurować niestandardowe zachowanie.

Tworzenie dobrego opisu narzędzia

Jasny opis pomaga Customer Agent zdecydować, kiedy użyć narzędzia. Jeśli jest zawarta w niestandardowej umiejętności, instrukcje umiejętności zapewniają dodatkowe wskazówki dotyczące organizacji pracy. Dobre opisy:

• Powiedz jednym zdaniem do czego służy narzędzie
• Jednym zdaniem powiedz, kiedy użyć
• Konkretnie odnoszą się do zwróconych danych lub podjętych działań

Nieprawidłowe opisy są niejasne („Pobiera informacje o klientach”), zbyt szerokie („Obsługuje wszystko, co związane z zamówieniami”) lub instruują Customer Agent, jak się zachowywać, a nie to, co robi narzędzie.

Względy bezpieczeństwa

• Przechowuj dane uwierzytelniające jako klucze tajne. Nigdy nie wklejaj klucza API ani tokenu bezpośrednio do nagłówka, adresu URL ani treści żądania. Dodaj go jako klucz tajny i odwołuj się do niego za pomocą zmiennej Secret (zobacz krok 6).
• W miarę możliwości używaj listy dozwolonych adresów IP. Twój punkt końcowy nadal musi być dostępny przez publiczną nazwę hosta; adresy sieci prywatnej oraz localhost są blokowane. Użyj listy dozwolonych jako dodatkowej warstwy ochrony obok uwierzytelniania.
• Zwróć uwagę na to, jakie dane wysyłasz. Konfiguracja żądania oraz źródła zmiennych określają, które wartości są wysyłane do punktu końcowego. Instrukcje umiejętności wskazują wartości, które Customer Agent podaje dla zmiennych dynamicznych. Sprawdź, jakie pola otrzymuje twój punkt końcowy.
• Limity szybkości. Jeśli Twój punkt końcowy ma limity szybkości, upewnij się, że są wystarczająco wysokie, aby obsłużyć oczekiwaną liczbę konwersacji.

Rozwiązywanie problemów

Objaw: Customer Agent nigdy nie używa narzędzia.
Sprawdź jego uprawnienie w Connectors. Zablokowane narzędzie nie może zostać uruchomione. Jeśli ustawiono „Only in skills”, potwierdź, że jest uwzględnione w odpowiedniej opublikowanej umiejętności. Doprecyzuj opis narzędzia, sprawdź wymagane dane wejściowe i uwierzytelnianie, a następnie przetestuj ponownie.

Objaw: Narzędzie zwraca błąd podczas testowania.
Prawdopodobna przyczyna: Nieprawidłowy adres URL, niepoprawnie sformatowana treść, brak wymaganych danych profilu lub ładunek, którego twój punkt końcowy nie akceptuje.
Rozwiązanie: W Teście przejrzyj Podgląd żądania oraz Odpowiedź. Sprawdź adres URL, nagłówki i treść pod kątem oczekiwanego wejścia twojego punktu końcowego. Jeśli narzędzie używa zmiennych Klaviyo Profile, wybierz profil testowy z wymaganymi wartościami.

Objaw: Customer Agent używa narzędzia, ale przekazuje nieprawidłowe parametry.
Prawdopodobna przyczyna: Zmienna ma nieprawidłowe źródło lub właściwość profilu albo instrukcje umiejętności nie precyzują, co należy przekazać.
Rozwiązanie: Sprawdź nazwy zmiennych, źródła i wybrane właściwości profilu w sekcji Zmienne. Zaktualizuj opisy zmiennych i instrukcje umiejętności, aby jasno określały, co należy podać.

Objaw: narzędzie działa wolno, co powoduje opóźnienia w odpowiedziach.
Prawdopodobnaprzyczyna: końcowy czas oczekiwania.
Poprawka: zoptymalizuj punkt końcowy. Sprawdź, czy możesz buforować wyniki po swojej stronie.

Najczęściej zadawane pytania

Czy jedno narzędzie może być używane do wielu zadań?
Tak. Po utworzeniu narzędzie może być używane przez wiele umiejętności. Wstaw go do edytowalnych instrukcji każdej umiejętności, a następnie opublikuj lub zaktualizuj każdą umiejętność.

Jakie metody uwierzytelniania są obsługiwane?
Dowolna metoda, która wysyła statyczne poświadczenie wraz z żądaniem, np. token bearer lub nagłówek klucza API. Zapisz dane uwierzytelniające jako sekret i odwołuj się do nich za pomocą zmiennej Secret (zobacz krok 6). Sekwencje, które muszą pobrać lub odświeżyć token w czasie wykonywania żądania, np. OAuth, nie są obsługiwane w w pełni niestandardowych narzędziach.

Co się stanie, jeśli mój punkt końcowy nie działa lub zwraca błąd?
Klaviyo zgłasza awarie narzędzia do Customer Agent. Tymczasowe awarie można ponowić w ramach limitów czasu oczekiwania i ponowień narzędzia. W instrukcjach umiejętności wyjaśnij, jak reagować, jeśli narzędzie nie może zrealizować żądania, np. proponując przekazanie sprawy. Korzystaj z niezawodnych punktów końcowych i uważnie monitoruj działanie narzędzia.

Czy mogę edytować narzędzie po jego utworzeniu?
Tak. Otwórz narzędzie w Customer Agent > Konektory > Niestandardowe, edytuj jego nazwę, opis lub konfigurację żądania, a następnie kliknij Zapisz. Dodaj lub usuń narzędzie w instrukcjach każdej umiejętności.

Czy mogę wersjonować narzędzie?
Wersjonowanie nie jest jeszcze obsługiwane. Zapisane zmiany dotyczą narzędzia udostępnionego, w tym bezpośredniego użycia oraz wszystkich umiejętności, które się do niego odwołują. Zapisz i uruchom test zapisuje także zmiany, więc przed edycją sprawdź uprawnienia narzędzia i jego użycie na żywo.

Dodatkowe źródła