Chat Widget SDK

Um eine engere Integration in die einbindende Webseite zu ermöglichen, sendet das Widget eine Reihe von Events und stellt verschiedene Methoden bereit. Damit können beispielsweise Eingaben in ein HTML-Formular und Eingaben im Chat synchronisiert werden.

Events

Die Events werden vom DOM-Element des Widgets (document.getElementById("mercury-widget")) emittiert mit den Optionen bubbles: true, cancelable: true. Es gibt folgende Event-Typen (event.type):

widget-ready: Wird gesendet, sobald das Widget geladen und bereit zur Interaktion ist. event.detail ist nicht gesetzt.

text-sent: Wird gesendet, wenn eine Textnachricht gesendet wurde. event.detail ist nicht gesetzt.

intent-sent: Wird gesendet, wenn ein Button-Klick gesendet wurde. event.detail ist nicht gesetzt.

messages-received: Wird gesendet, wenn eine oder mehrere Bot- oder Agenten-Nachrichten empfangen wurden. event.detail ist in diesem Fall:

{
  messages: [<message as JSON string>, ...]
}

message-added: Wird gesendet, sobald eine Bot- oder Agenten-Nachricht in der Nachrichtenliste angezeigt wird. event.detail ist in diesem Fall:

{
  message: <message as JSON string>
}

bot-event-received: Wird gesendet, wenn ein Event vom Bot empfangen wurde. Es gibt verschiedene Typen von Bot-Events mit folgendem event.detail:

{
  type: "BotIntent",
  intent: {
    key: "...",
    moduleKey: "..."
  }
}

{
  type: "UserIntent",
  intent: {
    key: "...",
    moduleKey: "..."
  }
}

{
  type: "ContextUpdate",
  update: {
    parameterKey: "...",
    value: "..."
  }
}

Beispiel

Nehmen wir an, wir wollen wie im eingangs erwähnten Beispiel Eingaben aus dem Chat in ein HTML-Formular übertragen. Dann könnten wir mit Hilfe des Bot-Events ContextUpdate folgendermaßen die Felder eines Adressformulars befüllen: (nehmen wir an, das Input-Feld für den Vornamen habe die ID “first-name“)

document.addEventListener("bot-event-received", (event) => {
  if (event.detail && event.detail.type === "ContextUpdate") {
    switch (event.detail.update.parameterKey) {
      case "user.firstName":
        document.getElementById('first-name').value = event.detail.update.value;
        break;
      //...
    }
  }
});

Methoden

Das DOM-Element des Widgets (document.getElementById("mercury-widget")) stellt folgende Methoden bereit:

sendUserIntent({key: "...", moduleKey: "..."}): Sendet einen User-Intent an den Bot.

triggerInitiative(parameterKey, value = null): Löst die Initiative für den gegebenen Kontextparameter aus. Wenn ein Wert angegeben wird, reagiert die Initiative mit dem "Confirm understood"-Hook, falls dieser aktiviert ist.

updateContext([{parameterKey: "...", operator: "...", value: "..."}, ...]): Aktualisiert den Kontext des Botnutzers. Als Operatoren sind verfügbar: "set", "delete", "add", "subtract", "invert" und "clear".

Alle Methoden geben eine Promise zurück, die mit der Response der API aufgelöst wird:

{
  data: <array of messages>,
  events: <array of bot events>
}

Zu beachten ist, dass alle Methoden erst verfügbar sind, wenn das Widget initialisiert ist. Dies kann mittels des o.g. Events widget-ready festgestellt werden.

Beispiel

Nehmen wir an, wir wollen wie im eingangs erwähnten Beispiel Eingaben aus einem HTML-Formular in den Kontext des Chats übertragen. Dann könnten wir mit Hilfe der Methode updateContext folgendermaßen den Kontext synchronisieren: (nehmen wir wieder an, das Input-Feld für den Vornamen habe die ID “first-name“)

const widget = document.getElementById("mercury-widget");
// wait for the widget to be ready
document.addEventListener("widget-ready", () => {
  // attach the event handler to our input field
  document.getElementById("first-name").addEventListener("change", (event) => {
    // send the context update
    widget.updateContext([{
      parameterKey: "user.firstName",
      operator: "set",
      value: event.target.value
    }]);
  });
});