Zum Inhalt springen
XICBOT

Einstellungen

English
Dokumentation · Werkzeuge und Aktionen

Werkzeuge anlegen und freigeben

Werkzeuge unter Auslöser › Werkzeuge anlegen: Bauformen, Schlüssel, Pflichtangaben, Mindestrolle, Freigabe und die Anbindung eigener Schnittstellen.

In einfacher Sprache

Diese Seite erklärt Werkzeuge. Mit einem Werkzeug kann der Assistent etwas tun, nicht nur antworten. Er kann zum Beispiel eine Anfrage aufnehmen oder einen Termin vereinbaren. Er kann auch an einen Menschen übergeben. Jedes Werkzeug gehört zu einem Assistenten. Sie legen fest, welche Angaben Pflicht sind. Sie legen auch fest, wer ein Werkzeug nutzen und ändern darf. Die Seite erklärt auch die Freigabe.

Stand

Alle Themen der Dokumentation

Werkzeuge lassen einen Assistenten im Gespräch handeln, statt nur zu antworten: eine Anfrage aufnehmen, einen Termin vereinbaren, an einen Menschen übergeben, im Katalog suchen oder ein angebundenes System fragen. Jedes Werkzeug gehört zu einem Assistenten. Diese Seite beschreibt, wie Sie Werkzeuge anlegen, welche Bauformen es gibt, wie Sie eine eigene Schnittstelle anbinden, welche Angaben Pflicht sind und wer ein Werkzeug auslösen, ändern und freigeben darf.

Wo Sie Werkzeuge finden

Öffnen Sie Auslöser › Werkzeuge (app.xicbot.de/werkzeuge). Auf dem Reiter Werkzeuge wählen Sie unter Assistent den Assistenten, dessen Werkzeuge Sie sehen oder ändern wollen. Die Karte Werkzeuge des Assistenten listet sie nach Schlüssel sortiert. Der Reiter Katalog daneben gehört zur Produktsuche, siehe Katalog und Shop.

  • Gibt es noch keinen Assistenten, bittet die Karte, zuerst einen anzulegen.
  • Das Formular Werkzeug hinzufügen erscheint erst, wenn ein Assistent gewählt und die Werkzeugliste geladen ist. Ohne Assistenten steht an seiner Stelle derselbe Hinweis mit Assistent anlegen, während des Ladens und nach einem Ausfall „Das Formular steht bereit, sobald die Werkzeugliste geladen ist.“
  • Hat der Assistent noch kein Werkzeug, steht dort „Für diesen Assistenten ist noch kein Werkzeug eingerichtet.“ Werkzeug hinzufügen führt zum Formular.
  • Scheitert das Laden, erscheint „Die Liste konnte nicht geladen werden.“ mit dem Knopf Erneut laden.
  • Ab sechs Werkzeugen erscheint das Feld Werkzeuge filtern. Es sucht nach Name oder Art und zeigt, wie viele Einträge passen. Passt keiner, steht dort „Kein Eintrag passt zu dieser Eingabe.“; Filter leeren setzt die Suche zurück.

Was eine Zeile zeigt

  • Die Bezeichnung, darunter Schlüssel und Beschreibung.
  • Bauform, Art und Freigabe, etwa „Termin vereinbaren · schreibend · mit Bestätigung“. Die Art ist lesend, schreibend oder unumkehrbar.
  • Bei einem Werkzeug, das nicht aktiv ist, zusätzlich inaktiv.
  • Mindestrolle und Pflichtangaben mit den Feldnamen, die beim Aufruf gefüllt sein müssen.
  • Rechts Bearbeiten und Löschen. Löschen fragt nach: „Dieses Werkzeug löschen? Bereits ausgelöste Vorgänge bleiben bestehen.“ Mit der Rolle Lesen steht dort nur Ansehen. Bearbeiten und Ansehen öffnen das Werkzeug im Formular, rollen es in Sicht und setzen den Fokus auf seine Überschrift „Bearbeiten: …“ mit der Bezeichnung. Nach dem Löschen steht „Das Werkzeug ist gelöscht.“ unter der Überschrift der Liste.

Bauformen

Die Bauform legt fest, was ein Werkzeug tut, welche Felder es erwartet und ob es lesend, schreibend oder unumkehrbar arbeitet. Die Auswahl ordnet die Bauformen nach Gruppen. Die Freigabe in der letzten Spalte ist die Vorgabe der Bauform: Sie gilt, wenn ein Werkzeug über die Schnittstelle ohne approval angelegt wird. Das Formular in der App beginnt jedes neue Werkzeug mit mit Bestätigung; bei lesenden Bauformen stellen Sie dort um, bei schreibenden und unumkehrbaren steht sie fest.

