@shivamprasad99/chatbot-sdk

A reusable React floating chatbot widget for BuyerXP. This package is fully isolated, styled with Tailwind CSS v4, and buildable for production.

Installation

This package is designed as a standalone module. Install React peer dependencies in the host project:

npm install react react-dom @shivamprasad99/chatbot-sdk

Usage

On Any Website with a Script Tag

For static sites, CMS pages, WordPress/Webflow custom code blocks, or any site where you can edit HTML, use the embeddable browser bundle:

<script
  src="https://sttrustpulse043760696395.blob.core.windows.net/chatbot-embed/chatbot.js"
  data-platform-id="YOUR_PLATFORM_ID"
  defer
></script>

Local development example after running npm run build:

<script
  src="./dist/chatbot-widget.js"
  data-platform-id="demo-platform"
  data-title="BuyerXP Assistant"
  data-subtitle="Ask me anything"
  async
></script>

Supported data-* attributes include:

| Attribute | Description | |---|---| | data-platform-id | Required platform/customer identifier. | | data-session-endpoint | Optional session API endpoint. Uses the production default if omitted. | | data-title | Header title. | | data-subtitle | Header subtitle. | | data-bot-name | Assistant display name. | | data-greeting | Optional initial assistant greeting. | | data-empty-state-title | Empty chat title. | | data-empty-state-description | Empty chat description. | | data-auto-open | true/false; opens the widget on load when true. | | data-fullscreen | true/false; fullscreen mode when true. Usually false for embeds. | | data-collect-email-at-start | true/false; requires email before chat when true. | | data-lead-endpoint-base | Optional lead capture base endpoint. | | data-metadata | Optional JSON object string passed as metadata. | | data-lead-consent | Optional JSON object string for lead consent overrides. | | data-storage-key | Optional browser session storage key. | | data-debug-latency | true/false; enables latency logs when true. | | data-auto-init | true/false; set false to load the script without automatic mount. |

Boolean attributes support true, false, 1, 0, yes, no, on, and off.

Script Embed Security

The script embed uses platform ID only. The platform ID is public and is not a secret.

Production security must be enforced by the backend by checking the browser Origin header against the allowed origins configured for that platform ID. See docs/platform-id-security-model.md.

The embed bundle requires data-platform-id before mounting and includes non-authoritative origin/page metadata for backend logging and debugging.

JavaScript API

The embed bundle exposes window.BuyerXPChatbot:

<script src="./dist/chatbot-widget.js" data-auto-init="false"></script>
<script>
  window.BuyerXPChatbot.init({
    platformId: 'demo-platform',
    title: 'BuyerXP Assistant',
    subtitle: 'Ask me anything'
  });
</script>

Available methods:

BuyerXPChatbot.init(config);    // mount/re-mount the widget
BuyerXPChatbot.update(config);  // re-render with merged config
BuyerXPChatbot.destroy();       // unmount and remove the root node
BuyerXPChatbot.getConfig();     // read the active config
BuyerXPChatbot.version;         // SDK version

In a React Application

Import the chatbot widget and its styles in your application:

import React from 'react';
import { ChatbotWidget } from '@shivamprasad99/chatbot-sdk';
import '@shivamprasad99/chatbot-sdk/style.css';

export default function App() {
  return (
    <ChatbotWidget
      enabled={true}
      siteId="buyerxp"
      sessionEndpoint="https://api.yourvoiceplatform.com/api/voice/session"
      title="BuyerXP Bot"
      subtitle="Hi, I'm BuyerXP Bot - your guide to BuyerXP"
      greeting="Hi there! I'm your BuyerXP assistant. How can I help you today?"
      storageKey="buyerxp_landing_chatbot_v1"
      metadata={{ source: 'my-app' }}
    />
  );
}

Lead Email Capture (In-Chat)

<ChatbotWidget
  enabled={true}
  siteId="buyerxp"
  sessionEndpoint="https://api.yourvoiceplatform.com/api/voice/session"
  collectEmailAtStart={true}
/>

When enabled, the widget first shows an email input card inside the chat window, then calls:

• POST /api/voice/session/{voice_session_id}/lead

Payload shape used by the SDK:

{
  "details": {
    "work_email": "[email protected]"
  },
  "consent": {
    "contact_consent": true,
    "consent_text_version": "v1"
  }
}

After a successful save, normal text/voice chat flow continues unchanged.

Props Reference

| Prop Name | Type | Description | |---|---|---| | enabled | boolean | Enables/disables the chatbot widget. | | sessionEndpoint | string | The API endpoint to initiate the voice/text session. | | siteId | string | Site identifier for the voice platform. | | storageKey | string | The browser sessionStorage key for persisting chat history. | | title | string | Chat window title. | | subtitle | string | Chat window subtitle/description. | | greeting | string | Optional initial assistant greeting message. If omitted or blank, no greeting is inserted. | | emptyStateTitle | string | Header text when there are no messages. | | emptyStateDescription| string | Sub-text when there are no messages. | | metadata | object | Custom metadata object passed to the backend. | | autoOpen | boolean | Control widget open/closed state programmatically. | | enableCampaignAutoOpen| boolean | Enables opening the chat via URL params (bot=open, utm_source=email). | | createVoiceClient | function | Optional override for creating the voice transport client. By default, the SDK uses its bundled web voice client. | | sanitizeHtml | function | Optional custom HTML sanitizer for markdown output. | | collectEmailAtStart | boolean | If true, chat and voice controls stay locked until the user submits an email in-chat. | | leadEndpointBase | string | Optional base endpoint for lead upsert. Defaults to sessionEndpoint. The SDK posts to {base}/{voice_session_id}/lead. | | leadConsent | object | Optional consent/details overrides for lead upsert. Supports contact_consent, marketing_opt_in, consent_text_version, and linkedin_url. |

Development and Building

To build the library locally for distribution:

1. Install dependencies:

   npm install

2. Build the output formats (ESM, UMD, and CSS):

   npm run build

This generates the dist/ directory containing:

• chatbot-sdk.js - ES module build for npm/React consumers.
• chatbot-sdk.umd.cjs - CommonJS/UMD build for npm/React consumers.
• chatbot-widget.js - self-contained browser embed bundle for script-tag installs.
• style.css - Standalone compiled Tailwind v4 CSS for package consumers.

Deploying the Blob-Hosted Embed

The embed deployment does not publish to npm. It uploads the built bundle to an isolated public Azure Blob container, promotes it to the stable chatbot.js path, and verifies the public bundle hash.

Sign in with Azure CLI and configure the storage account name:

az login
export AZURE_STORAGE_ACCOUNT="YOUR_STORAGE_ACCOUNT"

The script constructs the storage account's public Blob container URL. Set CHATBOT_PUBLIC_BASE_URL only when overriding the standard Blob container URL.

To reuse the existing TrustPulse Azure configuration without copying its connection string, point the deployment at that environment file:

export AZURE_EMBED_ENV_FILE="$HOME/Desktop/projects/trustpulse/scripts/azure_artifacts.env"
npm run deploy:embed:azure

The script maps TrustPulse's storage variables automatically and creates a separate public chatbot-embed container if it does not exist.

The version in package.json is also the embed release version. Validate a release locally without changing Azure:

npm run deploy:embed:azure -- --dry-run

Deploy the release:

npm run deploy:embed:azure

Each deployment creates an immutable release at releases/<version>/chatbot-widget.js and then promotes the same bytes to chatbot.js. Existing client integrations continue using the stable URL.

The same workflow is available through the Makefile:

make embed-dry-run
make embed-release VERSION=0.2.2

embed-release changes the local package version and deploys that version. It does not publish anything to npm.