Änderungsaktionen

Eine Änderung definieren#

Verwenden Sie eine Änderungsaktion, um einen Datensatz in Ihrem eigenen System zu aktualisieren, beispielsweise um eine Bestellung zu stornieren. Öffnen Sie Agent → Aktionen, konfigurieren Sie Ihr Agent-Secret unter Angemeldete Kunden und fügen Sie dann eine Änderungsaktion hinzu: einen eindeutigen Namen, eine Beschreibung, wann sie verwendet werden soll, einen öffentlichen HTTPS-Endpunkt und deklarierte String-Eingaben. Ein Name wie cancel_order wird zum Modell-Tool change_cancel_order. Bestehende Änderungen werden automatisch gespeichert; warten Sie auf die Speicheranzeige.

Lassen Sie Angemeldeten Kunden erforderlich für private Datensätze aktiviert. Ihr Endpunkt muss den angeforderten Datensatz trotzdem anhand der verifizierten Kunden-ID autorisieren. Ein im Chat eingegebener Name, eine E-Mail-Adresse oder eine Bestell-ID ist kein Identitätsnachweis. Wenn Sie diese Einstellung deaktivieren, kann customer null sein: Erlauben Sie dann nur Änderungen, die für anonyme Besucher geeignet sind. Zahlungen liegen außerhalb des Umfangs dieser Funktion.

Freigabe durch den Owner wählen#

Die Bestätigung durch den Kunden ist in jedem Modus erforderlich:

Prüfen Sie wartende Anfragen unter Agent → Aktionen → Freigaben. Der Website-Owner kann sie genehmigen oder ablehnen. Wenn private Telegram-Benachrichtigungen für den Owner verknüpft sind, enthält die Benachrichtigung zusätzlich die Schaltflächen Genehmigen / Ablehnen. Nur der private Chat des verknüpften Owners kann sie verwenden; abgelaufene oder wiederholte Tipps können keine erneute Ausführung auslösen. Die Freigabe läuft 24 Stunden nach der Bestätigung durch den Kunden ab. Der Kunde erhält das Ergebnis, einschließlich Ablehnung oder Ablauf. Die letzten Ausführungen zeigen Status, Zeitstempel, Referenz und Kunden-ID.

Was Ihr Endpunkt empfängt#

Wenn das Modell die Änderung vorschlägt, wird keine Anfrage gesendet. Nach der Bestätigung durch den Kunden und einer eventuell erforderlichen Freigabe durch den Owner sendet Make Agent Fast Folgendes:

POST /agent/cancel-order HTTP/1.1
Content-Type: application/json
x-maf-timestamp: <unix-seconds>
x-maf-signature: v1=<64-lowercase-hex-characters>
x-maf-idempotency-key: c5c1d94b-e88f-4bf6-8023-2dcd1e7ac67b

{
  "version": 1,
  "action": "cancel_order",
  "runId": "c5c1d94b-e88f-4bf6-8023-2dcd1e7ac67b",
  "requestId": "c5c1d94b-e88f-4bf6-8023-2dcd1e7ac67b",
  "siteId": "YOUR_SITE_ID",
  "input": { "order_id": "A128" },
  "customer": { "id": "customer_123", "email": "customer@example.com" }
}

action enthält das Präfix change_ nicht. Beide IDs und der Idempotenz-Header bleiben bei Wiederholungen gleich. input enthält nur deklarierte, getrimmte Strings; customer ist null oder das verifizierte Objekt mit id und optional email/name.

Verwenden Sie den Signaturprüfer für Abfragen: HMAC-SHA256 mit Ihrem Agent-Secret über "maf-webhook-v1:" + timestamp + "." + rawBody, in Kleinbuchstaben-Hex mit dem Präfix v1=. Prüfen Sie vor dem Schreiben die ursprünglichen Bytes, die Aktualität des Zeitstempels, die erwartete Site bzw. Aktion und die Zugehörigkeit des Datensatzes zum Kunden. Deduplizieren Sie x-maf-idempotency-key atomar zusammen mit Ihrer Änderung und speichern Sie das Ergebnis. Eine wiederholte Anfrage muss das gespeicherte Ergebnis zurückgeben, ohne den Datensatz erneut zu ändern. Die Sperrmechanismen der Plattform können die Deduplizierung in Ihrem System nicht ersetzen.

Ein Ergebnis zurückgeben#

Geben Sie 2xx-JSON mit dem erforderlichen Feld status (done, pending oder failed) und den optionalen Feldern message, reference und card zurück:

{
  "status": "done",
  "message": "Order cancelled.",
  "reference": "A128",
  "card": {
    "kind": "status",
    "title": "Order A128",
    "fields": [{ "label": "Order", "value": "A128" }]
  }
}

Die optionale Statuskarte erfordert title und fields; kind: "status" ist optional. Sie unterstützt status: { label, tone }, reference, asOf und link: { label, url }, wie bei Abfragen. Mögliche Tonalitäten sind neutral, success, warning oder danger; Links müssen sichere HTTPS-URLs sein. Unbekannte Schemafelder werden abgelehnt. Halten Sie Texte kurz und schlicht. Das äußere status bestimmt das Ergebnis; die Formulierung der Karte kann ein ausstehendes Ergebnis nicht in einen Erfolg verwandeln.

