Der Verkaufsagent antwortet im Widget der eigenen Website

Viele Anfragen zu einem Gebrauchtteil sind dieselben drei Fragen: Passt es an mein Fahrzeug, was kostet der Versand, in welchem Zustand ist es. Sie kommen abends und am Wochenende, und wer bis Montag wartet, kauft woanders. Ein Formular nimmt die Frage auf, beantwortet sie aber nicht.

Der Website-Kanal ist als Browser-Gateway gebaut, nicht als Hub-Aufruf mit versteckter Zugangskennung: Das Widget weist sich mit einem Kanalschlüssel aus, der sich jederzeit wechseln lässt. Ihr API-Schlüssel bleibt auf dem Server, wo er hingehört.

Was dieser Fall voraussetzt

• Ein eingerichtetes Profil. Der Agent antwortet nach seiner Anweisung; ohne Profil gibt es keinen Ton, keine Regeln und keine Befugnisse.
• Ein Website-Kanal mit erlaubten Ursprüngen. allowedOrigins legt fest, von welchen Adressen das Widget sprechen darf — das ist der Schutz gegen Fremdnutzung des Kanalschlüssels. Beim Einrichten des Widgets und beim Beginn eines Gesprächs muss der Origin der Anfrage einer dieser Ursprünge sein, sonst antwortet das Gateway mit origin_not_allowed.
• Das Besuchertoken. GET /web/channel gibt es aus; das Gateway erwartet es in der Kopfzeile X-Agent-Visitor zurück.
• Eine Stelle, an der Übergaben landen. needsHuman ohne Posteingang ist eine Warnung, die niemand liest.

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. Das Widget einrichten. GET /web/channel liefert title, greeting, accentColor, locale, pollIntervalSeconds und maxMessageChars. Die Oberfläche wird also nicht im Skript hart verdrahtet, sondern aus dem Kanal geladen — eine Änderung am Begrüßungstext braucht keinen neuen Seitenaufbau.
2. Das Gespräch beginnen. POST /web/conversations nimmt die erste Nachricht an und führt gleich den ersten Zug aus. Zurück kommen conversationId, seq und die Antwort, dazu needsHuman und owner. Ein zweiter Aufruf für die erste Antwort wäre eine vermeidbare Wartezeit.
3. Weiter antworten. POST /web/conversations/{conversationId}/messages führt jeden weiteren Zug aus. Die clientMessageId ist dabei wichtiger, als sie aussieht: Wird eine Nachricht mit derselben clientMessageId erneut abgeschickt, liefert der Aufruf die gespeicherte Antwort, statt noch einmal zu laufen.
4. Das Gespräch schliessen. POST /web/conversations/{conversationId}/close beendet es. Geschlossen heißt nicht gelöscht — der Verlauf bleibt im Posteingang nachvollziehbar, und genau das braucht man bei einer Beschwerde.

curl -X POST \
  -H 'X-Agent-Channel-Key: <KANALSCHLUESSEL>' \
  -H 'X-Agent-Visitor: <BESUCHERTOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{"message":"Passt der Scheinwerfer an einen Golf 7 Facelift?","clientMessageId":"m-1"}' \
  'https://api.tapinomahub.com/agent/api/index.php/web/conversations'

Was am Ende vorliegt

Am Ende beantwortet die Website die wiederkehrenden Fragen selbst und gibt die übrigen mit Verlauf an einen Kollegen weiter. Der Besucher wartet nicht bis Montag, und der Kollege beginnt nicht bei null.

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.