Den Verkaufsagenten in die eigene Chat- oder Ticketsoftware einbauenAlle Beiträge

Den Verkaufsagenten in die eigene Chat- oder Ticketsoftware einbauen

Nicht jeder will ein fremdes Widget. Dieser Fall zeigt, wie ein Softwarehaus den Agenten in sein eigenes System holt, ohne ihm die Hand am Warenkorb zu geben.

Veröffentlicht: 2026-09-12Lesezeit: 5 mintapinomahub API & Prozesse
API & ProzesseAPIAutomotive AftermarketMarktplätzeTeilehandel

Ein Softwarehaus betreibt für Teilehändler ein eigenes Ticket- und Chatsystem. Die Kunden sollen schneller Antworten bekommen, aber niemand will, dass ein Sprachmodell selbstständig Adressen ändert oder Rücksendeetiketten verschickt. Die Frage ist also nicht, ob automatisch geantwortet wird, sondern wer handeln darf.

Der Agent formuliert, Ihr System handeltEingang: ein eigenes Chat- oder Ticketsystem, das Antworten braucht, aber selbst handeln will 1. Vertrag lesen (GET /agent/capabilities): actionTypes, intents und limits — einmal bei der Anbindung statt fest eingetragen 2. Gespräch anlegen (POST /agent/conversations): profileId als Pflichtfeld, optional channel und threadKey; zurück kommen conversationId und greeting 3. Zug ausführen (POST /agent/conversations/{conversationId}/messages): reply und actions; requiresConfirmation wartet auf Ihre Bestätigung im nächsten Zug 4. Ohne Zug anhängen (POST /agent/conversations/{conversationId}/ingest): author end_user oder note — gespeichert, ohne das Modell zu fragen 5. Gespräch schliessen (POST /agent/conversations/{conversationId}/close): outcome wie sold, not_sold oder handed_over, dazu orderRef Ausgang: Antworten aus dem Agenten, Handlungen aus Ihrem System — Aktionen mit requiresConfirmation bestätigt Ihr System im nächsten Zug über confirmations Der Agent führt Aktionen nicht selbst aus. Er schlägt sie vor; Ergebnis und Bestätigung kommen mit dem nächsten Zug als toolResults und confirmations zurück.Der Agent formuliert, Ihr System handeltEingang: ein eigenes Chat- oder Ticketsystem, das Antworten braucht, aber selbst handeln will01Vertrag lesenGET /agent/capabilitiesactionTypes, intents und limits — einmal bei der Anbindung statt fest eingetragen02Gespräch anlegenPOST /agent/conversationsprofileId als Pflichtfeld, optional channel und threadKey; zurück kommen conversationId undgreeting03Zug ausführenPOST /agent/conversations/{conversationId}/messagesreply und actions; requiresConfirmation wartet auf Ihre Bestätigung im nächsten Zug04Ohne Zug anhängenPOST /agent/conversations/{conversationId}/ingestauthor end_user oder note — gespeichert, ohne das Modell zu fragen05Gespräch schliessenPOST /agent/conversations/{conversationId}/closeoutcome wie sold, not_sold oder handed_over, dazu orderRefAusgang: Antworten aus dem Agenten, Handlungen aus Ihrem System — Aktionen mit requiresConfirmationbestätigt Ihr System im nächsten Zug über confirmationsDer Agent führt Aktionen nicht selbst aus. Er schlägt sie vor; Ergebnis und Bestätigung kommen mit dem nächstenZug als toolResults und confirmations zurück.
Fünf Aufrufe vom Vertrag bis zum Abschluss. Aktionen kommen als Vorschlag und gehen als Ergebnis zurück.

Die Hub-Schnittstelle des Agenten trennt beides sauber: Ein Zug liefert die Antwort und eine Liste von actions, die Ihr System ausführen soll. Was requiresConfirmation trägt, geschieht erst, wenn Ihr System es im nächsten Zug bestätigt. Der Agent formuliert, Ihr System handelt.

FlächeRollen
VerkaufsagentSoftwarehaus, Plattform und Marktplatz, Teilehandel

Was dieser Fall voraussetzt

  • Ein eingerichtetes Profil. POST /agent/conversations verlangt eine profileId; ohne Profil gibt es keine Anweisung, keinen Ton und keine Befugnisse.
  • Eigene Werkzeuge für die Aktionen. Was der Agent vorschlägt, muss Ihr System ausführen können — eine Sendungsauskunft, eine Adressänderung, ein Rücksendeetikett.
  • Eine Stelle, die Bestätigungen einholt. Eine Aktion mit requiresConfirmation wartet auf ein ausdrückliches Ja.
  • Den API-Schlüssel auf dem Server. Diese Schnittstelle ist für Ihr Backend gedacht, nicht für den Browser des Kunden.

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.