BauformtypeGruppeArtFreigabe
Anfrage aufnehmenleadEingebautschreibendmit Bestätigung
Termin vereinbarenappointmentEingebautschreibendmit Bestätigung
An einen Menschen übergebenhandoffEingebautschreibendmit Bestätigung
Im Katalog suchenproduct_searchEingebautlesendohne Rückfrage
Warenkorb übergebencartEingebautunumkehrbarmit Bestätigung
Eigene SchnittstellehttpEingebautlesendmit Bestätigung
Formular vorausfüllenform_fillEingebautschreibendmit Bestätigung
Freie Zeiten lesencalendar_availabilityKalenderlesendohne Rückfrage
Termin buchencalendar_bookingKalenderschreibendmit Bestätigung
Bestellstatus lesenorder_statusWarenwirtschaftlesendmit Bestätigung
Lagerbestand leseninventory_statusWarenwirtschaftlesendohne Rückfrage
Bestellung ändernorder_changeWarenwirtschaftschreibendmit Bestätigung
Preis lesenprice_lookupKataloglesendohne Rückfrage
Vorgänge lesencrm_activitiesKundenverwaltunglesendmit Bestätigung
Interessent anlegencrm_leadKundenverwaltungschreibendmit Bestätigung
Rückruf festhaltencallback_noteKundenverwaltungschreibendmit Bestätigung
Ticket erstellenticket_createTicketsystemschreibendmit Bestätigung

Die eingebauten Bauformen bringt der Dienst mit. Anfrage aufnehmen nimmt Name, E-Mail, Telefon und Anliegen als Anfrage auf und heftet Anhänge aus dem Gespräch an. Eigene Schnittstelle ruft eine Adresse Ihrer Wahl auf; auch die zehn Bauformen der übrigen Gruppen sprechen mit einem System, das Sie anbinden. Wie dieses System antworten muss, beschreibt der Werkzeugbausatz. Einzelheiten zu Anfragen, Übergaben und Terminen stehen unter Termine und Vorgänge, zum Formular unter Formulare vorausfüllen, zu Katalog und Warenkorb unter Katalog und Shop.

Was eine Übergabe auslöst

Die Bauform An einen Menschen übergeben verlangt den Grund der Übergabe (reason) und nimmt Name (name), E-Mail-Adresse (email) und Rufnummer (phone) mit, wenn der Besucher sie nennt. Der Besucher sieht den Vorschlag „An einen Menschen übergeben:“ mit dem Grund, unter einer englischen Antwort „Hand over to a person:“, und bestätigt ihn. Danach erledigt der Dienst diese Schritte nacheinander:

  1. Schritt 1

    Gespräch übergeben

    Das Gespräch erhält den Status übergeben, auch wenn es schon geschlossen war. Steht es noch auf übergeben, bleibt der bisherige Zeitpunkt der Übergabe stehen; sonst zählt die Übergabe ab jetzt. Der neue Grund wird mit Semikolon an einen früheren angehängt, zusammen höchstens 300 Zeichen.

  2. Schritt 2

    Anfrage anlegen

    Unter Vorgänge › Anfragen entsteht ein Eintrag mit dem Grund als Anliegen sowie Name (bis 120 Zeichen), E-Mail-Adresse (bis 190) und Rufnummer (bis 60), soweit genannt. Die Spalte Quelle nennt den Schlüssel des Werkzeugs. Bestätigt der Besucher im selben Gespräch dieselbe Eingabe für dasselbe Werkzeug ein zweites Mal, bleibt es bei einem Eintrag, und das Ergebnis meldet duplicate_prevented: true.

  3. Schritt 3

    Postfach und Weiterleitung

    Das Gespräch steht im Postfach. Die Regeln der Weiterleitung greifen, und das Ereignis handoff.triggered wird ausgelöst. Scheitert die Zuordnung, liegt das Gespräch ohne Stelle im Postfach, und das Ereignis geht trotzdem hinaus, dann in der Regel mit queue: null. Bestätigt der Besucher dieselbe Eingabe ein zweites Mal, während das Gespräch noch auf übergeben steht, entfallen der erste Schritt und dieser; steht es nicht mehr darauf, wird es erneut übergeben.

  4. Schritt 4

    Mail an Ihr Team

    Ist die Anfrage neu, wird eine Mail an die Adresse für die Übergabe eingereiht, die in der Fassung des Assistenten hinterlegt ist, mit der das Gespräch läuft, und zwar mit Vorrang: Priorität 3 statt der üblichen 5. Bei einem doppelten Aufruf geht keine zweite Mail hinaus. Was die Mail enthält, beschreibt Postfach.

  5. Schritt 5

    Rückmeldung an den Assistenten

    Das Ergebnis enthält lead_id, handed_off: true, duplicate_prevented und bei einer neuen Anfrage email_notified. email_notified: true heißt, dass die Mail eingereiht wurde, nicht, dass sie zugestellt ist. Dazu erhält der Assistent den Hinweis „Das Gespräch liegt jetzt im Postfach. Ein Mensch meldet sich.“ und die Vorgabe, den Weg der Benachrichtigung in seiner Antwort nicht zu nennen.