Verwenden Sie done erst, wenn die Änderung abgeschlossen ist, pending, wenn sie noch in Bearbeitung ist, und failed bei einem bekannten Fehler. Zeitüberschreitungen, Netzwerkfehler, 5xx-Antworten und ungültige Antworten gelten als ungewiss (unknown). Der Abgleich versucht es nach einer Minute und dann nach fünf Minuten erneut, mit höchstens drei Ausführungsversuchen und demselben Schlüssel; die Warteschlangenplanung kann diese Zeiten verzögern. HTTP 4xx schlägt ohne Wiederholung fehl. Bei erschöpfter Ungewissheit schlägt die Ausführung fehl und der Owner wird benachrichtigt; das beweist jedoch nicht, dass Ihr System keine Änderung vorgenommen hat. Prüfen Sie den Vorgang, bevor Sie eine weitere Ausführung starten. pending löst keine weitere Ausführung aus.

Einen signierten finalen Callback senden#

Sobald ein pending- oder unknown-Lauf geklärt ist, senden Sie per POST eine finale Antwort an https://makeagent.fast/api/agent/actions/RUN_ID/callback. Senden Sie denselben Antwortvertrag mit status: "done" oder "failed"; pending wird hier nicht akzeptiert.

Callback-Vertrag aktualisiert am 2026-10-14: Signieren Sie maf-callback-v1: + runId + : + timestamp + . + rawBody. Wenn der Body runId enthält, muss es mit der Run-ID im Pfad übereinstimmen; bei Abweichung wird 400 zurückgegeben. Signaturen für einen anderen Lauf oder im vorherigen ungebundenen Format liefern 403.

import { createHmac } from "node:crypto";

const body = JSON.stringify({ status: "done", reference: "A128" });
const timestamp = String(Math.floor(Date.now() / 1000));
const signature = createHmac("sha256", agentSecret)
  .update(`maf-callback-v1:${runId}:${timestamp}.${body}`)
  .digest("hex");
const response = await fetch(
  `https://makeagent.fast/api/agent/actions/${encodeURIComponent(runId)}/callback`,
  {
    method: "POST",
    headers: {
      "content-type": "application/json",
      "x-maf-timestamp": timestamp,
      "x-maf-signature": `v1=${signature}`,
    },
    body,
  },
);

Verwenden Sie Ihr serverseitig gespeichertes Agent-Secret und die Run-ID aus der ursprünglichen Anfrage. Der Callback verwendet maf-callback-v1:, nicht den Namensraum der ausgehenden Anfrage. Die Zeitabweichung muss innerhalb von fünf Minuten liegen. Ungültige Signaturen liefern 403, ungültige Bodys 400; ein bereits abgeschlossener oder inkompatibler Lauf liefert 409. Ein wiederholter Callback überschreibt das Endergebnis nicht. Rotieren Sie dieses Secret zusammen mit Ihrer Identitäts- und Endpunkt-Signaturkonfiguration.

Kundenbestätigung und Belege#

Der Kunde prüft die exakten Eingaben und tippt im Vorschlag auf Bestätigen oder Abbrechen. Ein Vorschlag läuft nach 15 Minuten ab; ein neuer Vorschlag für dieselbe Aktion bzw. Unterhaltung ersetzt den alten. Die Bestätigung verwendet ein Token, das an diesen Lauf, diese Site und diesen Besucher gebunden ist. Die Eingabe von „Ja“ oder ein Klick auf eine generische Bestätigungskarte autorisiert die Änderung nicht. Schaltflächen in der Probe sind inaktiv und rufen Ihren Endpunkt nicht auf.

Im Web fragt das geöffnete Widget nicht abgeschlossene Belege ab, zunächst alle fünf Sekunden und danach alle 30 Sekunden, bis zu 24 Stunden lang. Ein Beleg kann folgende Zustände anzeigen: angefordert, wartet auf Owner, läuft, ausstehend, unbekanntes Ergebnis wird geprüft, erledigt, fehlgeschlagen, abgelehnt, abgebrochen oder abgelaufen. Nur done bestätigt den Abschluss.

Vorschläge in Channels funktionieren nur in privaten Chats, nie in Gruppen oder Kanälen. Verzögerte Belege nutzen die dauerhafte Outbox: Gewöhnliche Telegram-Bot-DMs werden unterstützt; WhatsApp, Messenger, Instagram und Telegram Business erfordern eine erfasste eingehende Nachricht innerhalb von 24 Stunden, die beim Senden erneut geprüft wird. Verzögerte Zustellung ist für Telegram-Gastanfragen, Discord und KakaoTalk nicht verfügbar. Geschlossene Zeitfenster und deaktivierte Verbindungen können die Zustellung verhindern; der Ausführungsverlauf erfasst das Ergebnis dennoch.

Limits und Tests#

Verwenden Sie einen kontrollierten Endpunkt, um Bestätigung, Abbruch, Freigabe, Timeout, die Behandlung doppelter Schlüssel und finale Callbacks zu prüfen. Kontrollieren Sie dessen Datensätze, nicht nur den Belegtext. Die Probe beweist, dass kein externer Schreibzugriff erfolgt; sie ist kein Test der Endpunktausführung. Testen Sie jeden vorgesehenen privaten Channel, bevor Sie sich auf Belege verlassen.