BlockSpark Chat Widget

A universal JavaScript chat widget library that connects directly with Dialogflow CX - no backend API required!

Supports: React, Next.js, Vue.js, Nuxt 3, Vite, and Vanilla JavaScript

Installation

Option 1: Install from Local Path (Recommended for Development)

# In your website project directory
npm install /path/to/blockspark-chat-widget
# or
npm install ../blockspark-chat-widget

Option 2: Use npm link (For Development)

# In the blockspark-chat-widget directory
npm link

# In your website project directory
npm link @blockspark/chat-widget

Option 3: Publish to npm (For Production)

# Build the library first
npm run build

# Publish to npm (make sure you're logged in)
npm publish

Then install in your project:

npm install @blockspark/chat-widget

Usage

Vue.js 3

<template>
  <ChatWidget
    df-project-id="your-project-id"
    df-agent-id="your-agent-id"
    :service-account-key="serviceAccountKey"
    backendBaseUrl="https://chartconnect.blockspark.in"
    backendWsUrl="wss://chartconnect.blockspark.in"
  />
</template>

<script setup>
import ChatWidget from '@blockspark/chat-widget/vue';
// ⚠️ REQUIRED: Import CSS separately
import '@blockspark/chat-widget/styles';
import serviceAccountKey from './credentials/dialogflow.json';
</script>

CSS Import Options:

• import '@blockspark/chat-widget/styles' (recommended)
• import '@blockspark/chat-widget/dist/styles.css' (alternative)

Nuxt 3 / Vue.js 3 (Important: Use ClientOnly!)

<template>
  <ClientOnly>
    <ChatWidget
      df-project-id="your-project-id"
      df-agent-id="your-agent-id"
      :service-account-key="serviceAccountKey"
    />
  </ClientOnly>
</template>

<script setup>
import ChatWidget from '@blockspark/chat-widget/nuxt';
import '@blockspark/chat-widget/styles';
import serviceAccountKey from './credentials/dialogflow.json';
</script>

In nuxt.config.ts:

export default defineNuxtConfig({
  css: ['@blockspark/chat-widget/dist/styles.css'],
  
  vite: {
    optimizeDeps: {
      exclude: ['@blockspark/chat-widget'],
    },
  },
});

⚠️ CRITICAL for Nuxt: The component MUST be wrapped in <ClientOnly> because it uses browser-only APIs (localStorage, window, WebSocket) that don't exist during SSR.

CSS Import Options:

• import '@blockspark/chat-widget/styles' (recommended - shorter path)
• import '@blockspark/chat-widget/dist/styles.css' (alternative)

React/Next.js

import ChatWidget from '@blockspark/chat-widget';
import '@blockspark/chat-widget/dist/styles.css';
import serviceAccountKey from './service-account-key.json';

function App() {
  return (
    <ChatWidget
      dfProjectId="your-project-id"
      dfLocation="us-central1"
      dfAgentId="your-agent-id"
      serviceAccountKey={serviceAccountKey}
      languageCode="en"
    />
  );
}

Props

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | dfProjectId | string | Yes | - | Dialogflow project ID | | dfLocation | string | No | "us-central1" | Dialogflow location | | dfAgentId | string | Yes | - | Dialogflow agent ID | | serviceAccountKey | object | Yes* | - | Google Cloud service account key JSON object | | accessToken | string | Yes* | - | Access token (alternative to serviceAccountKey) | | languageCode | string | No | "en" | Language code for Dialogflow | | title | string | No | "💬 BlockSpark AI Assistant" | Chat widget title | | subtitle | string | No | "We're here to help" | Chat widget subtitle | | welcomeTitle | string | No | "👋 Welcome to Blockspark" | Welcome popup title | | welcomeMessage | string | No | "My name is BlockSpark..." | Welcome popup message | | welcomeCta | string | No | "💬 Click here to start chatting!" | Welcome popup CTA text | | showWelcomePopup | boolean | No | true | Whether to show welcome popup | | welcomePopupDelay | number | No | 1500 | Delay before showing welcome popup (ms) | | fallbackWelcomeMessage | string | No | "Hello! I'm BlockSpark..." | Fallback message if API fails | | inputPlaceholder | string | No | "Type your message..." | Input field placeholder | | emptyStateMessage | string | No | "Hi! I'm BlockSpark..." | Empty state message | | debug | boolean | No | false | Enable debug logging | | backendBaseUrl | string | No | "http://localhost:8012" | Backend REST API base URL for Human Support Mode | | backendWsUrl | string | No | "ws://localhost:8012" | Backend WebSocket URL for Human Support Mode |

