QA Bot Core

A simple React chatbot component for Q&A applications with built-in rating system.

Pre-configured wrapper around react-chatbotify - Just provide your API endpoints and you're done.

Installation

npm install @snf/qa-bot-core

Usage

React Component

Basic Usage

Just provide required props:

import QABot from '@snf/qa-bot-core';

function App() {
  return (
    <QABot
      apiKey="your-api-key"
      qaEndpoint="https://your-api.com/chat"
      welcomeMessage="Hello! How can I help you today?"
      isLoggedIn={true}
    />
  );
}

Full Configuration

Customize appearance and behavior:

<QABot
  apiKey="your-api-key"
  qaEndpoint="https://your-api.com/chat"
  ratingEndpoint="https://your-api.com/rating"
  welcomeMessage="Hello! How can I help you today?"

  // Authentication (required)
  isLoggedIn={true}
  allowAnonAccess={false}
  actingUser="[email protected]"
  loginUrl="/login"

  // Window control
  open={false}
  onOpenChange={(isOpen) => console.log('Chat is now', isOpen ? 'open' : 'closed')}

  // Branding
  primaryColor="#24292e"
  secondaryColor="#586069"
  botName="Demo Assistant"
  logo="https://github.com/github.png"

  // Messages
  placeholder="Type your message here..."
  errorMessage="Sorry, something went wrong"
  tooltipText="Ask me anything!"

  // Layout
  embedded={false}

  // Footer
  footerText="Powered by Demo Corp"
  footerLink="https://demo.com"
/>

JavaScript API

import { qaBot } from '@snf/qa-bot-core';

const bot = qaBot({
  target: document.getElementById('bot-container'),
  apiKey: 'your-api-key',
  qaEndpoint: 'https://your-api.com/chat',
  ratingEndpoint: 'https://your-api.com/rating',
  welcomeMessage: "Hello! How can I help you today?",
  isLoggedIn: true,
  primaryColor: '#24292e',
  secondaryColor: '#586069',
  botName: 'Demo Assistant',
  logo: 'https://github.com/github.png'
});

// Programmatic control
bot.openChat();
bot.closeChat();
bot.addMessage('Hello from code!');
bot.destroy();

Standalone Bundle

<div id="bot-container"></div>
<script src="https://unpkg.com/@snf/qa-bot-core/dist/qa-bot-core.standalone.js"></script>
<script>
  window.qaBotCore({
    target: document.getElementById('bot-container'),
    apiKey: 'your-api-key',
    qaEndpoint: 'https://your-api.com/chat',
    ratingEndpoint: 'https://your-api.com/rating',
    welcomeMessage: "Hello! How can I help you today?",
    isLoggedIn: true,
    primaryColor: '#24292e',
    secondaryColor: '#586069',
    botName: 'Demo Assistant',
    logo: 'https://github.com/github.png'
  });
</script>

Configuration

Props