Werkzeug anlegen

  1. Schritt 1

    Assistent wählen

    Wählen Sie unter Assistent den Assistenten, der das Werkzeug benutzen soll, und klicken Sie auf Werkzeug hinzufügen.

  2. Schritt 2

    Bauform wählen

    Stellen Sie Bauform ein. Voreingestellt ist Anfrage aufnehmen. Nach dem Speichern lässt sich die Bauform nicht mehr wechseln.

  3. Schritt 3

    Grundangaben eintragen

    Tragen Sie Schlüssel, Bezeichnung und Wann soll der Assistent es benutzen? ein. Bei Eigene Schnittstelle und den Bauformen für angebundene Systeme kommen Adresse der Schnittstelle und Zugangsmarke hinzu.

  4. Schritt 4

    Felder und Pflichtangaben festlegen

    Bei Eigene Schnittstelle legen Sie unter Felder der Eingabe fest, was der Assistent übergibt. Bei Formular vorausfüllen ergeben sich die Felder aus der Zuordnung. Bei den übrigen Bauformen stehen die Felder fest, und Sie wählen nur, welche davon Pflichtangaben sind.

  5. Schritt 5

    Mindestrolle, Freigabe und Aktiv setzen

    Wählen Sie Mindestrolle und Freigabe. Voreingestellt sind Besucher (öffentlicher Chat), mit Bestätigung und ein gesetzter Haken bei Aktiv.

  6. Schritt 6

    Speichern

    Klicken Sie auf Speichern. Solange der Dienst prüft, steht auf dem Knopf Wird gespeichert …. Danach bietet sich das Werkzeug dem Assistenten an, sofern es aktiv ist und zu Rolle und Paket passt. Das Formular ist danach wieder leer, neben dem Knopf steht „Gespeichert: …“ mit der Bezeichnung, und der Fokus steht am Knopf Bearbeiten des gespeicherten Werkzeugs.

Schlüssel, Bezeichnung und Beschreibung

FeldRegelWozu
SchlüsselPflicht, 3 bis 64 Zeichen: ein Kleinbuchstabe am Anfang, danach Kleinbuchstaben, Ziffern und _. Je Assistent eindeutig und nach dem Speichern fest.Unter diesem Namen sieht der Assistent das Werkzeug.
BezeichnungPflicht, höchstens 120 ZeichenName in der Liste und in den Meldungen zu einem Aufruf
Wann soll der Assistent es benutzen?Pflicht, höchstens 600 ZeichenSagt dem Assistenten, wann das Werkzeug passt. Je genauer der Text, desto seltener wird es falsch eingesetzt.

Ist der Schlüssel beim Assistenten schon vergeben, meldet das Formular „Diesen Schlüssel gibt es bei diesem Assistenten schon.“ Bei Werkzeugen, die nicht nur lesen, ergänzt der Dienst Ihre Beschreibung von sich aus: Der Assistent erfährt, dass der Aufruf nichts sofort ausführt, sondern dem Besucher einen Vorschlag zum Bestätigen oder Ablehnen zeigt, und dass er das Werkzeug je Anliegen höchstens einmal aufrufen soll. Das brauchen Sie nicht selbst hineinzuschreiben.

Eigene Schnittstellen anbinden

Eigene Schnittstelle und die zehn Bauformen für angebundene Systeme rufen eine Adresse auf, die Sie hinterlegen. Dafür gibt es zwei Felder:

  • Adresse der Schnittstelle: Pflicht, beginnt mit http:// oder https:// und hat im Formular höchstens 500 Zeichen, etwa https://example.com/werkzeug.
  • Zugangsmarke: freiwillig, höchstens 500 Zeichen, verdeckt eingegeben. Ist eine hinterlegt, geht sie beim Aufruf als Kopfzeile authorization: Bearer … mit. Der Dienst gibt sie nicht wieder heraus, sondern zeigt an ihrer Stelle __set__. Unter dem Feld steht dann „Eine Marke ist hinterlegt. Ein neuer Wert ersetzt sie, ein leeres Feld lässt sie unverändert.“
  • Über die Schnittstelle bleibt eine hinterlegte Marke erhalten, wenn token fehlt oder __set__ enthält; ein leerer Wert entfernt sie.

Adresse und Zugangsmarke trägt ein oder ändert, wer die Rolle Verwaltung oder Inhaber hat. Mit der Rolle Bearbeiten sind beide Felder gesperrt: Ein solches Werkzeug neu anlegen lässt sich dann nicht, bei einem bestehenden lassen sich aber die übrigen Angaben ändern. Das Formular sagt dazu „Adresse und Zugangsmarke ändert, wer die Rolle Verwaltung oder Inhaber hat. Die übrigen Angaben lassen sich mit der Rolle Bearbeiten ändern.“

Welche Adressen erlaubt sind

Der Dienst prüft die Adresse beim Speichern und erneut bei jedem Aufruf. Erlaubt sind http und https. Geprüft wird nicht der Name, sondern jede Adresse, auf die er aufgelöst wird: Zeigt eine davon nicht ins offene Netz, lehnt der Dienst das Ziel ab. Beim Aufruf verbindet er sich mit genau der geprüften Adresse, sodass ein zwischendurch geänderter Namenseintrag nicht auf ein anderes Ziel umlenkt. Beim Speichern antwortet er mit Status 422 und einem dieser Codes. Die App zeigt dazu den Satz aus der letzten Spalte am Feld Adresse der Schnittstelle und zusätzlich oben auf der Seite:

