Web

This page documents the @nlxai/touchpoint-ui package, serving as the guide for the Touchpoint SDK for web applications.

A native web SDK that provides a customizable chat and voice interface that you can embed in your web applications. Touchpoint allows users to interact with your NLX applications through natural language and provides a seamless conversational experience.

Installation

NPM

For modern JavaScript frameworks (React, Vue, Angular, etc.):

Bash

npm install @nlxai/touchpoint-ui

CDN (Script Tag)

For static HTML pages or legacy applications:

Script Tag in HTML header

<script defer src="https://unpkg.com/@nlxai/touchpoint-ui/lib/index.umd.js"></script>

Full HTML example

<html lang="en">
  <head>
    <title>Touchpoint Example</title>
    <meta name="viewport" content="width=device-width, initial-scale=1">
  </head>
  <body>
    <script type="module">
      import { create, React, html } from "https://unpkg.com/@nlxai/[email protected]/lib/index.js?module";
      
      const touchpoint = await create({
        config: {
          applicationUrl: "REPLACE_WITH_APPLICATION_URL",
          headers: {
            "nlx-api-key": "REPLACE_WITH_API_KEY"
          },
          languageCode: "en-US",
          userId: "REPLACE_WITH_USER_ID",  // optional, auto-generated otherwise
        },
        colorMode: "light",
        input: "voice",
        theme: {
          fontFamily: "'Neue Haas Grotesk', sans-serif",
          accent:"#0040FF"
        },
      });
    </script>
  </body>
</html>

API Methods

create(options)

The primary entry point. Initializes the Touchpoint widget and mounts it to the DOM.

Returns: Promise<TouchpointInstance>

import { create } from "@nlxai/touchpoint-ui";

const touchpoint = await create({
  config: {
    applicationUrl: "REPLACE_WITH_APPLICATION_URL",
    headers: {
      "nlx-api-key": "REPLACE_WITH_API_KEY",
    },
    languageCode: "en-US",
    userId: "REPLACE_WITH_USER_ID", // optional, auto-generated otherwise
  },
  colorMode: "light",
  input: "voice",
  theme: {
    fontFamily: "'Neue Haas Grotesk', sans-serif",
    accent:"#0040FF"
  },
});

expanded

Available on TouchpointInstance You can expand and collapse the experience by calling setting the this field to true or false:

// Expand
touchpointInstance.expanded = true;
// Collapse
touchpointInstance.expanded = false;

teardown()

Available on TouchpointInstance Removes the Touchpoint widget from the DOM and cleans up event listeners.

Configuration

The create method accepts a configuration object with the following properties:

Core Configuration (config)

Parameters strictly related to the connection with the NLX bot.

Property

Type

Required

Description

applicationUrl

string

Yes

The endpoint URL of your NLX application.

headers

object

Yes

HTTP headers, typically containing {"nlx-api-key": "..."}.

languageCode

string

Yes

The IETF language tag (e.g., en-US, es-MX).

userId

string

No

A unique identifier for the user to maintain state across sessions.

conversationId

string

No

ID of an existing conversation to resume.

UI Options

Top-level properties that control the look and feel of the widget.

Property

Type

Default

Description

theme

Theme

{}

Custom colors, fonts, and border radii (see Theming below).

chatMode

boolean

false

If true, enables Classic Chat (persistent history). If false, uses Assistant Mode (ephemeral, focused UI).

input

'text' | 'voice' | 'voiceMini'

'voice'

The primary input mode. voiceMini renders a minimal microphone button only.

colorMode

'light' | 'dark'

'light'

Sets the base color scheme.

windowSize

'half' | 'full'

'half'

'full' forces the chat to occupy the entire viewport (useful for mobile web apps).

launchIcon

string (URL)

undefined

Custom URL for the floating launcher button icon.

brandIcon

string (URL)

undefined

Custom URL for the logo displayed in the chat header.

userMessageBubble

boolean

false

If true, wraps user messages in a colored bubble.

agentMessageBubble

boolean

false

If true, wraps agent messages in a colored bubble.

Theming

The theme object allows for granular customization of the visual system.

Type definition:

export interface Theme {
  fontFamily?: string;        // Main font family
  accent?: string;            // Accent color for primary buttons and other accent elements
  innerBorderRadius?: string; // Border radius for inner elements e.g. input fields
  outerBorderRadius?: string; // Border radius for outer elements like chat window containers and launch icons
}

Modality Components

Touchpoint supports rendering custom React components based on "modalities" defined in your NLX flow.

Usage:

Pass a modalityComponents object to the create function mapping modality names to components.

const modalityComponents = {
  // "FlightCard" matches the modality name in the NLX flow
  FlightCard: ({ data, conversationHandler }) => {
    return (
      <div className="flight-card">
        <h3>{data.flightNumber}</h3>
        <button onClick={() => conversationHandler.sendText("Book this flight")}>
          Book Now
        </button>
      </div>
    );
  }
};

await create({
  config: {
    applicationUrl: "REPLACE_WITH_APPLICATION_URL",
    headers: {
      "nlx-api-key": "REPLACE_WITH_API_KEY",
    },
    languageCode: "en-US"
  },
  input: "voiceMini",
  modalityComponents,
});

Conversation Handler API

The conversationHandler is passed to custom components and is also returned by the create instance. It is used to drive the conversation programmatically.

Method

Parameters

Description

sendText

(text: string, context?: object)

Sends a standard text message to the bot as if the user typed it.

sendChoice

(choiceId: string, context?: object)

Sends a structured choice selection (response to a button click).

sendFlow

(flowId: string, context?: object)

Triggers a specific flow ID directly, bypassing NLU flow matching.

sendWelcomeFlow

(context: object)

Triggers the welcome flow directly, bypassing NLU flow matching.

sendStructured

(request: object)

Sends a raw structured payload to the bot engine.

sendContext

(context: object)

Voice+ only: Pushes context updates to the active phone call (e.g., updating current page URL).

Voice+ Integration

When using Voice+ (synchronizing a phone call with the web UI), specific configurations apply.

Digital Drives Voice:

Use conversationHandler.sendContext({ currentUrl: window.location.href }) to update the voice application on the user's location.

Voice Drives Digital:

The SDK automatically listens for payloads from the voice channel. To handle these, ensure your customModalities are registered to catch the specific data types the voice application sends (e.g., ShowForm, PlaceOrder, etc).

Last updated