Akcje

Zdefiniuj, co Twój Agent AI może robić podczas rozmowy. Od odpowiadania na pytania przy użyciu danych z API w czasie rzeczywistym, przez zbieranie leadów i danych do analiz rynkowych, po wykonywanie niestandardowych zadań.

Agenci Quickchat AI mają dwa rodzaje akcji.

Quickchat AI Actions są wbudowane, wystarczy je włączyć i skonfigurować:

• Human Handoff przekazuje rozmowę człowiekowi.
• Inteligentne zbieranie danych zbiera leady i inne dane w trakcie czatu.

Akcje niestandardowe sięgają poza Quickchat AI:

• Akcje API wywołują dowolny endpoint HTTP. Opisujemy je na tej stronie.
• Akcje MCP podłączają cały serwer MCP naraz.
• Google Sheets to skrót, który jednym kliknięciem tworzy dla Ciebie akcję zapisującą dane.

Każda akcja może odczytywać dane z trwającej rozmowy przez AI Action Variables, a przykład Jira buduje taką akcję od początku do końca.

Niestandardowe Akcje

Custom Actions umożliwiają Twojej AI wywoływanie zewnętrznych API podczas rozmowy. Używaj ich do przeszukiwania narzędzi wewnętrznych, tworzenia zgłoszeń, wyzwalania alertów lub pobierania świeżych danych, których nie ma w Bazie Wiedzy. Znajdziesz je w Actions & MCPs w sekcji Custom Actions.

Jak działają niestandardowe akcje

1. Wybierz typ akcji: Akcja API, MCP, Akcja HubSpot, Akcja Discord, Google Sheets lub Shopify MCP. Skonfiguruj połączenie i instrukcje potrzebne AI.
2. Podczas czatu AI zwykle na podstawie opisu akcji oraz dostępnych szczegółów narzędzia lub parametrów decyduje, kiedy ją uruchomić. Akcję API można zamiast tego ustawić tak, aby uruchamiała się automatycznie przed pierwszą odpowiedzią.
3. Quickchat wykonuje wywołanie i zwraca wynik do AI. AI odczytuje odpowiedź i odpowiada użytkownikowi w języku naturalnym.
4. Przed użyciem akcji w rozmowach przetestuj ją lub połącz z poziomu jej edytora.

Wskazówka

Napisz opis jako instrukcję dla AI. Powiedz, kiedy używać akcji, co zwraca i jakie obowiązują ograniczenia.

Utwórz akcję API

1. Przejdź do Actions & MCPs.
2. Kliknij + w Custom Actions i wybierz API Action.
3. Uzupełnij Details:
   • Name: jasna i opisowa nazwa
   • Description: kiedy używać i co uwzględnić w parametrach
4. W sekcji Kiedy uruchomić wybierz AI decyduje lub Przed pierwszą odpowiedzią.
5. Skonfiguruj Connection:
   • Action Type: GET lub POST
   • Action endpoint URL: pełny adres URL API
   • Headers: dodaj wymagane nagłówki, np. Authorization lub content-type: application/json
6. Zdefiniuj Parameters: nadaj każdemu parametrowi name, location (query, body lub header) i description, która mówi AI, jak złożyć wartość. Wartości ścieżki (path) nie są lokalizacją parametru; wstaw je bezpośrednio w adresie URL endpointu za pomocą szablonów {{placeholder}}.
7. Test request i zweryfikuj odpowiedź. Następnie kliknij Done.

Poza samym żądaniem API Action ma trzy opcjonalne ustawienia, które warto znać: Save to memory, Run only when i Response filter.

Wybierz moment uruchomienia Akcji API

Użyj Kiedy uruchomić, aby wybrać jeden z dwóch trybów:

• AI decyduje: tryb domyślny. AI odczytuje opis Akcji i decyduje, czy żądanie odwiedzającego wymaga jej uruchomienia. Użyj tego trybu, gdy Akcja powinna uruchamiać się tylko w przypadku określonych pytań lub po zebraniu przez AI informacji od odwiedzającego.
• Przed pierwszą odpowiedzią: Quickchat uruchamia Akcję raz po wysłaniu przez odwiedzającego pierwszej wiadomości, ale zanim AI utworzy pierwszą odpowiedź. Zwykła odpowiedź AI otrzymuje odpowiedź API i wszystkie wartości zapisane przy użyciu Save to memory. AI nie może już wybrać tej Akcji jako narzędzia, więc uruchamia się ona tylko w pierwszej turze i nie później w rozmowie. Użyj tego trybu do identyfikacji klienta, pobrania kontekstu konta, sprawdzenia uprawnień albo innej konfiguracji potrzebnej każdej rzeczywistej rozmowie.

