FirstDistro Widget SDK
Embed our AI-powered customer success widget on your website in minutes. Transform product confusion into customer success.
Quick integration
Add 3 lines of code to your website. No complex setup or dependencies required.
Secure & private
API key authentication with rate limiting. Your data stays secure.
Works everywhere
Compatible with any website. React, Vue, vanilla HTML - it just works.
Quick start guide
Get your API key
Log in to your dashboard and generate an API key from the Chat Widget settings.
Go to DashboardAdd SDK to your website
Copy this code snippet and paste it before the closing </body> tag of your HTML.
<!-- FirstDistro Widget SDK -->
<script src="https://firstdistro.com/sdk/sdk.js"></script>
<script>
FirstDistro.init({
vendorId: 'your-vendor-id',
apiKey: 'your-api-key'
});
</script>You're Done!
The widget will appear on your website. Customize it further from your dashboard.
Event listeners
Track widget interactions and integrate with your CRM, analytics, and custom workflows.
Available events
// Get widget instance
const widget = FirstDistro.getInstance();
// Widget is ready and loaded
widget.on('widget-ready', (data) => {
console.log('Widget initialized!', data.sessionId);
});
// Lead captured (email/contact info submitted)
widget.on('lead-captured', (data) => {
console.log('New lead:', data.email, data.name);
// Send to your CRM
sendToHubSpot(data.email, data.name);
// Track in analytics
analytics.identify(data.email, {
name: data.name,
sessionId: data.sessionId
});
});
// Conversation started
widget.on('conversation-started', (data) => {
console.log('User started chatting');
analytics.track('Conversation Started');
});
// Product recommendation clicked
widget.on('recommendation-clicked', (data) => {
console.log('Product clicked:', data.productTitle);
analytics.track('Product Interest', {
product: data.productTitle,
confidence: data.confidence
});
});
// Widget expanded/collapsed
widget.on('widget-expanded', () => {
console.log('Widget opened');
});
widget.on('widget-collapsed', () => {
console.log('Widget minimized');
});
// Error handling
widget.on('error', (data) => {
console.error('Widget error:', data.error);
// Send to error tracking (Sentry, etc.)
});💡 Integration tips
- • Use
lead-capturedto sync with CRM (HubSpot, Salesforce, Pipedrive) - • Track
recommendation-clickedfor product analytics - • Monitor
errorevents with Sentry or Datadog - • Measure engagement time using
widget-expanded/widget-collapsed
Configuration reference
All configuration options (most are optional and use dashboard defaults)
💡 Best Practice: Use Dashboard Configuration
The minimal SDK setup (vendorId + apiKey) automatically loads your settings from the dashboard. This gives you industry-smart defaults, instant updates without code changes, and centralized configuration.
| Option | Type | Required | Description |
|---|---|---|---|
| vendorId | string | Yes | Your vendor ID from dashboard |
| apiKey | string | Yes | Your API key for authentication |
| position | string | No | bottom-left, bottom-center, bottom-right (default: bottom-center) |
| theme.primaryColor | string | No | Widget primary color (default: #0066ff) |
| aiPersona.name | string | No | AI assistant name (defaults to industry-smart name from dashboard) |
| aiPersona.greeting | string | No | Greeting message (defaults to industry-smart greeting from dashboard) |
| debug | boolean | No | Enable console logging (default: false) |
| mobile.fullscreen | boolean | No | Full-screen on mobile (default: true) |
| analytics.enabled | boolean | No | Enable automatic tracking (default: true) |
Advanced configuration
Override dashboard settings for specific use cases
When to use advanced options
- •You need different personas on different pages/domains
- •A/B testing different AI personalities
- •White-label deployments for multiple clients
Example: Override AI persona
FirstDistro.init({
vendorId: 'your-vendor-id',
apiKey: 'your-api-key',
// Override dashboard persona for this specific page
aiPersona: {
name: 'Alex',
greeting: 'Hi! I\'m Alex, your telecom solutions expert.'
},
// Optional: Custom theme
theme: {
primaryColor: '#ff6600'
},
// Optional: Custom position
position: 'bottom-right'
});Troubleshooting
Widget not appearing on page?
</body> tagdebug: true to see detailed logs"Invalid API key" error?
Seeing CORS warnings in console?
Widget script not loading?
/sdk/sdk.js is loadingdefer attribute if there are conflicts