CodeBedeutungMeldung in der App
url_requiredDie Bauform spricht mit einem angebundenen System, aber die Adresse fehlt.„Diese Bauform spricht mit einem fremden System. Ohne Adresse der Schnittstelle kann sie nicht arbeiten.“
url_unreadableDie Adresse lässt sich nicht lesen.„Diese Adresse ist nicht lesbar. Bitte geben Sie sie vollständig mit https:// an.“
scheme_not_allowedSie beginnt nicht mit http oder https.„Nur Adressen mit http:// oder https:// lassen sich abrufen.“
name_unresolvableDer Name lässt sich nicht auflösen.„Der Name dieser Adresse lässt sich nicht auflösen. Bitte prüfen Sie die Schreibweise.“
target_not_allowedMindestens eine aufgelöste Adresse liegt nicht im offenen Netz.„Diese Adresse zeigt nicht ins öffentliche Netz und wird darum nicht abgerufen, etwa eine Adresse im Firmennetz.“

Was Ihr System bekommt

Jeder Aufruf ist ein POST mit JSON-Körper und den Kopfzeilen content-type: application/json und accept: application/json, bei hinterlegter Marke dazu authorization: Bearer …. Eine Eigene Schnittstelle schickt den Schlüssel des Werkzeugs, die Eingabe und die Kennung des Gesprächs:

anfrage.json json

{
  "tool": "lieferzeit",
  "input": { "plz": "10115" },
  "conversation_id": "…"
}

Die Bauformen für angebundene Systeme schicken zusätzlich adapter, domain, operation und action mit. Arbeitet die Bauform nicht nur lesend, trägt der Aufruf außerdem die Kopfzeile idempotency-key: einen Schlüssel aus 64 Zeichen, der für dieselbe Eingabe im selben Gespräch gleich bleibt. Daran kann Ihr System einen doppelt eingegangenen Auftrag erkennen. Den genauen Aufbau beschreibt der Werkzeugbausatz.

  • Ihr System hat 8 Sekunden Zeit für die Antwort. Über die Schnittstelle lässt sich die Frist mit der Einstellung deadline_s zwischen 1 und 20 Sekunden setzen; im Formular gibt es dafür kein Feld, und ein Speichern im Formular setzt die Frist wieder auf 8 Sekunden. Für den Verbindungsaufbau gelten höchstens 5 Sekunden.
  • Weiterleitungen folgt der Dienst nicht; eine Antwort mit Status 300 bis 399 gilt als Fehler.
  • Die Antwort darf höchstens 64 KB groß sein, sonst wird sie verworfen.
  • Bei einer Eigenen Schnittstelle übernimmt der Dienst JSON unter data. Ist die Antwort kein JSON, nimmt er die ersten 2000 Zeichen als text. Dazu kommt der Status.
  • Die Bauformen für angebundene Systeme erwarten eine Antwort mit dem Feld ok. Übernommen werden nur die Ergebnisfelder der Bauform, Texte bis 600 Zeichen und Listen bis 20 Einträge.

Wenn die Anbindung scheitert

Ein gescheiterter Aufruf wird nicht wiederholt. Er endet mit einer der folgenden Meldungen und ist danach in der Werkzeugkarte als fehlgeschlagen oder als Zeitgrenze überschritten zu sehen.

MeldungZustand
„Für dieses Werkzeug ist keine gültige Adresse hinterlegt.“fehlgeschlagen
„Die hinterlegte Adresse zeigt nicht ins offene Netz.“fehlgeschlagen
„Das Werkzeug war nicht erreichbar.“fehlgeschlagen
„Das Werkzeug hat innerhalb von 8 Sekunden nicht geantwortet.“ (mit der eingestellten Frist)Zeitgrenze überschritten
„Das Werkzeug hat weitergeleitet (Status 302). Einer Weiterleitung folgt es nicht.“fehlgeschlagen
„Das Werkzeug hat mit Status 500 geantwortet.“fehlgeschlagen
„Das Werkzeug hat mehr als 64 KB geliefert. Die Antwort wurde verworfen.“fehlgeschlagen
„Das angebundene System hat nicht nach dem Anbindungsvertrag geantwortet.“fehlgeschlagen
„Das angebundene System hat den Vorgang abgelehnt.“, mit Grund, falls Ihr System einen nenntfehlgeschlagen

Felder der Eingabe

Die Felder legen fest, welche Angaben der Assistent beim Aufruf übergibt. Bei allen Bauformen außer Eigene Schnittstelle stehen sie fest, und das Formular zeigt „Die Felder dieser Bauform stehen fest und lassen sich nicht ändern.“ Bei Formular vorausfüllen ergeben sie sich aus der Zuordnung zu Ihrem Formular. Für eine Eigene Schnittstelle legen Sie sie unter Felder der Eingabe selbst an:

