Conversation Control
The Conversation Handler
The
ConversationHandler is a key part of the Touchpoint UI SDK, providing the primary interface for your application to interact with the NLX backend. It allows you to send messages, start flows, manage conversation context, and subscribe to conversation events.
Refer to the Headless API Reference (ConversationHandler interface) for a complete list of methods and their detailed type signatures.
Accessing the ConversationHandler
You can access the
ConversationHandler in two main ways:
From the Touchpoint Instance
When you initialize Touchpoint UI using the
create method, it returns a TouchpointInstance object. This object contains the conversationHandler.
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 touchpointOptions = { 11 config: { 12 applicationUrl: "YOUR_APPLICATION_URL", 13 headers: { "nlx-api-key": "YOUR_API_KEY" }, 14 languageCode: "en-US", 15 // userId is required for voice input, recommended otherwise 16 userId: crypto.randomUUID(), 17 }, 18 // Other Touchpoint UI options 19 }; 20 21 const touchpoint = await create(touchpointOptions); 22 const conversationHandler = touchpoint.conversationHandler; 23 // Now you can use conversationHandler methods 24 // Make it globally accessible for other script tags or inline event handlers 25 window.myAppGlobalConversationHandler = conversationHandler; 26 27 </script> 28 </body> 29</html>
From Custom Modality Components
When building Custom Modality Components, the
conversationHandler is passed as a prop to your component, allowing seamless interaction with the ongoing conversation.
Component example
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 MyCustomButtonComponent = ({ data, conversationHandler }) => { 11 const myButton = html`18`; 19 return myButton; 20 }; 21 22 </script> 23 </body> 24</html>
To use this component, you would register it in the
customModalities option when creating the Touchpoint instance.
Sending Messages and Data
The
ConversationHandler provides several methods to send information to your NLX application. Most of these methods allow an optional context object as the second argument, enabling you to pass context variables to NLX to use in your flows.
💡 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.
sendText(text, context?)
Use
sendText to send a free-form text message from the user. This is typically used when your NLX flow expects a textual response, such as capturing a name, email, or any other information for a slot that accepts open-ended input.
When to use:
- Responding to an open-ended question from the bot.
- Filling a slot that expects arbitrary text input.
1// Assuming 'conversationHandler' is obtained 2conversationHandler.sendText("Yes, I'd like to know more about your services."); 3 4// Sending text with context 5conversationHandler.sendText("My email is user@example.com", { 6 pageSection: "pricingInquiry", 7 timestamp: new Date().toISOString(), 8});
sendFlow(flowId, context?)
Use
sendFlow to programmatically trigger a specific flow within your NLX application. This is useful for starting the conversation at a particular point or guiding it based on user actions outside the chat interface (e.g., clicking a "Track Order" button on your website).
When to use:
- Starting a conversation with a specific purpose (e.g., "CheckOrderStatus").
- Responding to user interactions on your webpage that map to a defined flow.
- Allowing custom components to direct the conversation flow.
1// Assuming 'conversationHandler' is obtained 2conversationHandler.sendFlow("RequestTechnicalSupport"); 3 4// Sending an flow with context variables 5conversationHandler.sendFlow("ViewProductDetails", { 6 productId: "PROD12345", 7 category: "electronics", 8});
sendWelcomeFlow(context?)
Use
sendWelcomeFlow to initiate the conversation with the default welcome flow configured in your NLX application. This is automatically called by Touchpoint UI by default when the chat opens (unless initializeConversation is overridden), but you can call it manually to restart or refresh the conversation. You can also pass context variables to personalize the welcome experience.
When to use:
- Starting the conversation when Touchpoint is first opened.
- Providing a "start over" functionality.
- Sending initial context data (like user status or page information) at the beginning of a conversation.
1// Assuming 'conversationHandler' is obtained 2 3// Simple welcome flow 4conversationHandler.sendWelcomeFlow(); 5 6// Welcome flow with initial context 7conversationHandler.sendWelcomeFlow({ 8 userLoggedIn: true, 9 entryPoint: "ProductPageWelcome", 10 languagePreference: "es-MX", 11});
Refer to the Launching with Context guide for more on customizing initial interactions.
sendChoice(choiceId, context?)
Use
sendChoice when the user selects an option from a list of choices presented by the NLX application. These choices might appear as quick replies, buttons in a card, or items in a carousel. The choiceId must match one of the choiceIds provided by the bot in a previous message.
When to use:
- User clicks a quick reply button.
- User selects an item from a carousel or list that has an associated
choiceId. - Responding to a user-choice node that expects a 'label' or 'id' response.
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 MyCustomButtonComponent = ({ data, conversationHandler }) => { 11 const myButton = html`17`; 18 return myButton; 19 }; 20 21 </script> 22 </body> 23</html>
sendSlots(slots, context?)
Use
sendSlots to send a collection of slot values to NLX. This is highly useful for providing multiple pieces of information at once, such as filling a form.
Provide an object where keys are the slot names (as defined in your NLX Application's "Attached Slots" section for an Flow, or as slot collector node names) and values are the data for those slots.
When to use:
- Submitting data from a form within a custom component or your webpage.
- Providing multiple pieces of information gathered through a custom UI.
1// Assuming 'conversationHandler' is obtained 2// Slot names ('FirstName', 'ProductInterest') must match those in your NLX configuration. 3conversationHandler.sendSlots({ 4 FirstName: "Alex", 5 LastName: "Rivera", 6 ProductInterest: "Solar Panels", 7}); 8 9// Sending slots with context 10conversationHandler.sendSlots( 11 { EmailAddress: "alex.rivera@email.com", ZipCode: "90210" }, 12 { formName: "leadCaptureForm" }, 13);
sendStructured(request, context?)
sendStructured is used for sending a combination of an flow, choice, and/or slots in a single request. This is useful for more complex interactions where multiple pieces of data need to be conveyed simultaneously.
Refer to the Headless API Reference (StructuredRequest type) for details on the
request object structure.
1// Assuming 'conversationHandler' is obtained 2conversationHandler.sendStructured( 3 { 4 flowId: "FinalizeOrderFlow", // Trigger a specific flow 5 slots: { 6 // Provide slot data 7 PaymentMethod: "CreditCard", 8 ShippingPreference: "Express", 9 }, 10 // choiceId: "confirm_action" // Optionally, also send a choiceId 11 }, 12 { currentCartValue: 150.75 }, // Send along some context 13);