Easy-to-use helpdesk widget SDK that loads via iframe
npm install @weldsuite/helpdesk-widget-sdkwidgetId - all styling and configuration is managed in your backoffice!
widgetId, that's it!
bash
npm install @weldsuite/helpdesk-widget-sdk
`
or
`bash
yarn add @weldsuite/helpdesk-widget-sdk
`
or
`bash
pnpm add @weldsuite/helpdesk-widget-sdk
`
Quick Start
$3
`javascript
import { initHelpdeskWidget } from '@weldsuite/helpdesk-widget';
initHelpdeskWidget({ widgetId: 'your-widget-id' });
`
That's it! 🎉
The widget will automatically:
- Load with your configured theme colors
- Position itself as you set in the backoffice
- Display the pages you enabled
- Apply all your custom settings
Configuration
$3
| Parameter | Type | Description |
|-----------|------|-------------|
| widgetId | string | Required. Your unique widget identifier from the backoffice |
That's the only parameter you need!
$3
All widget settings are managed in your backoffice:
- 🎨 Theme colors (primary, button, launcher, accent)
- 📍 Position (bottom-right, bottom-left, top-right, top-left)
- 📄 Enabled pages (home, chat, help, status, etc.)
- 🚀 Auto-open behavior
- 🏠 Starting page
- 💬 Welcome message
- And much more!
This centralized approach means:
- ✅ No code changes needed to update widget appearance
- ✅ Consistent styling across all your sites
- ✅ Easy A/B testing from the backoffice
- ✅ Instant updates without redeploying your app
Usage Examples
$3
`html
My Website
Welcome to my website
`
$3
#### Using the Component (Easiest)
`tsx
import { HelpdeskWidgetReact } from '@weldsuite/helpdesk-widget-sdk/react';
function App() {
return (
My App
);
}
`
#### Using the Hook
`tsx
import { useHelpdeskWidget } from '@weldsuite/helpdesk-widget-sdk/react';
function App() {
const widget = useHelpdeskWidget({ widgetId: 'your-widget-id' });
return (
);
}
`
#### Using the Controls Hook
`tsx
import { useHelpdeskWidgetControls } from '@weldsuite/helpdesk-widget-sdk/react';
function App() {
const { show, hide, toggle } = useHelpdeskWidgetControls({
widgetId: 'your-widget-id'
});
return (
);
}
`
#### With Event Handlers
`tsx
import { HelpdeskWidgetReact } from '@weldsuite/helpdesk-widget-sdk/react';
function App() {
return (
widgetId="your-widget-id"
onReady={(event) => console.log('Widget ready!', event)}
onOpened={(event) => console.log('Widget opened!', event)}
onClosed={(event) => console.log('Widget closed!', event)}
/>
);
}
`
$3
#### App Router (Client Component)
`tsx
// components/WidgetProvider.tsx
'use client';
import { HelpdeskWidgetReact } from '@weldsuite/helpdesk-widget-sdk/react';
export default function WidgetProvider() {
return (
widgetId={process.env.NEXT_PUBLIC_WIDGET_ID!}
/>
);
}
`
Then add to your layout:
`tsx
// app/layout.tsx
import WidgetProvider from './components/WidgetProvider';
export default function RootLayout({ children }) {
return (
{children}
);
}
`
$3
#### Using the Component (Easiest)
`vue
My App
`
#### Using the Composable
`vue
`
#### Using the Controls Composable
`vue
`
#### With Event Handlers
`vue
widget-id="your-widget-id"
:on-ready="handleReady"
:on-opened="handleOpened"
/>
`
$3
#### Using the Standalone Component (Angular 14+)
`typescript
// app.component.ts
import { Component } from '@angular/core';
import { HelpdeskWidgetComponent } from '@weldsuite/helpdesk-widget-sdk/angular';
@Component({
selector: 'app-root',
standalone: true,
imports: [HelpdeskWidgetComponent],
template:
})
export class AppComponent {}
`
#### Using the Module (Pre-Angular 14)
`typescript
// app.module.ts
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { HelpdeskWidgetModule } from '@weldsuite/helpdesk-widget-sdk/angular';
import { AppComponent } from './app.component';
@NgModule({
declarations: [AppComponent],
imports: [
BrowserModule,
HelpdeskWidgetModule
],
bootstrap: [AppComponent]
})
export class AppModule {}
`
`typescript
// app.component.ts
import { Component } from '@angular/core';
@Component({
selector: 'app-root',
template:
})
export class AppComponent {}
`
#### Using the Service
`typescript
// app.component.ts
import { Component } from '@angular/core';
import { HelpdeskWidgetService } from '@weldsuite/helpdesk-widget-sdk/angular';
@Component({
selector: 'app-root',
template:
})
export class AppComponent {
constructor(private helpdeskService: HelpdeskWidgetService) {
this.helpdeskService.initialize({ widgetId: 'your-widget-id' });
}
showSupport() {
this.helpdeskService.show();
}
}
`
#### With Event Handlers
`typescript
// app.component.ts
import { Component } from '@angular/core';
import { HelpdeskWidgetComponent } from '@weldsuite/helpdesk-widget-sdk/angular';
@Component({
selector: 'app-root',
standalone: true,
imports: [HelpdeskWidgetComponent],
template:
})
export class AppComponent {
handleReady = (event: any) => {
console.log('Widget ready', event);
}
handleOpened = (event: any) => {
console.log('Widget opened', event);
}
}
`
$3
#### Using the Component
`svelte
My App
`
#### With Programmatic Control
`svelte
`
#### With Event Handlers
`svelte
widgetId="your-widget-id"
onReady={handleReady}
onOpened={handleOpened}
/>
`
Environment Configuration
The SDK supports different environments with easy configuration:
$3
`typescript
import { initHelpdeskWidget } from '@weldsuite/helpdesk-widget-sdk';
// Automatically uses https://widget.welddesk.com
initHelpdeskWidget({ widgetId: 'your-widget-id' });
`
$3
`typescript
import { initHelpdeskWidget, DEV_CONFIG } from '@weldsuite/helpdesk-widget-sdk';
// Uses http://localhost:3100
initHelpdeskWidget({
widgetId: 'your-widget-id',
baseUrl: DEV_CONFIG.baseUrl
});
`
$3
`typescript
import { initHelpdeskWidget, STAGING_CONFIG } from '@weldsuite/helpdesk-widget-sdk';
// Uses https://widget-staging.welddesk.com
initHelpdeskWidget({
widgetId: 'your-widget-id',
baseUrl: STAGING_CONFIG.baseUrl
});
`
$3
`typescript
import { initHelpdeskWidget } from '@weldsuite/helpdesk-widget-sdk';
initHelpdeskWidget({
widgetId: 'your-widget-id',
baseUrl: 'https://your-custom-domain.com'
});
`
Event Handling
The SDK provides type-safe event handlers for widget lifecycle events:
$3
- widget:ready - Widget iframe has loaded and is ready
- widget:opened - Widget panel has been opened
- widget:closed - Widget panel has been closed
- widget:error - An error occurred in the widget
$3
#### Via Configuration
`typescript
import { initHelpdeskWidget } from '@weldsuite/helpdesk-widget-sdk';
const widget = initHelpdeskWidget({
widgetId: 'your-widget-id',
onReady: (event) => {
console.log('Widget is ready!', event);
},
onOpened: (event) => {
console.log('Widget opened!', event);
// Track analytics, etc.
},
onClosed: (event) => {
console.log('Widget closed!', event);
},
onError: (event) => {
console.error('Widget error:', event.data);
}
});
`
#### Using on() Method
`typescript
import { HelpdeskWidget } from '@weldsuite/helpdesk-widget-sdk';
const widget = new HelpdeskWidget({ widgetId: 'your-widget-id' });
// Register event handlers
widget.on('widget:ready', (event) => {
console.log('Ready!', event);
});
widget.on('widget:opened', (event) => {
console.log('Opened!', event);
});
widget.init();
`
#### Removing Event Handlers
`typescript
const handleReady = (event) => {
console.log('Ready!', event);
};
// Add handler
widget.on('widget:ready', handleReady);
// Remove handler
widget.off('widget:ready', handleReady);
`
API Reference
$3
Convenience function that creates and initializes the widget in one call.
Parameters:
- config.widgetId (string, required) - Your widget ID
Returns: HelpdeskWidget instance
Example:
`javascript
const widget = initHelpdeskWidget({ widgetId: 'your-widget-id' });
`
$3
#### Constructor
`typescript
new HelpdeskWidget(config: { widgetId: string })
`
#### Methods
##### init(): void
Initialize and mount the widget to the page.
`javascript
const widget = new HelpdeskWidget({ widgetId: 'your-widget-id' });
widget.init();
`
##### destroy(): void
Remove the widget from the page and clean up resources.
`javascript
widget.destroy();
`
##### show(): void
Show the widget.
`javascript
widget.show();
`
##### hide(): void
Hide the widget.
`javascript
widget.hide();
`
##### toggle(): void
Toggle widget visibility.
`javascript
widget.toggle();
`
##### sendMessage(message: any): void
Send a custom message to the widget (for advanced integrations).
`javascript
widget.sendMessage({ type: 'custom-event', data: { foo: 'bar' } });
`
Programmatic Control
`javascript
const widget = initHelpdeskWidget({ widgetId: 'your-widget-id' });
// Show widget programmatically
document.getElementById('help-btn').addEventListener('click', () => {
widget.show();
});
// Hide widget
document.getElementById('close-btn').addEventListener('click', () => {
widget.hide();
});
// Toggle widget
document.getElementById('toggle-btn').addEventListener('click', () => {
widget.toggle();
});
`
Environment Variables
Store your widget ID in environment variables:
`bash
.env
NEXT_PUBLIC_WIDGET_ID=your-widget-id
VITE_WIDGET_ID=your-widget-id
REACT_APP_WIDGET_ID=your-widget-id
`
Then use it:
`javascript
initHelpdeskWidget({
widgetId: process.env.NEXT_PUBLIC_WIDGET_ID // Next.js
// or
widgetId: import.meta.env.VITE_WIDGET_ID // Vite
// or
widgetId: process.env.REACT_APP_WIDGET_ID // Create React App
});
`
TypeScript Support
Full TypeScript support is included. No additional @types packages needed!
`typescript
import { HelpdeskWidget, HelpdeskWidgetConfig } from '@weldsuite/helpdesk-widget';
const config: HelpdeskWidgetConfig = {
widgetId: 'your-widget-id'
};
const widget = new HelpdeskWidget(config);
widget.init();
`
Backoffice Configuration
All widget behavior and appearance is controlled from your backoffice dashboard:
$3
- Primary color
- Button color
- Button text color
- Launcher color
- Header color
- Accent color
- Border radius
- Font size
$3
- Position (bottom-right, bottom-left, top-right, top-left)
- Auto-open on page load
- Starting page
- Welcome message
- Company name
$3
- Home
- Chat/Messages
- Help
- Status
- Changelog
- News
- Feedback
- Announcements
- Event Sign-up
- Parcel Tracking
$3
- Text color
- Background color
Simply log into your backoffice, update your widget settings, and see changes instantly on all sites using that widget ID - no code deployment needed!
Browser Support
- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)
- iOS Safari (latest)
- Chrome for Android (latest)
Security
The widget is loaded in an isolated iframe with:
- Restricted iframe permissions
- Origin-verified postMessage communication
- No access to parent page DOM or JavaScript
- Secure HTTPS-only loading
Troubleshooting
$3
1. Check widget ID - Verify it matches your backoffice configuration
2. Check console - Look for error messages in browser console
3. Check backoffice - Make sure the widget is enabled and configured
4. Network check - Verify https://widget.welddesk.com is accessible
$3
Don't edit the code! Just update the settings in your backoffice dashboard. Changes will take effect immediately.
$3
Create multiple widget IDs in your backoffice with different configurations, then swap the widgetId in your code:
`javascript
// Development widget
const devWidgetId = 'dev-widget-123';
// Production widget
const prodWidgetId = 'prod-widget-456';
initHelpdeskWidget({
widgetId: process.env.NODE_ENV === 'production' ? prodWidgetId : devWidgetId
});
`
FAQ
Q: Can I change the widget color from my code?
A: No, all styling is managed in the backoffice. This ensures consistency across all your properties.
Q: Can I set the position programmatically?
A: No, position is configured in the backoffice per widget ID.
Q: How do I enable/disable specific pages?
A: Configure enabled pages in your backoffice dashboard.
Q: Can I have multiple widgets on one page?
A: Yes! Create multiple widget IDs in your backoffice and initialize each one:
`javascript
initHelpdeskWidget({ widgetId: 'sales-widget' });
initHelpdeskWidget({ widgetId: 'support-widget' });
``