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. Außerdem gibt es die Möglichkeit, das Widget programmatisch zu initialisieren. Dies kann z.B. auf komplexen Javascript-basierten Seiten nötig sein oder um während des Betriebs den Kanal zu wechseln.

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
    }]);
  });
});

Programmatische Initialisierung

Das Widget-Javascript stellt das globale Mercury-Objekt bereit, das für die Initialisierung über die Methode initChatWidget verfügt.

Um die automatische Initialisierung des Widgets zu vermeiden und es selber programmatisch zu initialisieren, muß zunächst anstelle des Scripts, das das Widget automatisch startet (https://cdn.mercury.ai/widget/v4/main.js) das Skript ohne Automatik geladen werden (https://cdn.mercury.ai/widget/v4/widget-main.js).

Zum Initialisieren des Widget müssen zunächst ein div erzeugt sowie ein Config- und ein User-Objekt angelegt werden. Mit diesen als Parametern wird dann o.g. Methode aufgerufen:

// create a div element into which the widget will be mounted
const el = document.createElement("div");
el.id = "mercury-widget";
document.body.appendChild(el);


// set up config object
const mercuryConfig = {
  apiKey: <data-key from your channel’s page>,
};


// set up user object
const mercuryUser = {
  userId: <some user id you provide>,
  // you may as well omit the userId, then the widget will generate a random id and save it in a cookie
};


// initialise the widget
window.Mercury.initChatWidget(el, mercuryConfig, mercuryUser);

Will man ein automatisch gestartetes Widget (d.h. eingebunden über https://cdn.mercury.ai/widget/v4/main.js) neu initialisieren, z.B. um einen anderen Kanal zu nutzen, unterscheidet sich das Vorgehen geringfügig: Die globalen Objekte mercuryConfig und mercuryUser wurden dann bereits angelegt und können ggf. angepaßt und erneut verwendet werden. Ebenso existiert bereits das Container-Element und kann über die ID mercury-widget gefunden werden. Hier ein Beispiel, um auf Button-Klick den Kanal zu wechseln:

  <!-- your button: -->
  <button id="channel-change-button">change channel</button>


  <!-- load and initialise your widget the regular way: -->
  <script type="application/javascript" src="https://cdn.mercury.ai/widget/v4/widget.js" id="mercury-widget-snippet" data-key="<your first channel’s key>"></script>


  <!-- set up a click handler that re-initalises the widget with the second channel key: -->
  <script type="application/javascript">
    const button = document.getElementById('channel-change-button');
    button.addEventListener('click', (e) => {
      const el = document.getElementById('mercury-widget');
      window.mercuryConfig.apiKey = <your second channel’s key>;
      window.Mercury.initChatWidget(el, mercuryConfig, mercuryUser);
    });
  </script>