BlockSpark Chat Widget

A reusable React chat widget component that connects directly with Dialogflow CX - no backend API required!

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 Usage (Quick Start)

# Install
npm install @blockspark/chat-widget

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

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

📚 For detailed Vue.js setup guide, see VUE_INSTALLATION_GUIDE.md

React/Next.js Usage

Basic Usage

import ChatWidget from '@blockspark/chat-widget';
import '@blockspark/chat-widget/dist/styles.css';

// Load your Google Cloud service account key
import serviceAccountKey from './path/to/service-account-key.json';

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

Using Access Token (Alternative)

If you prefer to manage authentication yourself:

import ChatWidget from '@blockspark/chat-widget';
import '@blockspark/chat-widget/dist/styles.css';

function App() {
  const [accessToken, setAccessToken] = useState<string>('');

  // Get access token from your backend or OAuth flow
  useEffect(() => {
    // Your token fetching logic here
    fetchAccessToken().then(setAccessToken);
  }, []);

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

With Custom Configuration

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"
      title="💬 My Chat Assistant"
      subtitle="How can I help you?"
      welcomeTitle="👋 Welcome!"
      welcomeMessage="I'm here to help you with any questions."
      welcomeCta="Start chatting"
      showWelcomePopup={true}
      welcomePopupDelay={2000}
      inputPlaceholder="Type your message..."
      emptyStateMessage="Hi! How can I help you today?"
      debug={false}
    />
  );
}

Using Environment Variables

You can configure the backend API URLs for Human Support Mode using environment variables. Create a .env file in the project root:

# .env file
REACT_APP_BACKEND_BASE_URL=http://localhost:8012
REACT_APP_BACKEND_WS_URL=ws://localhost:8012

Or pass them as props:

<ChatWidget
  dfProjectId="your-project-id"
  dfAgentId="your-agent-id"
  serviceAccountKey={serviceAccountKey}
  backendBaseUrl="http://your-backend-url:8012"
  backendWsUrl="ws://your-backend-url:8012"
/>

Note: Props take precedence over environment variables.

Human Support Mode

The widget supports automatic handoff from bot to human agents. When Dialogflow returns {"handoff": true}, the widget will:

1. Switch from Bot Mode to Human Support Mode
2. Create a support chat session
3. Connect via WebSocket for real-time messaging
4. Load message history
5. Route messages to the backend API instead of Dialogflow

The widget displays mode indicators and connection status in the chat header.

Import Types (TypeScript)

import ChatWidget, { ChatWidgetProps, DialogflowConfig } from '@blockspark/chat-widget';

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 | process.env.REACT_APP_BACKEND_BASE_URL or "http://localhost:8012" | Backend REST API base URL for Human Support Mode | | backendWsUrl | string | No | process.env.REACT_APP_BACKEND_WS_URL or "ws://localhost:8012" | Backend WebSocket URL for Human Support Mode |

* Either serviceAccountKey or accessToken must be provided.

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.)

Requirements

• React 16.8.0 or higher
• React DOM 16.8.0 or higher
• Google Cloud service account with Dialogflow API enabled
• Dialogflow CX agent

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

License

MIT export NPM_TOKEN=your_token_here