Developers

Journey manager

Getting started

The @nlxai/journey-manager package is used to manage multimodal journeys without writing dedicated frontend code.

In contrast to the conventional multimodal setup, where developers would use the barebones multimodal API to attach explicit event handling code to clicks and page loads, the journey manager works by pre-annotating your visual asset's interactive elements using the Dialog Studio desktop application.

Once you are ready, download a single code snippet and included on your page. Your asset is now enhanced with multimodal capabilities.

Setup

Add this code to the head of your document, including templates for the custom behaviors of your choice:

1<html>
2  <head>
3    <script defer src="https://unpkg.com/@nlxai/journey-manager/lib/index.umd.js"></script>
4    <script>
5      // Get conversation ID from the URL, assuming it is included as a 'cid' search param (and save in session storage)
6      // On subsequent page loads, retrieve from session storage assuming it was saved in the past half an hour
7      const getCid = () => {
8        const localStorageKey = "nlx-multimodal-session";
9        const saveToSessionStorage = (conversationId) => {
10          sessionStorage.setItem(localStorageKey, JSON.stringify({
11            conversationId,
12            timestamp: new Date().getTime()
13          }));
14        };
15        const retrieveFromSessionStorage = () => {
16          try {
17            const val = sessionStorage.getItem(localStorageKey);
18            if (!val) {
19              return null;
20            }
21            const parsed = JSON.parse(val);
22            if (parsed != null && typeof parsed == "object" && new Date().getTime() - parsed.timestamp < 30 * 60 * 1000) {
23              return parsed.conversationId;
24            }
25          } catch(_err) {
26            return null;
27          }
28        }
29        const params = new URLSearchParams(window.location.search);
30        const cidFromParams = params.get("cid");
31        if (cidFromParams) {
32          saveToSessionStorage(cidFromParams);
33          return cidFromParams;
34        }
35        return retrieveFromSessionStorage();
36      };
37
38      const triggers = {};
39
40      window.addEventListener("DOMContentLoaded", () => {
41        nlxai.journeyManager.run({
42          config: {
43            // hard-coded params
44            apiKey: "REPLACE_WITH_API_KEY",
45            workspaceId: "REPLACE_WITH_WORKSPACE_ID",
46            journeyId: "REPLACE_WITH_JOURNEY_ID",
47            // dynamic params
48            conversationId: getCid(),
49            languageCode: "REPLACE_WITH_LANGUAGE_CODE",
50          },
51          // Triggers object obtained from the journey step configuration
52          triggers: {},
53          // Send a custom step if a digression is detected
54          onDigression: (client) => {
55            client.sendStep("REPLACE_WITH_STEP_ID");
56          }
57        });
58      });
59    </script>
60  </head>
61  <body>
62  </body>
63</html>
64

The nlxai.journeyManager.run method takes an object argument with the following fields:

  • config: a journey configuration identical to that of the regular multimodal API.
  • triggers: an object containing triggers that map step ID's to specific interactions or events such as page loads or clicks.
  • onDigression: a callback used to handle digression, with the multimodal client as an argument in case you are sending steps as a response.
Next
Journey manager: Query engine