AngabeRegel
FeldnameKleinbuchstabe am Anfang, danach Kleinbuchstaben, Ziffern und _, höchstens 40 Zeichen. Die Regel steht samt den gesperrten Namen tenant_id, mandant, mandant_id und konto_id unter Felder der Eingabe. Einen Namen, der nicht passt, einen gesperrten, einen doppelten und eine Zeile ohne Namen meldet das Formular am Feld, bevor es speichert; über die Schnittstelle antwortet der Dienst mit 422 und dem Feldnamen. Gespeichert wird dann nichts. Den Namen schreibt der Dienst nicht um: Er ist der Schlüssel, den Ihr System erhält.
Typstring, integer, number oder boolean; jeden anderen Wert speichert der Dienst als string.
BeschreibungHöchstens 200 Zeichen. Fehlt description bei einem Feld, das über die Schnittstelle kommt, nimmt der Dienst den Feldnamen.
PflichtMacht das Feld zur Pflichtangabe.
AnzahlHöchstens 20 Felder. Ab dem 20. ist Feld hinzufügen gesperrt, und darunter steht „Höchstens 20 Felder.“; mehr lehnt der Dienst mit 422 ab. Feld hinzufügen und Feld entfernen ändern die Liste.

Was der Assistent übergibt, bereinigt der Dienst vor dem Aufruf: Er behält nur Felder, die im Schema stehen, kürzt Texte auf 2000 Zeichen und Listen auf 50 Einträge.

Pflichtangaben

Unter Pflichtangaben haken Sie an, welche Felder beim Aufruf gefüllt sein müssen, bis zu 20. Manche verlangt die Bauform selbst: Sie sind mit „von der Bauform verlangt“ markiert und lassen sich nicht abwählen, etwa subject bei Anfrage aufnehmen, starts_at bei Termin vereinbaren und reason bei An einen Menschen übergeben. Hat eine Bauform keine wählbaren Felder, steht dort „Diese Bauform hat keine wählbaren Felder.“ Angehakt werden können nur Felder, die es in der Bauform gibt.

Als leer gilt ein fehlender Wert, ein Text nur aus Leerzeichen und eine leere Liste; 0 und false zählen als Angabe. Der Dienst prüft beim Aufruf und noch einmal, wenn der Besucher bestätigt. Fehlt etwas, endet der Aufruf als fehlgeschlagen mit der Vorschau „Unvollständige Angaben für …“, und der Assistent erfährt, welche Angaben fehlen, damit er den Besucher danach fragt. So steht es auch im Formular: „Ohne diese Angaben wird der Aufruf abgewiesen und der Assistent fragt nach, statt einen unvollständigen Eintrag anzulegen.“

Mindestrolle

Mindestrolle legt fest, wer ein Werkzeug auslösen kann. Die Stufen bauen aufeinander auf; wer eine höhere erreicht, darf auch alles darunter.

StufeWer sie erreicht
Besucher (öffentlicher Chat)Jeder, auch im Chatfenster auf Ihrer Website
AngemeldetAufrufe über die Schnittstelle und Personen im Team mit der Rolle Lesen oder Bearbeiten
VerwaltungPersonen im Team mit der Rolle Verwaltung oder Inhaber
InhaberDer Inhaber des Kontos
  • Das Chatfenster auf Ihrer Website zählt als Besucher, auch wenn im selben Browser jemand in der App angemeldet ist. Ein Werkzeug mit höherer Mindestrolle bietet der Dienst dort nicht an; kommt es doch zu einem Aufruf, endet er als fehlgeschlagen mit „Nicht freigegeben: …“.
  • Voreingestellt ist Besucher (öffentlicher Chat).
  • Beim Anlegen stehen die Stufen bis zur eigenen Rolle zur Wahl, mit der Rolle Bearbeiten also bis Angemeldet. Das Formular sagt dazu „Zur Wahl stehen die Stufen bis zur eigenen Rolle.“ Über die Schnittstelle antwortet der Dienst auf eine höhere Stufe mit 403 role_too_low und field: min_role.
  • Die Mindestrolle eines bestehenden Werkzeugs ändert, wer die Rolle Verwaltung oder Inhaber hat. Für alle anderen ist das Feld gesperrt, mit dem Hinweis „Die Mindestrolle eines bestehenden Werkzeugs ändert, wer die Rolle Verwaltung oder Inhaber hat.“

Freigabe

Freigabe bestimmt, ob ein Aufruf sofort läuft oder erst nach einer Bestätigung. Bei schreibenden und unumkehrbaren Bauformen steht sie fest auf mit Bestätigung; das Feld ist gesperrt, auch wenn über die Schnittstelle etwas anderes kommt. Bei lesenden Bauformen wählen Sie zwischen mit Bestätigung und ohne Rückfrage. Sofort läuft ein Aufruf nur, wenn das Werkzeug lesend ist und auf ohne Rückfrage steht. Eine Ausnahme ist das Nachsehen freier Zeiten bei Termin vereinbaren: Es ändert nichts und läuft darum ohne Bestätigung.

Aktiv und abgeschaltet

Mit dem Haken Aktiv schalten Sie ein Werkzeug ein oder ab, ohne es zu löschen. Ein abgeschaltetes Werkzeug bietet der Dienst dem Assistenten ab dessen nächster Antwort nicht mehr an, auch in einem Gespräch, das schon läuft; ein Aufruf endet dann als fehlgeschlagen mit „Dieses Werkzeug gibt es für diesen Assistenten nicht.“ In der Liste steht es mit dem Zusatz inaktiv. Ein Vorschlag, der beim Abschalten schon offen war, lässt sich innerhalb seiner 60 Minuten noch bestätigen und wird dann ausgeführt; offene Vorschläge beendet erst das Löschen. Einstellungen und bisherige Vorgänge bleiben erhalten.