* Either serviceAccountKey or accessToken must be provided.

Features

• ✅ Direct Dialogflow CX Integration - No backend required
• ✅ Human Handoff Support - Automatic transition from bot to human agents
• ✅ Rich Content - Supports Dialogflow chips, cards, and more
• ✅ Real-time Messaging - WebSocket support for human agents
• ✅ SSR Compatible - Works with Next.js and Nuxt 3 (with ClientOnly wrapper)
• ✅ Framework Agnostic - Same UI across React and Vue
• ✅ TypeScript Support - Full type definitions included
• ✅ Tree-shakeable - Only import what you need

How It Works

The widget connects directly to Dialogflow CX using the REST API - no backend required!

1. Authentication: Uses Google Cloud service account key to generate OAuth2 access tokens
2. Session Management: Creates and manages Dialogflow sessions automatically
3. Message Handling: Sends messages directly to Dialogflow and displays responses
4. Rich Content: Supports Dialogflow rich content (chips, cards, etc.)
5. Human Handoff: Automatically switches to human support mode when Dialogflow returns handoff signal

Requirements

For React/Next.js

• React 16.8.0 or higher (peer dependency)
• React DOM 16.8.0 or higher (peer dependency)

For Vue.js/Nuxt

• Vue 3.0.0 or higher (peer dependency)

Note: Peer dependencies are optional - install only what you need for your framework.

Getting Your Service Account Key

1. Go to Google Cloud Console
2. Select your project
3. Navigate to IAM & Admin > Service Accounts
4. Create a new service account or select an existing one
5. Create a JSON key and download it
6. Enable Dialogflow API for your project
7. Grant the service account Dialogflow API User role

Security Warning ⚠️

Important: Service account keys contain sensitive credentials.

• For Development: You can import the key directly (as shown in examples)
• For Production:
  • DO NOT expose service account keys in client-side code
  • Use a backend proxy to handle authentication
  • Or use OAuth2 flow to get access tokens securely
  • Consider using restricted service account keys with minimal permissions

Development

# Install dependencies
npm install

# Build for production
npm run build

# Watch mode for development
npm run dev

Troubleshooting

Vue.js/Nuxt Issues

Widget not displaying?

• ✅ Make sure you imported the CSS: import '@blockspark/chat-widget/styles'
• ✅ For Nuxt: Wrap in <ClientOnly> component
• ✅ For Nuxt: Add CSS to nuxt.config.ts and exclude from optimization

Vue warnings about attributes?

• ✅ This is fixed in the latest version
• ✅ Ensure you're using the latest package version

Nuxt vite-node errors?

• ✅ Wrap component in <ClientOnly>
• ✅ Add to nuxt.config.ts:

  vite: {
    optimizeDeps: {
      exclude: ['@blockspark/chat-widget'],
    },
  }

• ✅ Clear cache: rm -rf .nuxt node_modules/.vite

504 Outdated Optimize Dep error?

• ✅ Clear Vite cache: rm -rf node_modules/.vite && npm run dev
• ✅ Or add to vite.config.ts:

  optimizeDeps: {
    exclude: ['@blockspark/chat-widget'],
  }

General Issues

Chat not opening?

• ✅ Check CSS is imported
• ✅ Verify Dialogflow config is provided
• ✅ Enable debug mode: :debug="true" or debug={true} to see console logs

Dialogflow errors?

• ✅ Verify service account key is valid
• ✅ Check Dialogflow API is enabled
• ✅ Ensure service account has Dialogflow API User role
• ✅ Verify project ID, location, and agent ID are correct

License

MIT