Wenn ein Kollege das Gespräch übernimmt

Ein Kunde schreibt, das gelieferte Steuergerät sei codiert und passe nicht. Das ist kein Standardfall: Es geht um Gewährleistung, um eine Rücksendung und vielleicht um Kulanz. Der Agent hat das erkannt und das Gespräch als übergabewürdig gekennzeichnet. Jetzt entscheidet die Organisation, nicht die Technik.

Übernahme und Rückgabe sind ausdrückliche Züge, keine Nebenwirkung. Der Grund ist einfach: Der eigentliche Schaden entsteht nicht, wenn ein Agent etwas nicht weiss, sondern wenn Agent und Mensch gleichzeitig antworten. Deshalb trägt jedes Gespräch jederzeit genau einen owner.

Was dieser Fall voraussetzt

• Eine Oberfläche für die Kollegen. Der Posteingang lässt sich über eine Browsersitzung öffnen, damit nicht jeder Mitarbeiter einen API-Schlüssel braucht.
• Eine Zuständigkeitsregel im Team. Wer übernimmt, muss auch zurückgeben; sonst bleibt der Agent für dieses Gespräch dauerhaft stumm.
• Ein Blick auf die Zähler. Was niemand liest, ist kein Posteingang, sondern ein Archiv.
• Eine Entscheidung über Preisangebote. Angebote lassen sich getrennt auflisten — wer sie nicht ansieht, verhandelt nicht, sondern wartet.

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. Den Posteingang überblicken. GET /agent/inbox/summary liefert die Zähler. Der Vorteil gegenüber einer Liste ist die Entscheidung vor dem Laden: Man sieht, ob überhaupt etwas wartet, bevor man vierzig Gespräche abruft.
2. Die Gespräche filtern. GET /agent/inbox/conversations kennt needsHuman, owner, unread, channelType und den Suchbegriff q über Betreff und Vorschau, dazu nextCursor. Für einen Arbeitsvorrat ist needsHuman der wichtigste Filter — er zeigt genau das, was der Agent selbst abgegeben hat.
3. Das Gespräch übernehmen. POST /agent/inbox/conversations/{conversationId}/takeover setzt den owner auf den Kollegen. Ab hier antwortet der Agent hier nicht mehr. Das Feld changed sagt, ob die Übernahme tatsächlich gewirkt hat oder ob ein anderer schneller war.
4. Den Agenten um Hilfe bitten. POST /agent/inbox/conversations/{conversationId}/assist gibt answer und suggestedReply zurück, dazu findings. Das ist der Unterschied zu einem Zug: Der Vorschlag geht nicht an den Kunden, sondern an den Kollegen. Abgeschickt wird von Hand.
5. Von Hand antworten. POST /agent/inbox/conversations/{conversationId}/reply sendet den Text und antwortet mit deliveryStatus. Auf einem Postfach- oder Marktplatzkanal wird die Antwort laut Vertrag zur Zustellung eingereiht, auf der Website gilt sie sofort als zugestellt; die einzelnen Werte von deliveryStatus legt der Vertrag nicht fest.
6. Zurückgeben. POST /agent/inbox/conversations/{conversationId}/release gibt das Gespräch an den Agenten zurück. Ohne diesen Schritt bleibt ein einmal übernommenes Gespräch für immer Handarbeit — der häufigste Grund, warum Automatisierung im Alltag versandet.

curl -H 'X-Api-Key: <API_KEY>' \
  'https://api.tapinomahub.com/hub/index.php/agent/inbox/conversations?needsHuman=true&limit=25'

Was am Ende vorliegt

Am Ende steht ein Gespräch, dessen Zuständigkeit zu jedem Zeitpunkt eindeutig war, und ein Team, das nur die Fälle bearbeitet, die tatsächlich einen Menschen brauchen. Der Agent bleibt für alles Übrige zuständig.

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.