Wer im Team was darf

RolleWas sie bei Werkzeugen darf
LesenListe und Einstellungen ansehen. Das Formular sagt dazu „Mit der Rolle Lesen lässt sich hier nur ansehen. Ändern kann, wer mindestens die Rolle Bearbeiten hat.“
BearbeitenWerkzeuge anlegen, ändern und löschen, ohne Adresse und Zugangsmarke; Mindestrolle bis Angemeldet; Vorschläge in der App bestätigen oder ablehnen
VerwaltungZusätzlich Adresse, Zugangsmarke und die Mindestrolle bestehender Werkzeuge; Mindestrolle bis Verwaltung
InhaberWie Verwaltung, Mindestrolle bis Inhaber

Fehlt die nötige Rolle, antwortet die Schnittstelle mit 403 role_too_low. Das Feld required nennt die nötige Rolle, field das betroffene Feld, etwa settings.url oder min_role. Wie Rollen vergeben werden, beschreibt Team und Rollen.

Ändern und löschen

  • Bauform und Schlüssel stehen nach dem Anlegen fest. Alles andere lässt sich ändern. Die Änderung gilt für jede Ausführung danach, auch für Vorschläge, die noch auf Bestätigung warten; bereits ausgeführte Aufrufe bleiben, wie sie sind. Nur der Haken Aktiv hält einen offenen Vorschlag nicht auf, siehe Aktiv und abgeschaltet.
  • Gibt es die Bauform eines bestehenden Werkzeugs nicht mehr, steht im Formular unter Bauform „Diese Bauform gibt es nicht mehr. Das Werkzeug lässt sich darum nicht mehr ändern, nur löschen.“, und Speichern ist gesperrt. Denselben Satz zeigt die App, wenn der Dienst das Speichern mit shape_unknown ablehnt.
  • Jede Änderung schreibt einen Eintrag ins Protokoll: tool.created, tool.updated oder tool.deleted, beim Ändern mit der Liste der geänderten Felder. Kommt der Eintrag nicht zustande, speichert der Dienst nichts und die App meldet „Nicht gespeichert: Der Eintrag ins Protokoll kam nicht zustande. Bitte versuchen Sie es erneut.“ Das Protokoll finden Sie unter Team und Rollen.
  • Löschen entfernt das Werkzeug, bereits ausgelöste Vorgänge bleiben bestehen. Danach erscheint „Das Werkzeug ist gelöscht.“ Bestätigt ein Besucher später noch einen offenen Vorschlag dieses Werkzeugs, endet er mit „Das Werkzeug wurde inzwischen entfernt.“
  • Ist das Werkzeug oder sein Assistent inzwischen gelöscht, etwa in einem anderen Fenster, meldet die App beim Speichern oder Löschen „Diesen Eintrag gibt es nicht mehr. Laden Sie die Seite neu, um den aktuellen Stand zu sehen.“
  • Anlegen und Ändern sind auf 30 Vorgänge je Minute und angemeldeter Person begrenzt; der Zähler gilt gemeinsam mit anderen Änderungen an Assistenten. Darüber meldet die App „Zu viele Versuche. Bitte warten Sie einen Moment.“

Die Werkzeugkarte im Gespräch

Ruft der Assistent ein Werkzeug auf, prüft der Dienst zuerst, ob es zu diesem Assistenten gehört, ob die Mindestrolle erreicht ist, ob die Bauform zum Paket passt und ob alle Pflichtangaben da sind. Scheitert eine dieser Prüfungen, endet der Aufruf als fehlgeschlagen, etwa mit „Nicht freigegeben: …“ oder „Nicht verfügbar: …“ und der Bezeichnung des Werkzeugs. Vorschauen stehen in der Sprache der Antwort, unter der die Karte erscheint: unter einer englischen Antwort auf Englisch, etwa „Not approved: …“, auch bei den Bauformen für angebundene Systeme, etwa „Check order status for order …“ bei Bestellstatus lesen. Ist die Antwort weder deutsch noch englisch, richtet sich die Vorschau nach dem Gespräch und danach nach der Fassung des Assistenten; ergibt sich daraus kein Englisch, steht sie auf Deutsch. Jeder Aufruf steht als Eintrag im Gespräch, bevor er ausgeführt wird, und wird danach mit Ergebnis oder Fehler fortgeschrieben. Läuft das Werkzeug nicht sofort, entsteht ein Vorschlag: Der Besucher sieht im Chatfenster eine Karte und bestätigt oder lehnt ab. Wie diese Karte im Chatfenster aussieht, beschreibt Gespräch im Widget.

  • Ein Vorschlag gilt 60 Minuten. Solange niemand entscheidet, bleibt er vorgeschlagen. Wer später bestätigt oder ablehnt, bekommt ihn als abgelaufen zurück, und ausgeführt wird nichts.
  • Beim Bestätigen prüft der Dienst erneut, ob das Werkzeug noch besteht, ob Mindestrolle und Paket passen und ob die Pflichtangaben da sind. Erst dann führt er den Aufruf aus.
  • Ein doppelter Klick löst nichts doppelt aus. Ist ein Vorschlag schon entschieden, meldet die Antwort duplicate: true und liefert den bestehenden Stand. Schlägt der Assistent im selben Gespräch dieselbe Eingabe zweimal vor und werden beide bestätigt, entsteht die Anfrage, der Termin oder die Warenkorbübergabe nur einmal.
  • Je Antwort des Assistenten sind höchstens 5 Werkzeugaufrufe möglich. Ruft er je Runde ein Werkzeug auf, hält er nach der fünften Runde ohne weitere Karte an und schreibt einen Hinweis in seine Antwort; diesen Hinweis und den engeren Deckel bei gedrosseltem Konto beschreibt Gespräch im Widget. Fordert er in einer Runde mehrere Werkzeuge an und überschreitet so die 5 Aufrufe, endet jeder weitere als fehlgeschlagen: Im Gespräch steht „Der Assistent hat für diese Antwort zu viele Schritte gebraucht und wurde angehalten.“, unter einer englischen Antwort „The assistant needed too many steps for this answer and was stopped.“; die Karte in der App zeigt unter Fehler „Der Deckel von 5 Werkzeugaufrufen je Antwort ist erreicht.“