Tryb Przed pierwszą odpowiedzią jest powiązany z pierwszą wiadomością odwiedzającego, a nie z utworzeniem rozmowy. Otwarcie czatu ani odebranie wiadomości powitalnej nie uruchamia Akcji, więc porzucone czaty nie wysyłają żądania. Quickchat zapisuje uruchomienie przed wywołaniem endpointu. Dlatego nie próbuje ponownie w tej samej rozmowie, nawet jeśli żądanie się nie powiedzie lub jego wynik jest niepewny.

Pierwsza odpowiedź czeka na zakończenie żądania, dlatego ten tryb może zwiększyć opóźnienie. Jeśli kilka Akcji korzysta z tego trybu, uruchamiają się kolejno, a czasy ich żądań się sumują. Jeśli brakuje wymaganych metadanych, endpoint jest niedostępny lub żądanie się nie powiedzie, AI nadal odpowie. Otwórz Dziennik żądań Akcji, aby sprawdzić, co się stało.

Ponieważ Akcja uruchamia się, zanim AI może wybrać wartości parametrów, każdy używany przez nią parametr AI musi mieć wartość domyślną. Metadane i wbudowane zmienne można wstawiać bezpośrednio w adresie URL, nagłówkach, parametrach query lub body.

Identyfikacja po adresie e-mail lub numerze telefonu

W przypadku kanałów, które mogą udostępniać adres e-mail albo numer telefonu, utwórz osobną Akcję wyszukiwania dla każdego identyfikatora. Dla obu wybierz Przed pierwszą odpowiedzią, a następnie do każdej dodaj pasujący warunek Run only when, taki jak visitor_email exists lub visitor_phone_number exists. Quickchat wysyła tylko to żądanie, dla którego są dostępne metadane.

Akcje Discord

Akcje Discord otwierają galerię wstępnie wypełnionych, edytowalnych Akcji API:

• Support i zgłoszenia: Otwórz zgłoszenie supportowe wymaga wybrania serwera i kanału tekstowego. Opcjonalnie możesz wybrać rolę supportu, którą można wspomnieć. Tworzy trzy Akcje, które otwierają prywatny wątek, dodają bieżącego zgłaszającego i publikują podsumowanie z opcjonalną wzmianką o roli.
• Moderacja: Nadaj timeout członkowi, Wyrzuć członka, Zbanuj członka, Zdejmij bana, Przypisz rolę, Ustaw slowmode i Wyślij ogłoszenie. Każdy szablon instaluje się jednym kliknięciem i korzysta z serwera, członka, roli lub kanału z bieżącego żądania Discord.

Quickchat tworzy na backendzie metodę HTTP, adres URL, nagłówki, body, parametry, opis, ustawienia odpowiedzi i warunki uruchamiania. Powstałe karty są zwykłymi Akcjami typu HTTP Request. Możesz sprawdzić i edytować każde pole.

Wszystkie siedem szablonów moderacji zawiera warunek author_is_admin is true w sekcji Uruchom tylko gdy. Discord ustala, czy bieżący autor ma uprawnienie Administrator, gateway Discord przekazuje tę wartość, a Quickchat sprawdza ją przed wysłaniem żądania. Publiczny czat ani metadane API nie mogą ustawić tego klucza. Testuj Akcje moderacji na Discordzie zarówno z konta administratora, jak i konta bez uprawnień administratora. AI Preview nie udostępnia autoryzowanego nadawcy Discord.

Uwaga

Akcje moderacji można edytować. Usunięcie lub osłabienie warunku author_is_admin is true usuwa dostarczoną granicę autoryzacji. Wyrzuć członka i Zbanuj członka nie proszą o potwierdzenie przed wykonaniem.

Sam bot nadal potrzebuje uprawnienia Discord wymaganego przez każde żądanie:

Akcja	Uprawnienie lub dostęp bota
Nadaj timeout członkowi	Moderate Members
Wyrzuć członka	Kick Members
Zbanuj członka, Zdejmij bana	Ban Members
Przypisz rolę	Manage Roles
Ustaw slowmode	Manage Channels
Wyślij ogłoszenie	View Channels i Send Messages

Discord wymusza także hierarchię ról. Umieść rolę bota ponad członkami i rolami, którymi ma zarządzać. Szablon nie wykonuje dodatkowej kontroli hierarchii ani poszczególnych uprawnień administratora wysyłającego żądanie.

Ustaw slowmode i Wyślij ogłoszenie przyjmują parametr ID kanału. Bez dodatkowego stałego celu szablon nie sprawdza, czy kanał należy do serwera, z którego administrator wysłał żądanie. Jeśli ten sam bot należy do wielu serwerów, edytuj te Akcje tak, aby używały stałego ID kanału, albo utwórz dla serwerów osobne granice zaufania z oddzielnymi Agentami i danymi logowania botów.

