Webhook w DomaAI - agent, który reaguje na formularz i zdarzenia

Harmonogram uruchamia agenta o stałej porze. Webhook uruchamia go wtedy, gdy coś się wydarzy: klient wyśle formularz na Twojej stronie albo inna usługa zgłosi zdarzenie. Z tego poradnika dowiesz się, jak założyć zadanie z webhookiem, gdzie znaleźć jego adres, jak go chronić i ile wywołań mieści się w planie.

Zadania z webhookiem są dostępne od planu Base. Zakładasz je w aplikacji na iPhonie i iPadzie (od wersji 0.1.15) albo w rozmowie, także w przeglądarce. Jeśli to Twój pierwszy agent, zacznij od wpisu Pierwszy agent automatyzacji.

Kiedy webhook zamiast harmonogramu

Zadanie w DomaAI ma w sekcji „Kiedy” cztery możliwości: Codziennie, Co tydzień, Co N godzin i Webhook. Pierwsze trzy to harmonogram: agent rusza o ustalonej porze albo co kilka godzin, niezależnie od tego, czy coś się wydarzyło. Webhook działa odwrotnie. Zadanie czeka, aż ktoś wyśle dane pod jego adres, i wtedy rusza z tymi danymi w poleceniu.

Webhook wybierz, gdy:

• liczy się czas reakcji - zapytanie z formularza nie czeka do porannego przeglądu, a harmonogram ma w każdym planie minimalny odstęp: od co 24 h na Free do co godzinę na Max,
• zdarzenia przychodzą nieregularnie - raz trzy zgłoszenia w godzinę, potem nic przez dwa dni, a zadanie rusza tylko wtedy, gdy coś przyszło, więc nie płacisz za puste przebiegi,
• dane wysyła inny system - formularz na stronie, narzędzie do automatyzacji, takie jak Zapier czy Make, GitHub albo zwykły cron.

Harmonogram zostaw do rzeczy cyklicznych: porannego przeglądu poczty, prasówki czy nowych przetargów w każdy poniedziałek.

Ustawienie zadania z webhookiem

Na iPhonie i iPadzie

1. Stuknij „+” przy polu wiadomości i wybierz kafel „Agenci i automatyzacje”.
2. W zakładce Zadania stuknij „Nowe zadanie”, a potem „Od zera”. Gotowy szablon do formularza opisujemy niżej.
3. Uzupełnij pola „Nazwa”, „Agent” i „Polecenie”. W poleceniu napisz, co agent ma zrobić z danymi, które przyjdą.
4. W sekcji „Kiedy” wybierz „Webhook”. Aplikacja wyjaśni: „Zadanie uruchomi się, gdy pod jego adres webhooka przyjdzie POST z JSON-em. Adres dostaniesz po zapisaniu; dane z żądania trafią do polecenia.” Jeśli Twój plan nie obejmuje webhooków, stuknięcie tej opcji pokaże plany.
5. W sekcji „Wynik” zobaczysz, że wynik przyjdzie e-mailem na adres konta. Włącz „Powiadomienie push”, jeśli chcesz dostać powiadomienie po udanym uruchomieniu. Warto też włączyć „Ponów po błędzie” (do 3 prób, bez podwójnej opłaty) i „Kontynuuj po zgodzie”, żeby po Twojej decyzji agent dokończył uruchomienie.
6. Stuknij „Zaplanuj zadanie”. Aplikacja od razu otworzy szczegóły zadania, a w nich adres webhooka.

Przykładowe polecenie dla zadania z webhookiem:

W danych jest zgłoszenie z formularza kontaktowego. Streść je w jednym zdaniu, oceń, czy jest pilne, i przygotuj krótką odpowiedź dla klienta. Streszczenie wyślij mi jako powiadomienie.

Zadanie dostaje dane od obcych osób, więc przypnij do niego agenta z wąskimi uprawnieniami, tylko z tym, czego wymaga polecenie. Opcja „Bez agenta” daje domyślne uprawnienia, w których wysyłki i publikacje czekają na Twoją zgodę.

W rozmowie, także w przeglądarce

Napisz w zwykłej rozmowie, co ma się dziać po zgłoszeniu:

Gdy przyjdzie zgłoszenie z formularza na mojej stronie, oceń je, przygotuj odpowiedź do mojej zgody i wyślij mi push ze streszczeniem.

Asystent dobierze szablon albo założy własnego agenta i zadanie. Adresu webhooka nie poda w rozmowie, bo działa on jak hasło. Odczytasz go w szczegółach zadania na iPhonie albo w przeglądarce, jak opisujemy niżej.

Adres webhooka i jak go chronić