Zustände eines Aufrufs

ZustandCodeBedeutung
vorgeschlagenproposedWartet auf Bestätigung oder Ablehnung
bestätigtconfirmedBestätigt, die Ausführung läuft
ausgeführtexecutedErfolgreich erledigt
abgelehntrejectedAbgelehnt, es wurde nichts ausgeführt
abgelaufenexpiredErst nach mehr als 60 Minuten bestätigt oder abgelehnt, es wurde nichts ausgeführt
fehlgeschlagenfailedEine Prüfung oder die Ausführung ist gescheitert
Zeitgrenze überschrittentimeoutDas angebundene System hat nicht rechtzeitig geantwortet

Vorschläge in der App entscheiden

Werkzeugaufrufe sehen Sie unter Gespräche im Verlauf des jeweiligen Gesprächs. Die Karte zeigt Werkzeug mit dem Schlüssel, den Zustand, die Dauer in Millisekunden und die Vorschau, dazu Eingabe, Ergebnis und bei einem Fehler Fehler mit der Meldung. Über einen offenen Vorschlag in einem Gespräch der Kanäle Test und Schnittstelle entscheiden Sie mit der Rolle Bearbeiten oder höher: dort steht „Wartet auf Bestätigung.“ mit Bestätigen und Ablehnen. Im Kanal Widget entscheidet der Besucher im Chatfenster; die Karte zeigt dann „Wartet auf die Bestätigung durch den Besucher im Chatfenster.“ und keine Knöpfe.

Werkzeuge über die Schnittstelle

Werkzeuge lassen sich auch über die Schnittstelle verwalten. Anmeldung und Grenzen beschreiben Anmeldung an der Schnittstelle und Grenzen der Schnittstelle.

GET /api/v1/assistants/{assistant}/tools

Listet die Werkzeuge des Assistenten nach Schlüssel unter tools und die Bauformen unter shapes. Jedes Werkzeug trägt unter anderem key, die Bauform unter adapter, kind, approval, min_role, is_active und die wirksamen Pflichtangaben unter required_effective; eine Zugangsmarke erscheint als __set__. Bei der Bauform Termin vereinbaren zeigt timezone_valid mit true oder false, ob die hinterlegte Zeitzone gilt, nach demselben Urteil wie beim Speichern; bei allen anderen Bauformen steht dort null. Dasselbe Feld trägt das Werkzeug in der Antwort beim Anlegen und Ändern. Die Bauform http nennt unter schema_rules die Regel ihrer Feldnamen: pattern (ohne Anker), max und die gesperrten Namen unter reserved; bei allen anderen Bauformen steht dort null.

Anmeldung
Angemeldet, jede Rolle

POST /api/v1/assistants/{assistant}/tools

Legt ein Werkzeug an. Pflicht sind type, key, title und description; dazu kommen wahlweise approval, min_role, required_fields, schema, settings und is_active. Antwortet mit 201 und dem Werkzeug unter tool. Fehlercodes: 422 key_taken, shape_unknown, url_required und die Codes der Zielprüfung, bei Eigene Schnittstelle schema_field_name_invalid, schema_field_name_reserved und schema_required_unknown mit dem Feldnamen unter field sowie schema_fields_too_many mit max, bei Termin vereinbaren, Warenkorb übergeben und Formular vorausfüllen außerdem die Codes der Prüfung ihrer Einstellungen, etwa appointment_timezone_invalid für eine unbekannte Zeitzone, 403 role_too_low, 402 plan_feature_missing.

Anmeldung
Angemeldet, Rolle Bearbeiten oder höher
Begrenzung
30 je Minute und angemeldeter Person, gemeinsam mit anderen Änderungen an Assistenten

PUT /api/v1/tools/{id}