Instalacja Support Ticket korzysta z istniejących funkcji Akcji do przekazywania danych:

1. open_support_ticket tworzy prywatny wątek na wybranym kanale, przechwytuje $.id i zapisuje je w pamięci rozmowy jako discord_ticket_thread_id. Wymaga warunku discord_message is true, uruchamia się tylko na wybranym serwerze i tylko wtedy, gdy ten klucz pamięci nie istnieje.
2. add_ticket_requester odczytuje {{metadata_discord_ticket_thread_id}} oraz dostarczone przez Discord {{metadata_discord_author_id}}. Wymaga warunku discord_message is true i uruchamia się tylko na wybranym serwerze po zapisaniu ID wątku.
3. post_in_ticket odczytuje to samo zapisane ID wątku, publikuje jednowierszowe podsumowanie sprawy przygotowane przez Agenta oraz wspomina zgłaszającego. Jeśli wybierzesz rolę supportu, wspomina również tę rolę. Ma te same warunki dotyczące wiadomości Discord, serwera i zapisanego wątku. Pole allowed_mentions w body żądania Discord jest ograniczone do zgłaszającego oraz, jeśli wybrano rolę, do tej roli.

Opisy oraz główny prompt Agenta powinny nakazywać uruchamianie tych Akcji w podanej kolejności. Nie ma osobnej warstwy stanu workflow, blokady, potwierdzenia, ponawiania, odzyskiwania, uzgadniania ani ochrony przed ponownym odtworzeniem żądania. Jeśli wynik jest niepewny, przed ponowieniem sprawdź Discord i log Akcji, ponieważ Discord mógł już wykonać żądanie.

discord_ticket_thread_id nie jest automatycznie usuwany. Dlatego szablon obsługuje jedno zgłoszenie na rozmowę w Quickchat. Aby utworzyć kolejne zgłoszenie, rozpocznij nową rozmowę lub wątek na Discordzie albo edytuj Akcje i dodaj potrzebny cykl życia pamięci.

Dla Support Ticket przyznaj botowi View Channels, Send Messages, Read Message History, Create Private Threads, Send Messages in Threads i Manage Threads na wybranym kanale zgłoszeń. Jeśli żadna rola nie ma być wspomniana, w polu Powiadom rolę (opcjonalnie) pozostaw opcję Nie powiadamiaj roli. Jeśli wybierzesz rolę, musi ona umożliwiać wzmianki, a jej członkowie muszą mieć dostęp do prywatnych wątków. Jeśli nie ma dostępnych ról, które można wspomnieć, zgłoszenia nadal otwierają się normalnie bez powiadamiania roli. Galeria pokazuje kanały tekstowe i role, które można wspomnieć, ale nie sprawdza wszystkich nadpisań uprawnień kanału.

Uwaga

Akcje Discord wymagają tokenu z Twojej własnej aplikacji Discord w sekcji Aplikacje zewnętrzne → Discord → Konfiguracja zaawansowana. Sam wspólny bot dostępny jednym kliknięciem nie może dostarczyć tego tokenu. Zobacz Discord.

Galeria jest skrótem konfiguracji, a nie dodatkową warstwą egzekwowania zasad. Jeśli edytujesz wygenerowaną Akcję lub tworzysz niestandardową Akcję API Discord, przed włączeniem sprawdź jej dane logowania, cele, parametry, udostępnianie odpowiedzi i warunki Uruchom tylko gdy.

Save to memory

Przechwyć wartość z odpowiedzi API i zapisz ją w pamięci konwersacji pod wybranym przez siebie kluczem. Kolejne Akcje mogą jej ponownie użyć jako {{metadata_<key>}}, a pojawia się ona w szczegółach konwersacji (Inbox, API oraz eksporty).

Sięgnij po to ustawienie, gdy jedna Akcja produkuje coś, czego potrzebuje kolejna Akcja. Akcja wyszukująca może zapisać customer_id ze swojej odpowiedzi; kolejna Akcja wysyła wtedy {{metadata_customer_id}} bez konieczności przepisywania wartości przez AI.

W sekcji Save to memory edytora API Action nadaj przechwytywanej wartości klucz pamięci i wskaż część odpowiedzi, którą chcesz zachować. Od tej pory jest to zmienna metadanych jak każda inna.

Klucze pamięci są wspólne z narzędziami Remote MCP agenta. Jeśli narzędzie MCP zapisuje już pod tym samym kluczem, pole klucz pamięci zgłosi konflikt przy zapisie, więc wybierz inny klucz.

Wskazówka

Używaj kluczy w formacie snake_case (litery, cyfry, podkreślniki). Klucz taki jak customer_id można referencjonować jako {{metadata_customer_id}}; klucze ze spacjami lub innymi znakami interpunkcyjnymi nie mogą być używane w placeholderach. Zobacz Metadane konwersacji, aby dowiedzieć się, jak działają zmienne metadanych.

