assistly-chat
v1.0.7
Published
Assistly customer support chat widget for React, Next.js, and vanilla JavaScript apps
Maintainers
fadacoReadme
assistly-chat
Drop-in customer support chat widget for any JavaScript application. Works with React, Next.js, Vue, Angular, or plain HTML/JS.
Prerequisites
- Create a free account at https://assistly.cloud
- Once signed in, go to Setup & Integrations to find your Organization ID
- Use your Organization ID in the widget configuration below
Installation
npm install assistly-chat
# or
yarn add assistly-chat
# or
pnpm add assistly-chatQuick Start
React / Next.js
import { AssistlyWidget } from "assistly-chat/react";
function App() {
return (
<div>
<h1>My App</h1>
<AssistlyWidget organizationId="your-org-id" />
</div>
);
}Vanilla JavaScript
import { createWidget } from "assistly-chat";
const widget = createWidget({
organizationId: "your-org-id",
});Script Tag (CDN / No Bundler)
If you prefer not to use npm, you can use the hosted script tag instead:
<script
src="https://assistly.cloud/widget.js"
data-organization-id="your-org-id"
></script>User Identification
Pass user details to enable session persistence and allow users to see their past conversations:
React
import { AssistlyWidget } from "assistly-chat/react";
function App() {
const user = useAuth(); // your auth hook
return (
<AssistlyWidget
organizationId="your-org-id"
userEmail={user.email}
userName={user.name}
/>
);
}Vanilla JS
import { createWidget } from "assistly-chat";
const widget = createWidget({
organizationId: "your-org-id",
userEmail: "[email protected]",
userName: "Jane Doe",
});Script Tag
<script
src="https://assistly.cloud/widget.js"
data-organization-id="your-org-id"
data-user-email="[email protected]"
data-user-name="Jane Doe"
></script>When a user is identified:
- The auth/login screen is skipped automatically
- Their session persists across page reloads
- A "Past conversations" button appears so they can view previous chats
Configuration
| Prop / Option | Type | Default | Description |
| --- | --- | --- | --- |
| organizationId | string | (required) | Your Assistly organization ID |
| widgetUrl | string | https://widget.assistly.cloud | Custom widget URL (for self-hosted deployments) |
| position | "bottom-right" | "bottom-left" | "bottom-right" | Widget button position on screen |
| userEmail | string | undefined | Identified user's email |
| userName | string | undefined | Identified user's display name |
API Methods
The createWidget() function returns an API object for programmatic control:
Vanilla JS
import { createWidget } from "assistly-chat";
const widget = createWidget({ organizationId: "your-org-id" });
// Open the chat
widget.show();
// Close the chat
widget.hide();
// Remove the widget entirely
widget.destroy();
// Reinitialize with new config (e.g., after user logs in)
widget.init({
userEmail: "[email protected]",
userName: "Jane Doe",
});Global API
The widget is also available globally on window.AssistlyWidget:
// Works after the widget has been initialized
window.AssistlyWidget.show();
window.AssistlyWidget.hide();
window.AssistlyWidget.destroy();Framework Guides
Next.js App Router
Create a client component for the widget:
// components/widget-provider.tsx
"use client";
import { AssistlyWidget } from "assistly-chat/react";
export default function WidgetProvider() {
return <AssistlyWidget organizationId="your-org-id" />;
}Then add it to your root layout:
// app/layout.tsx
import WidgetProvider from "@/components/widget-provider";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html>
<body>
{children}
<WidgetProvider />
</body>
</html>
);
}Next.js Pages Router
// pages/_app.tsx
import { AssistlyWidget } from "assistly-chat/react";
export default function MyApp({ Component, pageProps }) {
return (
<>
<Component {...pageProps} />
<AssistlyWidget organizationId="your-org-id" />
</>
);
}Vue / Nuxt
Use the vanilla JS API inside a Vue component:
<script setup>
import { onMounted, onUnmounted } from "vue";
import { createWidget } from "assistly-chat";
let widget;
onMounted(() => {
widget = createWidget({
organizationId: "your-org-id",
});
});
onUnmounted(() => {
widget?.destroy();
});
</script>Angular
// app.component.ts
import { Component, OnInit, OnDestroy } from "@angular/core";
import { createWidget, AssistlyWidgetAPI } from "assistly-chat";
@Component({ selector: "app-root", template: "<router-outlet />" })
export class AppComponent implements OnInit, OnDestroy {
private widget: AssistlyWidgetAPI | null = null;
ngOnInit() {
this.widget = createWidget({
organizationId: "your-org-id",
});
}
ngOnDestroy() {
this.widget?.destroy();
}
}Plain HTML
<!DOCTYPE html>
<html>
<head>
<title>My Site</title>
</head>
<body>
<h1>Welcome</h1>
<script
src="https://assistly.cloud/widget.js"
data-organization-id="your-org-id"
></script>
</body>
</html>Self-Hosted
If you're self-hosting Assistly, point the widget to your own instance:
<AssistlyWidget
organizationId="your-org-id"
widgetUrl="https://widget.yourdomain.com"
/>Or in vanilla JS:
createWidget({
organizationId: "your-org-id",
widgetUrl: "https://widget.yourdomain.com",
});Features
- Auto-theming - Automatically picks up colors, button shape, size, and icon configured in your Assistly dashboard
- Proactive messages - Time-based, scroll-based, and URL-based proactive messages configured from the dashboard
- Voice support - Voice calling via Vapi integration (when configured)
- Away messages - Automatic offline messaging when agents are unavailable
- Unread badge - Shows unread message count on the widget button
- localStorage caching - Theme settings are cached for instant load on return visits
- Responsive - Adapts to mobile and desktop viewports
- Identified users - Pass user email/name to skip login and enable conversation history
TypeScript
Full TypeScript support is included. Types are exported from both entry points:
import type { AssistlyWidgetConfig, AssistlyWidgetAPI } from "assistly-chat";AssistlyWidgetConfig
interface AssistlyWidgetConfig {
organizationId: string;
widgetUrl?: string;
position?: "bottom-right" | "bottom-left";
userEmail?: string;
userName?: string;
}AssistlyWidgetAPI
interface AssistlyWidgetAPI {
show: () => void; // Open the chat widget
hide: () => void; // Close the chat widget
destroy: () => void; // Remove the widget from the DOM
init: (config: Partial<AssistlyWidgetConfig>) => void; // Reinitialize
}License
MIT