Den Verkaufsagenten anhalten, ohne eine Nachricht zu verlieren

Freitagabend: Die Monatsnutzung nähert sich dem Budget, und im Quelltext einer fremden Seite taucht der Kanalschlüssel des Website-Widgets auf. Beides verlangt eine schnelle Reaktion, und beides darf nicht dazu führen, dass Kunden ins Leere schreiben.

Die Steuerung des Agenten ist dafür gebaut, dass Anhalten nichts kaputtmacht: Der Stopp ist sofort wirksam, offene Gespräche erhalten einmal eine Abschlussnachricht, und eingehende Nachrichten werden weiter aufgenommen — nur nicht mehr vom Modell beantwortet.

Was dieser Fall voraussetzt

• Eine vorbereitete Abschlussnachricht. Wer sie erst im Vorfall formuliert, formuliert sie schlecht; hinterlegt werden kann sie in der Steuerung oder beim Stopp.
• Einen Kollegen, der die aufgenommenen Nachrichten sieht. Aufnehmen ohne Posteingang verschiebt das Problem nur.
• Eine Auslieferung, die das Widget-Skript sofort aktualisieren kann. Der alte Kanalschlüssel wirkt nach dem Wechsel sofort nicht mehr.
• Wissen, welche Zugangsangabe betroffen ist. Ein gezielter Widerruf trifft nur sie; ein pauschaler trifft den ganzen Kanal.

Der Ablauf

Die Tabelle nennt je Stufe den zuständigen Aufruf und das, was danach vorliegt. Die Begründung, warum die Stufe nicht übersprungen werden kann, steht darunter.

Warum jede Stufe nötig ist

1. Die Lage lesen. GET /agent/usage liefert für einen Monat die berechneten Beträge nach Erstattungen, Züge, Kollegenfragen und Gespräche — insgesamt, je Kanal und je Tag —, dazu balance und budgetState. So lässt sich entscheiden, ob der ganze Agent angehalten werden muss oder nur ein Kanal auffällt.
2. Anhalten. POST /agent/stop nimmt optional reason und closingMessage. Der Stopp ist sofort wirksam; offene Gespräche erhalten einmal die Abschlussnachricht, damit niemand ohne ein Wort wartet.
3. Weiter aufnehmen. POST /agent/conversations/record legt ein Gespräch in der Hand eines Kollegen an, speichert die Nachricht und antwortet nicht. Das ist der vorgesehene Weg für ein angehaltenes oder gedeckeltes Konto: Nichts geht verloren, und nichts wird berechnet.
4. Den Kanalschlüssel wechseln. POST /agent/channels/{channelId}/web-key/rotate gibt den neuen webKey genau einmal aus. Der alte wirkt sofort nicht mehr — deshalb gehört das neue Skript-Tag in dieselbe Auslieferung.
5. Zugang gezielt widerrufen. POST /agent/channels/{channelId}/credentials/revoke löscht mit purpose genau eine Zugangsangabe — etwa mail_smtp oder ebay_refresh_token. Ohne purpose wird der ganze Kanal widerrufen, weil ein Kanal ohne seinen Schlüssel stumm und trotzdem aktiv wäre.
6. Fortsetzen. POST /agent/resume nimmt den Betrieb wieder auf; ab der nächsten Nachricht werden Züge wieder beantwortet. Die in der Zwischenzeit aufgenommenen Gespräche bleiben beim Kollegen, bis er sie zurückgibt.

curl -X POST \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"reason":"Monatsbudget erreicht","closingMessage":"Ein Kollege meldet sich persönlich bei Ihnen."}' \
  'https://api.tapinomahub.com/hub/index.php/agent/stop'

Was am Ende vorliegt

Am Ende steht ein Vorfall, bei dem kein Kunde ohne Antwort blieb, kein Schlüssel länger galt als nötig und keine Nachricht verloren ging. Der Agent läuft wieder, und die Zwischenzeit ist im Posteingang nachvollziehbar.

Wo das in der Dokumentation steht

Die verbindlichen Feldlisten, Fehlercodes und Beispielantworten stehen im OpenAPI-Vertrag dieser Fläche unter docs.tapinomahub.com (tapinoma-agent). Alle Anwendungsfälle nach Fläche und Rolle geordnet: Übersicht der Anwendungsfälle.