Run only when

Ogranicz Akcję tak, aby uruchamiała się tylko wtedy, gdy spełnione są warunki dotyczące metadanych konwersacji. Warunki są sprawdzane po naszej stronie, w momencie wywołania, po tym, jak AI zdecyduje o wywołaniu Akcji, ale zanim zostanie wysłane jakiekolwiek żądanie, więc nie da się ich obejść z poziomu czatu.

To właściwe narzędzie do uprzywilejowanych lub nieodwracalnych Akcji (banowanie członka, wystawianie zwrotu, usuwanie rekordu). Linijka w Twoim promptcie mówiąca „tylko administratorzy mogą to zrobić” jest pomocną instrukcją, ale nie jest granicą bezpieczeństwa: zdeterminowany użytkownik może spierać się z modelem lub spróbować prompt injection. Warunek uruchomienia jest deterministyczny i istnieje poza promptem, więc obowiązuje niezależnie od tego, co mówi rozmowa.

• Warunek uruchomienia jest granicą. Jest sprawdzany po stronie serwera i nie jest częścią promptu, który czyta model. To właśnie to faktycznie powstrzymuje Akcję przed uruchomieniem.
• Reguła w promptcie jest doświadczeniem użytkownika. Zachowaj też linijkę w promptcie, aby AI uprzejmie odmawiało i wyjaśniało dlaczego, zamiast milknąć.

Dodaj warunki w sekcji Run only when edytora Akcji. Kliknij Add condition, wybierz klucz metadanych (na przykład telegram_sender_is_admin) i wybierz sposób porównania:

Warunek	Spełniony, gdy wartość metadanych…
is true	jest prawdziwa (truthy)
is false	jest fałszywa (falsy)
exists	jest obecna na konwersacji
does not exist	jest nieobecna
equals	pasuje do wartości, którą podasz
does not equal	różni się od wartości, którą podasz

Akcja uruchamia się tylko wtedy, gdy spełniony jest każdy warunek. Warunek na kluczu, który nie jest ustawiony na konwersacji, nie zostaje spełniony.

Gdy warunek nie zostaje spełniony, nie jest wysyłane żadne żądanie, a AI informuje użytkownika, że nie może tego zrobić. Poniżej to samo żądanie banowania zostaje zablokowane dla osoby niebędącej administratorem i dozwolone dla administratora, przy czym zmienia się tylko to, kto pyta:

Uwaga

Bramkuj tylko na metadanych, które ustawia Quickchat (takich jak zweryfikowana przez kanał flaga telegram_sender_is_admin), a nie na wartościach, na które może wpłynąć odwiedzający. Zobacz Metadane konwersacji, aby sprawdzić, skąd pochodzi każdy klucz.

Response filter

Domyślnie AI widzi pełną odpowiedź API. Dodaj wyrażenia JSONPath w sekcji Response filter, aby ograniczyć AI do konkretnych jej części.

Dwa typowe powody do filtrowania:

• Ukrycie wrażliwych pól. Trzymaj adresy e-mail klientów, dane płatnicze lub wewnętrzne identyfikatory poza kontekstem modelu, gdy endpoint zwraca więcej, niż AI potrzebuje.
• Zmniejszenie promptu. Gadatliwe API mogą zwracać duże ładunki; filtrowanie do kilku istotnych pól utrzymuje odpowiedź małą, a AI skupione.

Dodaj jedno lub więcej wyrażeń JSONPath, a AI otrzyma tylko dopasowane części. Na przykład $.data.items[*].name zachowuje z większej odpowiedzi same nazwy elementów.

Wskazówka

Użyj panelu Test Response, aby zobaczyć dokładnie, co AI otrzyma po filtrowaniu, zanim na tym polegniesz. Zobacz Testowanie Akcji.

Uwaga

JSONPath, który niczego nie dopasowuje, zostawia AI z pustą odpowiedzią. Zacznij bez filtra, potwierdź, że wywołanie działa, a następnie go zawęź.

Najlepsze praktyki

• Bądź precyzyjny w opisach. Powiedz AI, kiedy używać akcji i co powinny zawierać parametry.
• Minimalizuj zakresy. Dołączaj tylko niezbędne nagłówki i tokeny. Dla Jira używaj nagłówka Basic z adresu e-mail Atlassian i tokenu API.
• Testuj przed wdrożeniem korzystając z panelu Test request. Potwierdź kody statusu i przykładowe ładunki w narzędziu docelowym.

Samouczki

• Wyszukiwanie zgłoszeń Jira w rozmowie z AI
• Wysłanie powiadomienia Slack przy użyciu Akcji AI