Aktionen: Antworten aus Ihrem eigenen System

Mit einer Aktion kann Ihr Bot mitten im Chat etwas in Ihrem eigenen System nachschlagen — wo eine Bestellung ist, wann sie geliefert wird, ob eine Buchung bestätigt ist. Der Kunde fragt, der Bot sammelt, was er braucht, ruft Ihre API auf und antwortet aus dem, was zurückkommt, in der Sprache des Kunden.

Es funktioniert überall dort, wo Ihr Bot funktioniert: im Website-Widget, über Ihren Bot-Link und QR-Code sowie in den Android-, iOS-, React Native-, Flutter- und Ionic-Apps. Nichts wird installiert oder aktualisiert — der Aufruf erfolgt von unseren Servern aus, sodass Ihre API-Zugangsdaten nie einen Browser oder ein Telefon erreichen.

Bevor Sie beginnen: Jeder kann mit Ihrem Bot chatten

Ihr Bot ist ein öffentlicher Chat. Wenn eine Bestellnummer allein genügt, um eine Bestellung zu sehen, kann jeder Nummern eingeben, bis eine passt.

Der Bot hilft auf drei Arten, aber keine davon ersetzt diese Prüfung: Er sendet nur Werte, die der Kunde tatsächlich eingegeben hat, er begrenzt, wie viele Abfragen ein Chat oder eine Adresse machen kann, und Sie können wählen, welche Felder der Antwort er sehen darf.

Eine einrichten

Öffnen Sie Aktionen im Dashboard und wählen Sie Neue Aktion. Inhaber und Admins können diesen Bildschirm sehen.

• Name — für Sie, etwa „Bestellstatus“.
• Wann soll der Bot sie verwenden? — ein Satz, so wie Sie es einem neuen Kollegen erklären würden: „Der Kunde fragt, wo seine Bestellung ist oder wann sie ankommt.“
• Ihre API-Adresse — GET oder POST und eine https://-Adresse. Schreiben Sie {{order_id}} dorthin, wo ein Wert hingehört.
• Wonach der Bot den Kunden fragt — bis zu sechs Werte. Jeder hat eine Bezeichnung in Ihren Worten („Bestellnummer“), den Namen, den Ihre API verwendet (order_id), und einen Typ: beliebiger Text, eine Zahl, eine E-Mail-Adresse oder eine Telefonnummer.
• Header — Ihr API-Schlüssel oder Token. Verschlüsselt gespeichert und nie wieder angezeigt.
• Nur diese Felder mit dem Bot teilen — optional. Listen Sie die Teile der Antwort auf, die der Bot verwenden darf, etwa status, eta, items[].name. Alles andere wird verworfen, bevor die KI es sieht.

Klicken Sie auf Testen, geben Sie Beispielwerte ein, und Sie sehen die gesendete Anfrage und genau das, was der Bot erhalten würde. Probieren Sie es dann in echt auf dem Bildschirm Testen: „Wo ist meine Bestellung 48213? Meine E-Mail ist asha@example.com“.

Was Ihre API empfängt

Bei GET werden die Werte, die Sie in der Adresse platziert haben, eingesetzt und die übrigen an den Query-String angehängt:

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

Bei POST bilden die Werte den JSON-Body:

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

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

Jede Anfrage enthält außerdem Ihre eigenen Header und diese:

Was Sie zurücksenden

Antworten Sie innerhalb von 8 Sekunden mit JSON oder einer kurzen Zeile Klartext.

• 200 mit den Daten — der Bot antwortet daraus. Halten Sie sie klein und verwenden Sie klare Feldnamen: {"status":"shipped","eta":"2 October"} funktioniert besser als interne Codes.
• 404, wenn nichts übereinstimmt — der Bot sagt es dem Kunden und bittet ihn, seine Eingabe zu prüfen.
• Alles andere, oder keine rechtzeitige Antwort — der Bot entschuldigt sich, nennt Ihre Kontaktdaten, und der Chat wird für Sie markiert. Der Grund wird auf dem Bildschirm „Aktionen“ angezeigt.

Weiterleitungen werden nicht gefolgt, und eine Antwort über 256 KB wird nicht gelesen.

Die Signatur prüfen

Anfragen werden nach dem Standard Webhooks-Verfahren signiert, Sie können also eine vorhandene Bibliothek verwenden. Ihr Signaturgeheimnis finden Sie auf dem Bildschirm „Aktionen“.

Von Hand: Verbinden Sie die ID, den Zeitstempel und den exakten Body mit Punkten, signieren Sie das mit HMAC-SHA256 unter Verwendung des Geheimnisses (der Teil nach whsec_, base64-dekodiert) und vergleichen Sie.

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));
}

Bei einer GET-Anfrage ist der Body leer, der signierte Text endet also mit einem Punkt. Verwenden Sie POST, wenn die Werte selbst von der Signatur abgedeckt sein sollen.

Wie der Bot sie verwendet

• Er fragt nach allem, was fehlt, eine kurze Frage nach der anderen, und merkt sich, was der Kunde zuvor im Chat gesagt hat.
• Er rät nie einen Wert. Hat der Kunde ihn nicht eingegeben, fragt der Bot nach.
• Eine Abfrage pro Nachricht. Ihre gespeicherten Antworten haben weiterhin Vorrang, sodass eine Frage, die Sie von Hand beantwortet haben, nie Ihre API aufruft.
• Antworten aus einer Abfrage werden nie für einen anderen Kunden wiederverwendet.
• Eine Abfrage zählt als eine Antwort, wie jede andere Antwort, die die KI schreibt.

Unter Chats steht bei einer Antwort, die aus einer Abfrage stammt, darunter, welche Aktion ausgeführt wurde und wie sie endete. Die vom Kunden eingegebenen Werte bleiben im Transkript und nirgendwo sonst.

Limits

Aktionen lesen Informationen. Richten Sie keine auf eine Adresse, die etwas verändert — eine Bestellung zu stornieren oder eine Rückerstattung auszulösen braucht einen Bestätigungsschritt, den der Bot noch nicht hat.