TouchStage Chat SDK

A customizable chat widget for providing interactive in-app tours and user guidance. Works with any web application without React dependencies.

Installation

npm install touchstage-client

Quick Start

// ES Modules
import { initChatWidget } from "touchstage-client";

// CommonJS
const { initChatWidget } = require("touchstage-client");

// Initialize the widget
await initChatWidget({
  apiKey: "YOUR_API_KEY",
  productId: "YOUR_PRODUCT_ID",
  userId: "USER_ID",
  userEmail: "[email protected]", // Optional
  userName: "User Name", // Optional
  userRole: ["admin"], // Optional
  userPlan: "premium", // Optional
  userTenantId: "tenant-123", // Optional
  baseUrl: "https://api.yourcompany.com", // Optional - Custom API base URL
  isDarkMode: false, // Optional
  showChatButton: true, // Optional - controls chat button visibility
  initialVisible: false, // Optional - widget starts visible if true
  additionalData: {}, // Optional additional user data
});

Manual Integration via Script Tag

<!-- Add the JS -->
<script src="https://unpkg.com/touchstage-client/dist/chat-widget.umd.js"></script>

<script>
  window.initChatWidget({
    apiKey: "YOUR_API_KEY",
    productId: "YOUR_PRODUCT_ID",
    userId: "USER_ID",
    userEmail: "[email protected]", // Optional
    userName: "User Name", // Optional
    userRole: ["admin"], // Optional
    userPlan: "premium", // Optional
    userTenantId: "tenant-123", // Optional
    baseUrl: "https://api.yourcompany.com", // Optional - Custom API base URL
    isDarkMode: false, // Optional
    showChatButton: true, // Optional
    initialVisible: false, // Optional
  });
</script>

Framework Integration Examples

Vue.js

<template>
  <div>
    <button @click="openChat">Open Chat</button>
  </div>
</template>

<script>
import {
  initChatWidget,
  openChatWidget,
  destroyChatWidget,
} from "touchstage-client";

export default {
  async mounted() {
    // Initialize widget when component mounts
    await initChatWidget({
      apiKey: "your-api-key",
      productId: "your-product-id",
      userId: this.$store.state.user.id,
      userEmail: this.$store.state.user.email,
      isDarkMode: this.$store.state.theme === "dark",
    });
  },
  methods: {
    async openChat() {
      await openChatWidget();
    },
  },
  async beforeUnmount() {
    // Clean up when component unmounts
    await destroyChatWidget();
  },
};
</script>

Angular

import { Component, OnInit, OnDestroy } from "@angular/core";
import {
  initChatWidget,
  openChatWidget,
  destroyChatWidget,
} from "touchstage-client";

@Component({
  selector: "app-root",
  template: '<button (click)="openChat()">Open Chat</button>',
})
export class AppComponent implements OnInit, OnDestroy {
  async ngOnInit() {
    // Initialize widget
    await initChatWidget({
      apiKey: "your-api-key",
      productId: "your-product-id",
      userId: "user-123",
      userEmail: "[email protected]",
    });
  }

  async openChat() {
    await openChatWidget();
  }

  async ngOnDestroy() {
    // Clean up
    await destroyChatWidget();
  }
}

Svelte

<script>
  import { onMount, onDestroy } from 'svelte';
  import { initChatWidget, openChatWidget, destroyChatWidget } from "touchstage-client";

  onMount(async () => {
    // Initialize widget
    await initChatWidget({
      apiKey: 'your-api-key',
      productId: 'your-product-id',
      userId: 'user-123',
      userEmail: '[email protected]'
    });
  });

  async function openChat() {
    await openChatWidget();
  }

  onDestroy(async () => {
    // Clean up
    await destroyChatWidget();
  });
</script>

<button on:click={openChat}>Open Chat</button>

React

import { useEffect } from "react";
import {
  initChatWidget,
  openChatWidget,
  destroyChatWidget,
} from "touchstage-client";

function App() {
  useEffect(() => {
    // Initialize widget
    initChatWidget({
      apiKey: "your-api-key",
      productId: "your-product-id",
      userId: "user-123",
      userEmail: "[email protected]",
    });

    // Cleanup on unmount
    return () => {
      destroyChatWidget();
    };
  }, []);

  const openChat = async () => {
    await openChatWidget();
  };

  return (
    <div>
      <button onClick={openChat}>Open Chat</button>
    </div>
  );
}

Configuration Options

