Developers

Script manager

Getting started

The @nlxai/voice-plus-web package is used to manage Voice+ scripts without writing dedicated frontend code.

In contrast to the conventional Voice+ setup, where developers would use the barebones Voice+ 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 Voice+ 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/voice-plus-web/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-voice-plus-web-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      const contentLoaded = () => {
41        if (document.readyState === "loading") {
42          return new Promise((resolve) => {
43            window.addEventListener("DOMContentLoaded", () => {
44              resolve();
45            });
46          });
47        } else {
48          return Promise.resolve();
49        }
50      };
51
52      contentLoaded().then(() => {
53        nlxai.voicePlusWeb.run({
54          config: {
55            // hard-coded params
56            apiKey: "REPLACE_WITH_API_KEY",
57            workspaceId: "REPLACE_WITH_WORKSPACE_ID",
58            scriptId: "REPLACE_WITH_SCRIPT_ID",
59            // dynamic params
60            conversationId: getCid(),
61            languageCode: "REPLACE_WITH_LANGUAGE_CODE",
62          },
63          // Triggers object obtained from the journey step configuration
64          triggers: {},
65          // Send a custom step if a digression is detected
66          onDigression: (client) => {
67            client.sendStep("REPLACE_WITH_STEP_ID");
68          }
69        });
70      });
71    </script>
72  </head>
73  <body>
74  </body>
75</html>
76

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

  • config: a script configuration identical to that of the regular Voice+ 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 Voice+ client as an argument in case you are sending steps as a response.
Next
Script manager: Query engine