Documentation & Help Center

Getting Started

Add the AISocialPilot chat widget to any website with a single script tag. Paste the following snippet before the closing </body> tag of your HTML:

<script src="https://cdn.aisocialpilot.ai/widget.js"
  data-widget-id="YOUR_WIDGET_ID"
  data-theme="light"
  data-position="bottom-right">
</script>

React / NPM Integration

If you use React (or any framework that supports npm packages), install the official package for a first-class integration:

npm install @aisocialpilot/chat-widget

Then import and render the component anywhere in your app:

import { ChatWidget } from '@aisocialpilot/chat-widget';

export default function App() {
  return (
    <ChatWidget
      widgetId="YOUR_WIDGET_ID"
      theme="light"
      position="bottom-right"
    />
  );
}

The React component accepts the same configuration options as the script tag (listed below), passed as props.

Configuration Reference

All options can be set as data-* attributes on the script tag (kebab-case) or as React component props (camelCase).

Customization

Theme Switching

The widget ships with both a light and dark theme. Set the theme via the data-theme attribute or theme prop:

<!-- Dark theme -->
<script src="https://cdn.aisocialpilot.ai/widget.js"
  data-widget-id="YOUR_WIDGET_ID"
  data-theme="dark">
</script>

Custom Brand Colors

Override the primary color to match your brand. The color affects the widget header, send button, links, and typing indicator.

<script src="https://cdn.aisocialpilot.ai/widget.js"
  data-widget-id="YOUR_WIDGET_ID"
  data-primary-color="#7c3aed">
</script>

Position

Choose between bottom-right (default) and bottom-left to place the widget launcher where it fits best in your layout.

CSS Isolation

All widget CSS classes use the asp- prefix (e.g. asp-chat-window, asp-message-bubble) to avoid conflicts with your existing stylesheets. The widget also renders inside Shadow DOM for complete style isolation.

Internationalization

The widget supports six languages out of the box. All UI strings — the send button label, input placeholder, timestamp formatting, and system messages — are fully translated.

Set the locale with the data-locale attribute or the locale prop:

<script src="https://cdn.aisocialpilot.ai/widget.js"
  data-widget-id="YOUR_WIDGET_ID"
  data-locale="es">
</script>

<ChatWidget widgetId="YOUR_WIDGET_ID" locale="fr" />

Pre-Chat Form

Collect your visitor's name and email before the conversation starts. The pre-chat form is shown only once per visitor session — the details are persisted in local storage.

Script Tag

<script src="https://cdn.aisocialpilot.ai/widget.js"
  data-widget-id="YOUR_WIDGET_ID"
  data-pre-chat-enabled="true"
  data-name-required="true"
  data-email-required="true"
  data-custom-greeting="Welcome! Tell us a bit about yourself.">
</script>

React Component

<ChatWidget
  widgetId="YOUR_WIDGET_ID"
  preChatEnabled={true}
  nameRequired={true}
  emailRequired={false}
  customGreeting="Welcome! Tell us a bit about yourself."
/>

Both nameRequired and emailRequired default to true when the pre-chat form is enabled. Set either to false to make the field optional (shown but not required).

Rich Messages

The widget supports several rich content types that are rendered automatically when the AI or a human agent sends structured payloads.

Quick Replies

Quick reply buttons are shown below an AI message and let the visitor respond with a single tap. They disappear after one is selected.

{
  "type": "quick_replies",
  "options": [
    { "label": "Pricing", "value": "Tell me about pricing" },
    { "label": "Features", "value": "What features do you offer?" },
    { "label": "Talk to human", "value": "Connect me to support" }
  ]
}

Cards

Cards display an image, title, description, and one or more action buttons. Use them for product highlights, articles, or feature spotlights.

{
  "type": "card",
  "title": "Pro Plan",
  "description": "Unlimited posts, 10 social accounts, priority support.",
  "imageUrl": "https://example.com/pro-plan.png",
  "buttons": [
    { "label": "Learn more", "url": "https://aisocialpilot.ai/pricing" },
    { "label": "Subscribe", "value": "subscribe_pro" }
  ]
}

Carousels

Carousels are horizontally scrollable collections of cards. The visitor can swipe through them on mobile or use arrow buttons on desktop.

{
  "type": "carousel",
  "cards": [
    {
      "title": "Starter",
      "description": "$29/mo",
      "buttons": [{ "label": "Choose", "value": "pick_starter" }]
    },
    {
      "title": "Pro",
      "description": "$79/mo",
      "buttons": [{ "label": "Choose", "value": "pick_pro" }]
    },
    {
      "title": "Business",
      "description": "$199/mo",
      "buttons": [{ "label": "Choose", "value": "pick_business" }]
    }
  ]
}

Buttons

Standalone button groups can link to external URLs or trigger in-chat actions. Buttons with a url property open in a new tab; buttons with a value property send the value as a visitor message.

Troubleshooting

script-src: cdn.aisocialpilot.ai
connect-src: cdn.aisocialpilot.ai your-project.supabase.co
style-src: cdn.aisocialpilot.ai