Adres powstaje po zapisaniu zadania, a jego ostatni fragment to tajny token.

• Na iPhonie i iPadzie - w szczegółach zadania jest karta „Adres webhooka”, a obok adresu ikona kopiowania.
• W przeglądarce - w panelu bocznym otwórz kafel „Maszyny” i znajdź sekcję „Rutyny”. Pod wierszem zadania jest „Adres webhooka”, domyślnie zamaskowany, z przyciskami „Pokaż”, „Kopiuj” i „Nowy adres”.

Skopiowany adres wklej tam, gdzie Twoja usługa formularzy albo narzędzie do automatyzacji przyjmuje adres webhooka. Żądanie wysyłasz metodą POST, z treścią w JSON-ie i nagłówkiem Content-Type: application/json.

Jak chronić adres:

• Traktuj go jak hasło. Kto go zna, może uruchomić zadanie na Twoich kredytach. Nie publikuj go i nie wklejaj do kodu strony, który widzi przeglądarka odwiedzającego. Żądanie wysyłaj z serwera albo z usługi formularzy.
• Token nie trafia do logów serwera DomaAI.
• Wymień adres, gdy wyciekł. W przeglądarce służy do tego „Nowy adres”. Stary adres przestaje działać od razu i odpowiada błędem 404, więc nowy od razu wklej u nadawcy.
• Wyłącz zadanie, gdy chcesz wstrzymać przyjmowanie zgłoszeń. Wywołania dostają wtedy odpowiedź 409, dopóki zadania nie włączysz.

Co dzieje się z danymi z żądania

Treść żądania trafia do polecenia zadania, ale w osobnym, oznaczonym bloku. Agent traktuje ją jako dane do przetworzenia, nie jako polecenia. Dane mogą wskazać, kogo dotyczy zadanie, np. adres do odpowiedzi, ale samego zadania nie zmieniają.

• Czyszczenie - z danych usuwamy znaki sterujące i niewidoczne znaki, w których da się ukryć instrukcje. Gdy podczas pracy agent trafi na treść, która próbuje nim sterować, np. w przeczytanym mailu, uruchomienie dostaje w historii oznaczenie „Podejrzana treść”, a akcje ze skutkiem na zewnątrz czekają na Twoją zgodę.
• Rozmiar - żądanie może mieć do 64 KB, a do polecenia trafia najwyżej 6 000 znaków danych. Treść, która nie jest poprawnym JSON-em, agent dostanie jako zwykły tekst. Puste wywołanie też uruchomi zadanie, więc adres zadziała jako zwykły wyzwalacz, np. z crona.
• Duplikaty - ta sama treść wysłana ponownie w ciągu 10 minut nie uruchomi zadania drugi raz. Jeśli nadawca dołącza nagłówek Idempotency-Key, powtórkę z tym samym kluczem rozpoznajemy przez 24 h. Przy testach zmieniaj więc treść zgłoszenia.
• Kolejka - gdy zadanie właśnie pracuje, kolejne zdarzenia czekają w kolejce najwyżej 24 h i ruszają po kolei. Na iPhonie widzisz je w szczegółach zadania w wierszu „W kolejce”, a w przeglądarce w wierszu zadania w sekcji „Rutyny” („w kolejce: …”). Wstrzymane zadanie nie przyjmuje nowych wywołań, ale zdarzenia przyjęte wcześniej czekają na wznowienie.
• Przechowywanie - dane z webhooka pochodzą od osób trzecich, więc przechowujemy je 24 h. W tym czasie na iPhonie powtórzysz uruchomienie z tymi samymi danymi: otwórz je w sekcji „Historia” w szczegółach zadania i w menu „…” wybierz „Powtórz” albo „Powtórz jako próbę”.

Kody odpowiedzi serwera dla osoby, która podłącza formularz:

Przy braku kredytów, wyczerpanym limicie i pełnej kolejce dostajesz push, a gdy wynik zadania idzie e-mailem, także e-mail. Takie powiadomienie przychodzi najwyżej raz na dobę dla danego zadania i powodu i nie zawiera danych z formularza.

Szablon: odpowiedź na zapytanie z formularza

Najszybciej zaczniesz od gotowego szablonu „Nowe zapytanie z formularza → odpowiedź i push”. To automatyzacja formularza kontaktowego z agentem w roli Sprzedaż i oferty. Po każdym zgłoszeniu agent:

1. streszcza zgłoszenie w jednym zdaniu i ocenia je: pilne, zwykłe albo spam,
2. spam i oferty handlowe kończy bez odpowiedzi,
3. przygotowuje odpowiedź na zapytanie klienta: podziękowanie, następny krok i informację, kiedy się odezwiesz, najwyżej 4 zdania i bez cen spoza Twoich materiałów,
4. wysyła Ci push z imieniem klienta i streszczeniem.