| Prop | Type | Required | Description | |------|------|----------|-------------| | apiKey | string | ✅ | API key for your Q&A service | | qaEndpoint | string | ✅ | Q&A API endpoint URL | | welcomeMessage | string | ✅ | Initial greeting message | | isLoggedIn | boolean | ✅ | Whether the user is logged in. Controls header icon and Q&A access gating | | ratingEndpoint | string | ❌ | Rating API endpoint URL (enables thumbs up/down) | | allowAnonAccess | boolean | ❌ | Allow Q&A access even when not logged in (default: false) | | actingUser | string | ❌ | Acting user identifier sent to backend as X-Acting-User header and acting_user body field | | loginUrl | string | ❌ | Login URL for the login button when not logged in (default: /login) | | open | boolean | ❌ | Control chat window open/closed state | | onOpenChange | function | ❌ | Callback when chat window state changes: (open: boolean) => void | | primaryColor | string | ❌ | Main theme color (default: #1a5b6e) | | secondaryColor | string | ❌ | Secondary theme color (default: #107180) | | botName | string | ❌ | Bot display name (default: Q&A Bot) | | logo | string | ❌ | Bot avatar URL (default: /chat-icon.svg) | | placeholder | string | ❌ | Input placeholder text | | errorMessage | string | ❌ | Error state message | | tooltipText | string | ❌ | Tooltip text for chat toggle | | embedded | boolean | ❌ | Embedded mode (default: false) | | footerText | string | ❌ | Footer text | | footerLink | string | ❌ | Footer link URL | | customFlow | Flow | ❌ | Custom flow steps to merge with built-in Q&A flow (see Custom Flows section) | | onAnalyticsEvent | function | ❌ | Analytics callback: (event: QABotAnalyticsEvent) => void |

Features

Login State Management

The bot manages authentication state through the isLoggedIn prop:

• Logged in (isLoggedIn={true}): Shows user icon in header, Q&A is fully accessible
• Not logged in (isLoggedIn={false}): Shows login button in header, Q&A is gated (prompts to log in)

Example:

const [userLoggedIn, setUserLoggedIn] = useState(false);

<QABot
  apiKey="your-api-key"
  qaEndpoint="https://your-api.com/chat"
  welcomeMessage="Hello! How can I help you today?"
  isLoggedIn={userLoggedIn}
  loginUrl="https://your-app.com/login"
/>

When the user is not logged in (isLoggedIn={false}):

• The login button appears in the chat header
• Clicking it opens the loginUrl in a new tab
• Q&A flow is gated and prompts users to log in

When the user is logged in (isLoggedIn={true}):

• A user icon appears in the chat header
• Users can ask questions normally

Anonymous Access

If you want to allow Q&A access without requiring login, use the allowAnonAccess prop:

<QABot
  apiKey="your-api-key"
  qaEndpoint="https://your-api.com/chat"
  welcomeMessage="Hello! How can I help you today?"
  isLoggedIn={false}
  allowAnonAccess={true}
/>

This bypasses the login gate for Q&A while still showing the login button in the header. Note that custom flows (if any) are unaffected by this setting.

Chat Window Control

Control the chat window open/closed state programmatically:

const [chatOpen, setChatOpen] = useState(false);

<QABot
  apiKey="your-api-key"
  qaEndpoint="https://your-api.com/chat"
  welcomeMessage="Hello! How can I help you today?"
  isLoggedIn={true}
  open={chatOpen}
  onOpenChange={setChatOpen}
/>

<button onClick={() => setChatOpen(true)}>Open Chat</button>
<button onClick={() => setChatOpen(false)}>Close Chat</button>

The open prop provides two-way binding:

• Setting open={true} opens the chat window
• Setting open={false} closes the chat window
• User interactions (clicking open/close buttons) trigger onOpenChange

Imperative API

You can also control the bot imperatively using a ref:

const botRef = useRef();

<QABot
  ref={botRef}
  apiKey="your-api-key"
  qaEndpoint="https://your-api.com/chat"
  welcomeMessage="Hello! How can I help you today?"
  isLoggedIn={true}
/>

// Available methods:
botRef.current.openChat();           // Open the chat window
botRef.current.closeChat();          // Close the chat window
botRef.current.toggleChat();         // Toggle chat window state
botRef.current.addMessage("Hello!"); // Inject a message into the chat
botRef.current.setBotEnabled(false); // Change enabled state

Embedded Mode

The bot supports two display modes:

Floating Mode (default):

• Shows as a toggle button in the bottom-right corner
• Chat window can be opened/closed by clicking the button
• Overlays on top of page content

Embedded Mode:

• Displays inline within your page layout
• Always visible (no toggle button)
• Takes full width of its container
• Chat window cannot be closed

Example of embedded mode:

<div style={{ maxWidth: '800px', margin: '0 auto' }}>
  <h1>Customer Support</h1>
  <QABot
    apiKey="your-api-key"
    qaEndpoint="https://your-api.com/chat"
    welcomeMessage="Hello! How can I help you today?"
    isLoggedIn={true}
    embedded={true}
  />
</div>

Note: When embedded={true}, the open and onOpenChange props are ignored, and the imperative methods openChat(), closeChat(), and toggleChat() have no effect.

Custom Flows

You can extend the bot with custom flow steps using the customFlow prop. This allows you to add ticket creation, feedback forms, or other interactive workflows that merge with the built-in Q&A flow.

import QABot from '@snf/qa-bot-core';

const myCustomFlow = {
  submit_ticket: {
    message: "I'll help you submit a ticket. What's the issue?",
    path: "ticket_details"
  },
  ticket_details: {
    message: "Thanks! Your ticket has been submitted.",
    path: "start"
  }
};

<QABot
  apiKey="your-api-key"
  qaEndpoint="https://your-api.com/chat"
  welcomeMessage="Hello! How can I help you today?"
  isLoggedIn={true}
  customFlow={myCustomFlow}
/>

Custom flows are merged into the flow object, so your custom steps can reference built-in steps and vice versa.

Flow Settings Utility

When building custom flows, you may encounter a react-chatbotify quirk where chatDisabled state persists across step transitions. The applyFlowSettings utility helps manage this:

import { applyFlowSettings } from '@snf/qa-bot-core';

const myFlow = {
  choose_option: {
    message: "Select an option:",
    options: ["Option A", "Option B"],
    path: "next_step"
  },
  next_step: {
    message: "You selected an option!",
    path: "start"
  }
};

// Auto-disable chat input on steps with options/checkboxes
const processedFlow = applyFlowSettings(myFlow, {
  disableOnOptions: true
});

<QABot
  // ...other props
  customFlow={processedFlow}
/>

The disableOnOptions: true setting automatically sets chatDisabled: true for steps that have options or checkboxes, and chatDisabled: false for steps without them (unless you've explicitly set chatDisabled yourself).

History Tracking for Custom Flows

When building custom flows, you may want certain important messages to be saved in session history so they can be restored when a user revisits a previous session. By default, messages defined with the message: property in flow steps may not be tracked in history.

Use the withHistory and withHistoryFn helpers to ensure messages are tracked:

import { withHistory, withHistoryFn } from '@snf/qa-bot-core';

const myFlow = {
  // Static message - use withHistory()
  ask_email: {
    message: withHistory("Please enter your email address:"),
    path: "next_step"
  },

  // Dynamic message - use withHistoryFn()
  show_summary: {
    message: withHistoryFn(() => {
      const data = getFormData();
      return `Summary:\nName: ${data.name}\nEmail: ${data.email}`;
    }),
    options: ["Submit", "Cancel"],
    path: "submit"
  },

  // Success message with important data (e.g., ticket links)
  success: {
    message: withHistoryFn(() => generateSuccessMessage(result)),
    options: ["Back to Menu"],
    path: "start"
  }
};

When to use these helpers:

• withHistory(string) - For static messages you want restored in history
• withHistoryFn(fn) - For dynamic/computed messages (summaries, API responses with links)

Tip: You don't need to wrap every message - only the important ones that would be valuable when restoring a session (like ticket confirmations, summaries, or API responses).

Session Management

The bot automatically manages conversation sessions with unique session IDs:

• Each bot instance generates a unique session ID when mounted
• The session ID is included in API request headers (X-Session-ID)
• A "New Chat" button in the footer allows users to start fresh conversations
• Clicking "New Chat" generates a new session ID and clears the conversation history
• This allows your backend to track conversation continuity and user journeys

Session Headers Sent to API:

X-Session-ID: qa_bot_session_abc123
X-Query-ID: query_xyz789

The session ID persists across page refreshes, but clicking "New Chat" creates a completely new session. This is useful for:

• Starting a new topic without the bot referencing previous context
• Resetting conversation state
• Allowing users to have multiple distinct conversations

Analytics Events

The bot fires analytics events via an optional callback prop, allowing you to wire up GTM, GA4, or any analytics provider without adding dependencies to the library.

<QABot
  apiKey="your-api-key"
  qaEndpoint="https://your-api.com/chat"
  welcomeMessage="Hello! How can I help you today?"
  isLoggedIn={true}
  onAnalyticsEvent={(event) => {
    // Push to GTM dataLayer
    window.dataLayer?.push({
      event: event.type,
      ...event
    });
  }}
/>

Event Types:

| Event | When Fired | Key Fields | |-------|------------|------------| | chatbot_open | Chat window opened | sessionId | | chatbot_close | Chat window closed | sessionId, messageCount, durationMs | | chatbot_new_chat | User clicks "New Chat" | sessionId, previousMessageCount | | chatbot_question_sent | User submits question | sessionId, queryId, questionLength | | chatbot_answer_received | API returns response | sessionId, queryId, responseTimeMs, responseLength, hasMetadata | | chatbot_answer_error | API call fails | sessionId, queryId, errorType | | chatbot_rating_sent | User rates response | sessionId, queryId, rating | | chatbot_login_prompt_shown | Login gate displayed | sessionId |

All events include type and timestamp. The sessionId is auto-injected when available.

TypeScript:

import type { QABotAnalyticsEvent, QABotAnalyticsEventType } from '@snf/qa-bot-core';

Debug Logging

The bot includes a lightweight logging utility that's disabled by default but can be enabled at runtime for troubleshooting. Logs are controlled via localStorage, making it easy to debug in any environment (including production) without rebuilding.

Enable debug logging:

localStorage.setItem('QA_BOT_DEBUG', 'true');

Disable debug logging (default):

localStorage.removeItem('QA_BOT_DEBUG');

When enabled, you'll see styled console output for:

• Library version on load
• Session lifecycle events (CREATED, RESET, RESTORED)
• History operations (message tracking, session restore)
• Message tracking (which messages are being saved to history)

Errors and warnings always display regardless of the debug flag.

API Requirements

Your Q&A endpoint should accept POST requests:

POST /your-qa-endpoint
Content-Type: application/json
X-API-KEY: your-api-key

{
  "query": "User's question here"
}

And return:

{
  "response": "Bot's answer with **markdown** support",
  "sessionId": "session_123",
  "queryId": "query_456"
}

Rating Endpoint (Optional)

For thumbs up/down feedback:

POST /your-rating-endpoint
Content-Type: application/json
X-API-KEY: your-api-key

{
  "sessionId": "session_123",
  "queryId": "query_456",
  "rating": 1  // 1 for 👍, 0 for 👎
}

Development

Demo Application

The project includes an interactive demo that showcases all features:

# Install dependencies
npm install

# Run demo app
npm start

The demo runs at http://localhost:3000 and includes:

Configuration Status

• Shows which environment variables are configured
• Displays API endpoints for verification

Dynamic Props

• Toggle isLoggedIn prop to simulate login/logout states
• Toggle open prop to control chat window state
• Toggle embedded prop to switch between floating and embedded modes

Component API

• Test the imperative addMessage() method
• Inject custom messages into the chat

Environment Variables

Create a .env file in the project root:

REACT_APP_API_KEY=your-api-key
REACT_APP_QA_ENDPOINT=https://your-api.com/chat
REACT_APP_RATING_ENDPOINT=https://your-api.com/rating  # optional

Building

# Build library
npm run build:lib

License

MIT License