Developer Docs

Conversation Control

Launching with Context

Touchpoint UI offers flexible ways to customize the conversation's launch. You can pass initial data to your NLX application using

initialContext or implement custom startup logic with the initializeConversation function.

Context Variables in NLX and Touchpoint

Context Variables within NLX and Touchpoint allow you pass 'context' about the user's interaction and state from Touchpoint to NLX.

💡 In order to use the context variables from Touchpoint in your flow, you need to define each variable as a Context Variable in your NLX workspace. If the context variable is not configured within NLX, the value will not be available in the Flow.

Passing Initial Data with initialContext

The

initialContext option in your Touchpoint UI configuration is the simplest way to send data to your NLX application when a conversation starts. initialContext works all input modes: text, voice, and voiceMini.

The

initialContext object accepts key-value pairs, which are then available as Context Variables within your NLX flows.

When to use

initialContext:

  • You need to pass user details, page information, or any other relevant data at the beginning of the conversation.
  • You don't need custom JavaScript logic to run on launch, just data passing.
  • You want a straightforward way to provide context for text, voice, or voiceMini interactions from the start.
1<html lang="en">
2  <head>
3    <title>Touchpoint Sample HTML</title>
4    <meta name="viewport" content="width=device-width, initial-scale=1">
5  </head>
6  <body>
7    <script type="module">
8      import { create, React, html } from "https://unpkg.com/@nlxai/touchpoint-ui@1.1.3/lib/index.js?module";
9      
10      const touchpoint = await create({
11        config: {
12          applicationUrl: "YOUR_APPLICATION_URL",
13          headers: { "nlx-api-key": "YOUR_API_KEY" },
14          languageCode: "en-US",
15          // userId is required if input is "voice" or "voiceMini"
16          userId: crypto.randomUUID(),
17        },
18        // userTier and current page must be defined as context variables in your NLX workspace
19        initialContext: {
20          userTier: "gold",
21          currentPage: "/products/item123",
22        },
23        // input: "text", // or "voice", "voiceMini"
24      });
25      
26    </script>
27  </body>
28</html>

If you also provide a custom

initializeConversation function (see below), the initialContext object will be passed as the second argument to that function.

Customizing Initialization Logic with initializeConversation

For more advanced scenarios where you need to execute custom JavaScript logic when the Touchpoint UI launches, you can use the

initializeConversation function.

💡

initializeConversation only works for text input mode. Your function is responsible for initiating the conversation (e.g., by calling handler.sendWelcomeFlow() or handler.sendFlow()).

When to use

initializeConversation:

  • You need to conditionally decide which flow to send based on application state.
  • You want to perform actions like logging, analytics tracking, or API calls before the first message is sent.
  • You need to implement custom setup logic for specific input modes.

Initialization Function Signature

The

initializeConversation function receives the ConversationHandler instance and any initialContext you provided in the configuration:

1type InitializeConversation = (
2  conversationHandler: ConversationHandler,
3  initialContext?: Record<string, any>, // Context from TouchpointConfiguration.initialContext
4) => void;

The

ConversationHandler provides methods like:

MethodDescription
sendWelcomeFlow(context?)Sends the default welcome Flow. The context argument here will merge with or override the initialContext passed to the function.
sendFlow(flowId, context?)Sends a specific Flow. The context argument here will merge with or override the initialContext passed to the function.

Examples

This example demonstrates passing

firstName and userTier. These need to be defined as Context Variables in your NLX Workspace to be usable in your flows. This approach works for text, voice, and voiceMini.

1<html lang="en">
2  <head>
3    <title>Touchpoint Sample HTML</title>
4    <meta name="viewport" content="width=device-width, initial-scale=1">
5  </head>
6  <body>
7    <script type="module">
8      import { create, React, html } from "https://unpkg.com/@nlxai/touchpoint-ui@1.1.3/lib/index.js?module";
9      
10      const touchpoint = await create({
11        config: {
12          applicationUrl: "YOUR_APPLICATION_URL",
13          headers: { "nlx-api-key": "YOUR_API_KEY" },
14          languageCode: "en-US",
15          userId: crypto.randomUUID(), // Required for voice
16        },
17        // userTier and firstName must be defined as context variables in your NLX workspace
18        initialContext: {
19          firstName: "David",
20          userTier: "premium",
21        },
22        // input: "text", // Or "voice", "voiceMini"
23      });
24      
25    </script>
26  </body>
27</html>

2. Launching with a Custom Flow Using initializeConversation

The specific flow (

CheckOrderStatus) must be defined in your NLX application. userSource, pageUrl, all must be defined as context variables in your NLX workspace.

1<html lang="en">
2  <head>
3    <title>Touchpoint Sample HTML</title>
4    <meta name="viewport" content="width=device-width, initial-scale=1">
5  </head>
6  <body>
7    <script type="module">
8      import { create, React, html } from "https://unpkg.com/@nlxai/touchpoint-ui@1.1.3/lib/index.js?module";
9      
10      const initializeWithCustomFlow = (conversationHandler) => {
11        // userSource and pageUrl must be defined as context variables in your NLX workspace
12        const context = {
13          userSource: "website",
14          pageUrl: window.location.href
15        }
16        // Send a specific Flow with the context
17        conversationHandler.sendFlow("CheckOrderStatus", context);
18      };
19      
20      const touchpoint = await create({
21        config: {
22          applicationUrl: "YOUR_APPLICATION_URL",
23          headers: { "nlx-api-key": "YOUR_API_KEY" },
24          languageCode: "en-US",
25        },
26        initializeConversation: initializeWithCustomFlow,
27        input: "text", // This custom function will run for any input mode
28      });
29      
30    </script>
31  </body>
32</html>
Next
Conversation Control: Subscribing to Events