Gmail jest opcjonalny. Gdy go połączysz w Konektorach, odpowiedź do klienta czeka na Twoją zgodę i po zatwierdzeniu wychodzi z Twojej skrzynki. Bez Gmaila agent wpisuje treść odpowiedzi do wyniku, a Ty wysyłasz ją sam.

Zadanie z szablonu zakładasz tak:

1. „+” → „Agenci i automatyzacje” → zakładka Zadania → „Nowe zadanie” → „Z szablonu”.
2. W galerii „Szablony agentów” wybierz „Nowe zapytanie z formularza → odpowiedź i push”.
3. Szablon nie wymaga konta, więc kreator ma trzy kroki: Podgląd, Dostosuj i Próba. W podglądzie widzisz limit 40 kr na jedno uruchomienie, „Przykład wyniku” i „Co agent może robić”.
4. W kroku Dostosuj w sekcji „Kiedy” jest już wybrany „Webhook”. Pole „Imię agenta” ma na start nazwę szablonu skróconą do 40 znaków. Możesz ją zmienić, np. na „Kasia od zapytań”. Zostaw włączone „Powiadomienie push”.
5. Wybierz „Utwórz bez próby”, a potem „Przejdź do zadania”. W szczegółach zadania skopiuj adres webhooka i wklej go u nadawcy formularza.

Szablon spodziewa się w danych imienia, e-maila, telefonu i treści zgłoszenia. Na przykład:

Wynik takiego uruchomienia wygląda mniej więcej tak:

Pilne - Marek Lis prosi o wycenę ogrodzenia 60 m do końca tygodnia. Odpowiedź przygotowana, czeka na Twoją zgodę. Push wysłany: „Marek Lis - wycena ogrodzenia 60 m, do piątku”.

Odpowiedź zatwierdzasz na iPhonie w zakładce Zgody (ryzykowne akcje przez Face ID), a w przeglądarce w panelu bocznym pod „Więcej” → „Zgody agentów”. Przed zatwierdzeniem możesz ją poprawić. Prośba bez decyzji wygasa po 7 dniach. Szczegóły opisuje poradnik o uprawnieniach i zgodach agentów.

Uruchomienie kosztuje tak jak u każdego agenta: 20 kr na start, a potem praca modelu, całość przycięta do limitu. Ten szablon ma limit 40 kr, a typowe uruchomienie to ok. 30 kr. Miesięczny koszt zależy więc od liczby zgłoszeń. Przy 50 zgłoszeniach w miesiącu wyjdzie orientacyjnie 1 500 kr, czyli mniej niż połowa miesięcznej puli planu Base (4 000 kr). Nieudane uruchomienie oddaje kredyty. Pozostałe szablony opisuje galeria szablonów.

Limity w planach

Liczba zadań z webhookiem i dzienna liczba uruchomień zależą od planu. Free nie ma webhooków.

Webhooki - ile zadań może być uruchamianych webhookiem. Na dobę - wszystkie uruchomienia automatyzacji na koncie, nie tylko te z webhooka.

Każde zadanie z webhookiem przyjmuje do 100 zdarzeń na dobę. Zdarzenia liczą się też do dziennej liczby uruchomień automatyzacji na koncie, razem z harmonogramami, próbami i „Uruchom teraz”. Ten licznik zaczyna się od północy. Na planie Base wcześniej skończy się więc limit 30 uruchomień na konto niż 100 zdarzeń na zadanie. Gdy formularz dostaje kilkadziesiąt zgłoszeń dziennie, potrzebujesz planu Plus albo wyższego, a do tego kredytów na każde uruchomienie. Po obniżce planu działające zadania biegną dalej, ale od razu obowiązuje dzienny limit nowego planu. Pełną tabelę znajdziesz w limitach planów.

Od czego zacząć

1. Załóż zadanie z szablonu formularza albo od zera, z „Kiedy” ustawionym na „Webhook” (od planu Base).
2. Skopiuj adres i wklej go po stronie serwera albo w usłudze formularzy, nie w kodzie strony.
3. Wyślij zgłoszenie testowe i obejrzyj przebieg w historii zadania na iPhonie.
4. Przez pierwsze dni zatwierdzaj odpowiedzi ręcznie i poprawiaj polecenie.

Listę usług, które łączysz z agentami, pokazuje sekcja integracje na stronie o agentach automatyzacji, a Gmaila podłączysz według wpisu o konektorach. Pierwsze zadanie z webhookiem założysz od razu w aplikacji w przeglądarce.