| Parameter | Type | Required | Description | | -------------- | ------------------- | -------- | ------------------------------------------ | | apiKey | string | Yes | Your TouchStage API key | | productId | string | Yes | Your product ID from TouchStage dashboard | | userId | string | Yes | Unique identifier for the current user | | userEmail | string | No | User's email address | | userName | string | No | User's display name | | userRole | string[] | No | Array of user roles | | userPlan | string | No | User's subscription plan | | userTenantId | string | No | User's tenant/organization ID | | baseUrl | string | No | Your product api base url | | isDarkMode | boolean | No | Enable dark mode (default: false) | | showChatButton | boolean | No | Show/hide chat button (default: true) | | initialVisible | boolean | No | Start with widget visible (default: false) | | additionalData | Record<string, any> | No | Any additional user data |

API Reference

initChatWidget(config): Promise<void>

Initializes the chat widget with the provided configuration. Performs API health check and sets up the widget.

Parameters:

• config (InitConfig): Configuration object with required and optional properties

Returns: Promise that resolves when widget is successfully initialized

Throws: Error if API health check fails or required parameters are missing

setUserData(userData, widgetOptions?): void

Updates user data after initialization.

Parameters:

• userData (InitConfig): Updated user configuration
• widgetOptions (WidgetOptions, optional): Widget display options

openChatWidget(): Promise<boolean>

Opens/shows the chat widget.

Returns: Promise - true when widget is opened

closeChatWidget(): Promise<boolean>

Closes/hides the chat widget.

Returns: Promise - false when widget is closed

toggleChatWidget(): Promise<boolean>

Toggles the chat widget visibility.

Returns: Promise - new visibility state

isChatWidgetVisible(): Promise<boolean>

Checks if the chat widget is currently visible.

Returns: Promise - current visibility state

setBaseUrl(baseUrl): Promise<void>

Updates the API base URL.

Parameters:

• baseUrl (string): New API base URL

Returns: Promise

destroyChatWidget(): Promise<void>

Destroys the chat widget and cleans up resources.

Returns: Promise

Advanced Usage

Dynamic User Data Updates

// Using ES module import
import { setUserData } from "touchstage-client";

setUserData({
  apiKey: "your-api-key",
  productId: "your-product-id",
  userId: "new-user-id",
  userEmail: "[email protected]",
  userRole: ["admin", "user"],
});

// Or using window object (for script tag loading)
window.setUserData({
  apiKey: "your-api-key",
  productId: "your-product-id",
  userId: "new-user-id",
  userEmail: "[email protected]",
  userRole: ["admin", "user"],
});

Theme Management

// Initialize with dark mode
await initChatWidget({
  // ... other config
  isDarkMode: true,
});

Custom Base URL

// Use custom API endpoint
await initChatWidget({
  // ... other config
  baseUrl: "https://your-custom-api.com",
});

Integration Methods

Method 1: ES Module Import (Recommended for Frameworks)

import { initChatWidget, openChatWidget, closeChatWidget } from "touchstage-client";

await initChatWidget({...});
await openChatWidget();

Method 2: Script Tag (CDN Loading)

<script src="https://unpkg.com/touchstage-client/dist/chat-widget.umd.js"></script>
<script>
  window.initChatWidget({...});
  window.openChatWidget();
</script>

Error Handling

The widget includes built-in error handling and will throw errors for:

• Missing required configuration parameters (apiKey, productId, userId)
• API health check failures
• Network connectivity issues

Always wrap initialization in a try-catch block for production use:

try {
  await initChatWidget({
    apiKey: "YOUR_API_KEY",
    productId: "YOUR_PRODUCT_ID",
    userId: "USER_ID",
  });
  console.log("Widget initialized successfully");
} catch (error) {
  console.error("Failed to initialize widget:", error);
}

Browser Support

The widget supports all modern browsers:

• Chrome 60+
• Firefox 60+
• Safari 12+
• Edge 79+

Troubleshooting

Common Issues

1. Widget not appearing: Check console for initialization errors
2. API errors: Verify API key and product ID
3. Styling conflicts: The widget uses CSS-in-JS to avoid conflicts

Debug Mode

Enable debug logging:

// Set debug mode in localStorage
localStorage.setItem("touchstage_debug", "true");

Support

For issues and questions:

• GitHub Issues: [TouchStage Repository]
• Documentation: [TouchStage Docs]
• Email: [email protected]

Copyright

© TouchStage. All rights reserved.