atoms-widget-core
Version:
Atoms Widget SDK for React applications
211 lines (172 loc) • 7.38 kB
Markdown
# Atoms Widget SDK
A React-based widget SDK for seamlessly integrating Atoms AI chat and voice functionality into web applications. Built with TypeScript and modern React patterns for enterprise-grade reliability.
## Features
### Core Capabilities
- **Real-time Chat**: Full-featured chat implementation with typing indicators and message history
- **Voice Calling**: Complete voice conversation support
- **Dual Integration**: React component for modern frameworks and HTML custom element for vanilla projects
- **TypeScript First**: Full type safety with comprehensive IntelliSense support
- **Responsive Design**: Adaptive UI that works across all device sizes
### Customization
- **Flexible Positioning**: 4 position options (bottom-right, bottom-left, top-right, top-left)
- **Size Variants**: Tiny, compact, and full-size layouts
- **Color Theming**: Complete color customization for branding consistency
- **Consent Management**: Built-in privacy consent flow with customizable content
## Installation
### React/Next.js Projects
```bash
npm install atoms-widget-core
```
```jsx
import { AtomsWidget } from "atoms-widget-core";
function App() {
return (
<AtomsWidget
assistantId="your-assistant-id"
mode="chat"
position="bottom-right"
size="full"
accentColor="#2d9d9f"
title="AI Assistant"
chatPlaceholder="How can I help you today?"
/>
);
}
```
### HTML/Vanilla JavaScript
```html
<!DOCTYPE html>
<html>
<head>
<script src="https://unpkg.com/atoms-widget-core@latest/dist/embed/widget.umd.js"></script>
</head>
<body>
<atoms-widget
assistant-id="your-assistant-id"
mode="chat"
position="bottom-right"
size="full"
accent-color="#2d9d9f"
base-color="#ffffff"
cta-button-color="#000000"
cta-button-text-color="#ffffff"
title="AI Assistant"
chat-placeholder="How can I help you today?"
></atoms-widget>
</body>
</html>
```
## ⚙️ Configuration
### Required Properties
| Property | Type | Description |
| ------------- | -------- | ----------------------- |
| `assistantId` | `string` | Your Atoms assistant ID |
### Layout & Positioning
| Property | Type | Default | Description |
| -------------- | --------------------------------------------------------------------------------- | ---------------- | ----------------------- |
| `mode` | `"chat" \| "voice"` | `"chat"` | Interaction mode |
| `position` | `"bottom-right" \| "bottom-left" \| "top-right" \| "top-left"` | `"bottom-right"` | Widget position |
| `size` | `"tiny" \| "compact" \| "full"` | `"full"` | Widget size |
| `borderRadius` | `number` | `16` | Border radius in pixels |
### Color Customization
| Property | Type | Default | Description |
| -------------------- | -------- | ----------- | -------------------------------- |
| `baseColor` | `string` | `"#ffffff"` | Background color |
| `accentColor` | `string` | `"#2d9d9f"` | Primary accent color |
| `ctaButtonColor` | `string` | `"#000000"` | CTA button background |
| `ctaButtonTextColor` | `string` | `"#ffffff"` | CTA button text color |
| `agentBubbleColor` | `string` | `"#F3F4F6"` | Agent message bubble color |
| `textOnAccentColor` | `string` | `"#ffffff"` | Text color on accent backgrounds |
| `secondaryTextColor` | `string` | `"#6B7280"` | Secondary text color |
| `primaryTextColor` | `string` | `"#111827"` | Primary text color |
### Text & Labels
| Property | Type | Default | Description |
| ----------------- | -------- | ------------------------ | ----------------------- |
| `title` | `string` | `"Talk with AI"` | Widget title |
| `ctaName` | `string` | `"Chat with us"` | CTA button text |
| `startButtonText` | `string` | `"Start"` | Voice start button text |
| `endButtonText` | `string` | `"End Call"` | Voice end button text |
| `chatPlaceholder` | `string` | `"Type your message..."` | Chat input placeholder |
| `avatarUrl` | `string` | `""` | Avatar image URL |
### Empty State Messages
| Property | Type | Description |
| ------------------------- | -------- | -------------------------------------- |
| `voiceEmptyMessage` | `string` | Message shown when voice is inactive |
| `voiceActiveEmptyMessage` | `string` | Message shown during active voice call |
| `chatEmptyMessage` | `string` | Message shown in empty chat |
| `hybridEmptyMessage` | `string` | Message shown in hybrid mode |
### Consent Management
| Property | Type | Default | Description |
| ------------------- | --------- | --------------------- | ---------------------------- |
| `consentRequired` | `boolean` | `false` | Require privacy consent |
| `consentTitle` | `string` | `"Privacy Agreement"` | Consent dialog title |
| `consentContent` | `string` | Default privacy text | Consent dialog content |`"consent-accepted"` | localStorage key for consent |
## Usage Examples
### Customer Support Chat
```jsx
import { AtomsWidget } from "atoms-widget-core";
export default function SupportWidget() {
return (
<AtomsWidget
assistantId="support-assistant-123"
mode="chat"
position="bottom-right"
size="full"
accentColor="#3B82F6"
baseColor="#ffffff"
title="Customer Support"
ctaName="Need Help?"
chatPlaceholder="Describe your issue..."
consentRequired={true}
consentTitle="Privacy Notice"
consentContent="We collect conversation data to improve our service."
/>
);
}
```
### Voice-Only Assistant
```jsx
import { AtomsWidget } from "atoms-widget-core";
export default function VoiceAssistant() {
return (
<AtomsWidget
assistantId="voice-assistant-456"
mode="voice"
position="bottom-center"
size="tiny"
accentColor="#10B981"
title="Voice Assistant"
ctaName="Start Voice Chat"
/>
);
}
```
### HTML Integration with Custom Styling
```html
<!DOCTYPE html>
<html>
<head>
<script src="https://unpkg.com/atoms-widget-sdk/dist/embed/widget.umd.js"></script>
<style>
atoms-widget {
--atoms-accent-color: #8b5cf6;
--atoms-base-color: #f8fafc;
}
</style>
</head>
<body>
<atoms-widget
assistant-id="your-assistant-id"
mode="chat"
position="bottom-left"
size="compact"
accent-color="#8B5CF6"
base-color="#F8FAFC"
title="AI Helper"
chat-placeholder="Ask me anything..."
consent-required="true"
></atoms-widget>
</body>
</html>
```
Built with ❤️ by the Atoms team