Ändert ein Werkzeug. type und key lassen sich nicht ändern; die übrigen Felder wie beim Anlegen. Fehlende Angaben behandelt der Dienst verschieden: min_role, required_fields, is_active und approval bleiben stehen, und ohne settings speichert er das Werkzeug ohne Einstellungen, also auch ohne Adresse und Zugangsmarke. Schicken Sie darum bei jeder Änderung alle Angaben mit. Antwortet mit 200 und dem Werkzeug unter tool, bei unbekannter Kennung mit 404 not_found.

Anmeldung
Angemeldet, Rolle Bearbeiten oder höher
Begrenzung
30 je Minute und angemeldeter Person, gemeinsam mit anderen Änderungen an Assistenten

DELETE /api/v1/tools/{id}

Löscht ein Werkzeug und antwortet mit deleted: true. Bereits ausgelöste Vorgänge bleiben bestehen.

Anmeldung
Angemeldet, Rolle Bearbeiten oder höher

POST /api/v1/conversations/{conversation}/tool/{call}/confirm

Bestätigt einen offenen Vorschlag aus der App heraus. Die Antwort enthält den Aufruf unter call und duplicate, das anzeigt, ob der Vorschlag schon entschieden war. In einem Gespräch des Kanals Widget antwortet der Dienst mit 409 visitor_decides; dort entscheidet der Besucher. Der bestätigte Aufruf trägt unter approval_path den Wert operator_confirmed; bestätigt der Besucher im Chatfenster, steht dort visitor_confirmed.

Anmeldung
Angemeldet, Rolle Bearbeiten oder höher

POST /api/v1/conversations/{conversation}/tool/{call}/reject

Lehnt einen offenen Vorschlag aus der App heraus ab. Antwort wie beim Bestätigen. In einem Gespräch des Kanals Widget antwortet der Dienst mit 409 visitor_decides; dort entscheidet der Besucher.

Anmeldung
Angemeldet, Rolle Bearbeiten oder höher

Die Wege, auf denen der Besucher im Chatfenster bestätigt oder ablehnt, beschreibt Gespräch im Widget. Weitere Wege zu Gesprächen stehen unter Gespräche und Verwaltung über die Schnittstelle.

Häufige Fragen

Warum kann ich die Freigabe nicht umstellen?

Bei schreibenden und unumkehrbaren Bauformen steht die Freigabe fest auf mit Bestätigung. Wählbar ist sie nur bei lesenden Bauformen.

Warum sind Adresse und Zugangsmarke gesperrt?

Diese Felder ändert, wer die Rolle Verwaltung oder Inhaber hat. Mit der Rolle Bearbeiten lassen sich die übrigen Angaben ändern, ein Werkzeug für ein angebundenes System aber nicht neu anlegen.

Was passiert mit Vorgängen, wenn ich ein Werkzeug lösche?

Bereits ausgelöste Vorgänge bleiben bestehen. Ein noch offener Vorschlag des Werkzeugs lässt sich danach nicht mehr ausführen. Wollen Sie ein Werkzeug nur pausieren, nehmen Sie stattdessen den Haken bei Aktiv heraus.

Was tun, wenn mein System langsam antwortet?

Nach 8 Sekunden endet der Aufruf als Zeitgrenze überschritten und wird nicht wiederholt. Über die Schnittstelle lässt sich die Frist mit deadline_s auf bis zu 20 Sekunden setzen; ein späteres Speichern im Formular setzt sie auf 8 Sekunden zurück. Besser ist eine Antwort, die sofort bestätigt und die Arbeit danach erledigt.

Warum bietet der Assistent ein Werkzeug im Chatfenster nicht an?

Prüfen Sie, ob das Werkzeug aktiv ist, ob seine Mindestrolle auf Besucher (öffentlicher Chat) steht und ob die Bauform zu Ihrem Paket gehört. Nur dann bekommt der Assistent es im Chatfenster angeboten.

Warum kam zu einer Übergabe keine Mail?

Prüfen Sie zuerst, ob am Assistenten eine Adresse für die Übergabe hinterlegt ist. Ohne sie liegt die Übergabe nur im Postfach und unter Anfragen. Bestätigt der Besucher dieselbe Übergabe im selben Gespräch ein zweites Mal, geht ebenfalls keine zweite Mail hinaus.

Eine Stelle ist unklar geblieben?

Schreiben Sie uns, welche Seite und welcher Schritt gemeint ist. Wir antworten persönlich.

Anfrage in drei Schritten

  1. 1. Anliegen
  2. 2. Ihr Fall
  3. 3. Kontakt

Worum geht es?

Ein Klick genügt, alles Weitere ist freiwillig.

Erzählen Sie kurz von Ihrem Fall

Alle Angaben in diesem Schritt sind freiwillig. Sie helfen uns, gleich mit etwas Konkretem zu antworten statt mit Rückfragen.

Anfragen im Monat, ungefähr (optional)
Wann soll es losgehen? (optional)
Wie erreichen wir Sie?

Name und E-Mail-Adresse genügen. Wir antworten persönlich.

Wir verwenden Ihre Angaben, um Ihre Anfrage zu bearbeiten. Mehr dazu in der Datenschutzerklärung.