Akcje: odpowiedzi z Twojego własnego systemu

Akcja pozwala Twojemu botowi sprawdzić coś w Twoim własnym systemie w trakcie czatu — gdzie jest zamówienie, kiedy zostanie dostarczone, czy rezerwacja jest potwierdzona. Klient pyta, bot zbiera potrzebne informacje, wywołuje Twoje API i odpowiada na podstawie tego, co otrzyma, w języku klienta.

Działa wszędzie tam, gdzie Twój bot: w widżecie na stronie, w linku do bota i kodzie QR oraz w aplikacjach Android, iOS, React Native, Flutter i Ionic. Nic nie jest instalowane ani aktualizowane — wywołanie następuje z naszych serwerów, więc dane dostępowe do Twojego API nigdy nie trafiają do przeglądarki ani telefonu.

Zanim zaczniesz: każdy może rozmawiać z Twoim botem

Twój bot to publiczny czat. Jeśli sam numer zamówienia wystarczy, aby zobaczyć zamówienie, każdy może wpisywać numery, aż któryś zadziała.

Bot pomaga na trzy sposoby, ale żaden z nich nie zastępuje tej weryfikacji: wysyła tylko wartości, które klient faktycznie wpisał, ogranicza liczbę wyszukań z jednego czatu lub jednego adresu, a Ty możesz wybrać, które pola odpowiedzi może zobaczyć.

Skonfiguruj akcję

Otwórz Akcje w panelu i wybierz Nowa akcja. Ten ekran widzą właściciele i administratorzy.

• Nazwa — dla Ciebie, np. „Status zamówienia”.
• Kiedy bot ma tego używać? — jedno zdanie, tak jakby tłumaczyć to nowemu współpracownikowi: „Klient pyta, gdzie jest jego zamówienie lub kiedy dotrze”.
• Adres Twojego API — GET lub POST oraz adres https://. Wpisz {{order_id}} tam, gdzie ma być wartość.
• O co bot pyta klienta — do sześciu wartości. Każda ma etykietę w Twoich słowach („Numer zamówienia”), nazwę używaną przez Twoje API (order_id) i typ: dowolny tekst, liczba, adres e-mail lub numer telefonu.
• Nagłówki — Twój klucz API lub token. Przechowywany w formie zaszyfrowanej i nigdy więcej nie wyświetlany.
• Udostępniaj botowi tylko te pola — opcjonalnie. Wymień części odpowiedzi, z których bot może korzystać, np. status, eta, items[].name. Wszystko inne jest odrzucane, zanim zobaczy to AI.

Naciśnij Testuj, wpisz przykładowe wartości, a zobaczysz wysłane żądanie i dokładnie to, co otrzymałby bot. Potem wypróbuj to naprawdę na ekranie Test: „Gdzie jest moje zamówienie 48213? Mój e-mail to asha@example.com”.

Co otrzymuje Twoje API

Przy GET wartości umieszczone w adresie są uzupełniane, a pozostałe są dodawane do ciągu zapytania:

GET https://api.yourshop.com/orders/48213?email=asha%40example.com

Przy POST wartości stanowią treść JSON:

POST https://api.yourshop.com/lookup
Content-Type: application/json

{"order_id":"48213","email":"asha@example.com"}

Każde żądanie zawiera też Twoje własne nagłówki oraz te:

Co odesłać

Odpowiedz w ciągu 8 sekund w formacie JSON lub krótką linią zwykłego tekstu.

• 200 z danymi — bot odpowiada na ich podstawie. Zachowaj zwięzłość i używaj czytelnych nazw pól: {"status":"shipped","eta":"2 October"} działa lepiej niż wewnętrzne kody.
• 404, gdy nic nie pasuje — bot informuje o tym klienta i prosi o sprawdzenie wpisanych danych.
• Cokolwiek innego lub brak odpowiedzi na czas — bot przeprasza, podaje Twoje dane kontaktowe, a czat zostaje dla Ciebie oznaczony. Powód jest widoczny na ekranie Akcje.

Przekierowania nie są śledzone, a odpowiedź powyżej 256 KB nie jest odczytywana.

Sprawdź podpis

Żądania są podpisywane w sposób zgodny ze Standard Webhooks, więc możesz użyć istniejącej biblioteki. Twój sekret do podpisywania znajdziesz na ekranie Akcje.

Ręcznie: połącz identyfikator, znacznik czasu i dokładną treść kropkami, podpisz to algorytmem HMAC-SHA256 z użyciem sekretu (część po whsec_, zdekodowana z base64) i porównaj.

const crypto = require('crypto');

function isFromKeyda(req, rawBody, secret) {
  const id = req.headers['webhook-id'];
  const ts = req.headers['webhook-timestamp'];
  const given = String(req.headers['webhook-signature'] || '').replace(/^v1,/, '');
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // older than 5 minutes
  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
  const want = crypto.createHmac('sha256', key).update(`${id}.${ts}.${rawBody}`).digest('base64');
  return given.length === want.length
    && crypto.timingSafeEqual(Buffer.from(given), Buffer.from(want));
}

W przypadku żądania GET treść jest pusta, więc podpisywany tekst kończy się kropką. Użyj POST, jeśli chcesz, aby podpis obejmował także same wartości.

Jak bot z tego korzysta

• Pyta o wszystko, czego brakuje, po jednym krótkim pytaniu naraz, i pamięta, co klient powiedział wcześniej na czacie.
• Nigdy nie zgaduje wartości. Jeśli klient jej nie wpisał, bot o nią pyta.
• Jedno wyszukanie na wiadomość. Twoje zapisane odpowiedzi nadal mają pierwszeństwo, więc pytanie, na które odpowiedziano ręcznie, nigdy nie wywołuje Twojego API.
• Odpowiedzi z wyszukania nigdy nie są używane ponownie dla innego klienta.
• Wyszukanie liczy się jako jedna odpowiedź, tak jak każda inna odpowiedź napisana przez AI.

W sekcji Czaty odpowiedź pochodząca z wyszukania ma pod spodem adnotację: która akcja została uruchomiona i jak się zakończyła. Wartości wpisane przez klienta pozostają w transkrypcji i nigdzie indziej.

Limity

Akcje odczytują informacje. Nie kieruj akcji na adres, który coś zmienia — anulowanie zamówienia lub zwrot pieniędzy wymaga kroku potwierdzenia, którego bot jeszcze nie ma.