Die Aufrufkette dieses Anwendungsfalls
StufeAufrufWas danach vorliegt
Vertrag lesenGET /agent/capabilitiesactionTypes, intents und limits — einmal bei der Anbindung statt fest eingetragen
Gespräch anlegenPOST /agent/conversationsprofileId als Pflichtfeld, optional channel und threadKey; zurück kommen conversationId und greeting
Zug ausführenPOST /agent/conversations/{conversationId}/messagesreply und actions; requiresConfirmation wartet auf Ihre Bestätigung im nächsten Zug
Ohne Zug anhängenPOST /agent/conversations/{conversationId}/ingestauthor end_user oder note — gespeichert, ohne das Modell zu fragen
Gespräch schliessenPOST /agent/conversations/{conversationId}/closeoutcome wie sold, not_sold oder handed_over, dazu orderRef

Warum jede Stufe nötig ist

  1. Den Vertrag lesen. GET /agent/capabilities nennt Formate, Kanäle, actionTypes, intents und limits. Der Vertrag empfiehlt ausdrücklich, ihn einmal bei der Anbindung zu lesen, statt Grenzen fest einzutragen — sonst veraltet Ihre Integration mit der nächsten Erweiterung still.
  2. Das Gespräch anlegen. POST /agent/conversations verlangt profileId und nimmt optional unter anderem channel, threadKey, subject und externalRef. Welche Wirkung threadKey beim Anlegen hat, beschreibt der Vertrag nicht; GET /agent/inbox/conversations lässt sich nach threadKey als genauem Verlaufsschlüssel filtern.
  3. Den Zug ausführen. POST /agent/conversations/{conversationId}/messages liefert reply, intent, needsHuman, findings und actions. Jede Aktion trägt type — customer_tool, hub_call, handoff oder request_photo — und gegebenenfalls requiresConfirmation. Die Ergebnisse gehen im nächsten Zug als toolResults zurück, die Bestätigungen als confirmations.
  4. Ohne Zug anhängen. POST /agent/conversations/{conversationId}/ingest speichert eine Nachricht oder eine interne Notiz mit author end_user oder note, ohne das Modell zu fragen. Das ist der Weg für Gespräche, die gerade ein Kollege führt.
  5. Das Gespräch schliessen. POST /agent/conversations/{conversationId}/close nimmt outcome — etwa sold, not_sold, handed_over oder spam — und optional orderRef. Der Abschluss ist keine Formalie: Erst mit ihm lässt sich auswerten, was der Agent tatsächlich bewirkt hat.
Eine vorgeschlagene Aktion im nächsten Zug bestätigen
curl -X POST \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"confirmations":[{"actionId":"<actionId>","confirmed":true}]}' \
  'https://api.tapinomahub.com/hub/index.php/agent/conversations/<conversationId>/messages'

Was am Ende vorliegt

Am Ende antwortet Ihr System schneller, ohne dass der Agent je selbst etwas an einem Auftrag verändert. Jede Handlung geht durch Ihre Werkzeuge, jede heikle Handlung durch eine Bestätigung — und jedes Gespräch endet mit einem auswertbaren Ergebnis.

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.

Quellen und Rechtsgrundlagen

Häufige Fragen

Führt der Agent Aktionen selbst aus?

Nein. Er liefert sie als Vorschlag in actions. Ihr System führt sie aus und meldet das Ergebnis im nächsten Zug als toolResults.

Wozu gibt es ingest, wenn es doch Züge gibt?

Für Nachrichten, auf die das Modell nicht antworten soll — etwa wenn ein Kollege das Gespräch führt oder eine interne Notiz dazugehört. Solche Nachrichten fragen das Modell nicht.

Muss ich Grenzen wie die Nachrichtenlänge selbst pflegen?

Nein. Sie stehen in GET /agent/capabilities unter limits. Lesen Sie sie bei der Anbindung, statt sie fest einzutragen.

Passend dazu

API & ProzesseAnwendungsfälle der tapinomahub-APIsEndpunkte einzeln zu lesen erklärt, was ein Aufruf tut. Diese Übersicht erklärt, welche Aufrufe zusammen eine Aufgabe erledigen — und auf welcher der vier Flächen Ihre Aufgabe liegt.API & ProzesseDen Agenten anweisen und ihm eine Obergrenze gebenEin Agent ohne Anweisung antwortet beliebig, ein Agent ohne Deckel kostet beliebig. Dieser Fall zeigt, wie beides vor dem ersten Gespräch festgelegt wird.API & ProzesseDer Verkaufsagent antwortet im Widget der eigenen WebsiteAnfragen kommen nachts und am Wochenende. Dieser Fall zeigt, wie ein Widget sie beantwortet, ohne dass ein Browserskript je Ihren API-Schlüssel sieht.KI & DatenSchnittstelle anbinden: Wann sich eine API für Verwerter lohntEine Schnittstelle ersetzt das Abtippen zwischen zwei Systemen. Ob sie sich lohnt, entscheidet nicht die Technik, sondern die Zahl der Vorgänge pro Woche.