Overview
This guide covers common issues you may encounter when integrating the AI Chat SDK and how to resolve them.
Installation issues
Package not found
Symptom: npm install or pnpm add fails with “package not found”
Solution:
Configure .npmrc
Add the registry configuration to your .npmrc file:@sleek:registry=https://npm.cloudsmith.io/sleek/sleek/
//npm.cloudsmith.io/sleek/sleek/:_authToken={YOUR_TOKEN_HERE}
Add your token
Replace {YOUR_TOKEN_HERE} with your authentication token
Install the package
pnpm add @sleek/ai-chat-sdk
Module not found
Symptom: Cannot find module '@sleek/ai-chat-sdk'
Solution: Verify your TypeScript configuration includes:
{
"compilerOptions": {
"moduleResolution": "bundler",
"esModuleInterop": true
}
}
SDK initialization issues
SDK not initializing
Symptom: SDK initialization fails or throws error
Solution: Enable debug mode to see detailed error messages:
import { initializeAiChatSdk } from '@sleek/ai-chat-sdk';
const sdk = initializeAiChatSdk('your-api-key', {
enableDebug: true, // Shows detailed logs in console
chatConfig: {
// ... your config
},
dataProviders: {
offerRedirectUrlProvider: async (url) => null,
merchantCashbackProvider: async (urls) => ({}),
},
});
”SDK already initialized” error
Symptom: Error when calling initializeAiChatSdk multiple times
Solution: The SDK returns the existing instance if already initialized. Use getAiChatSdk() to retrieve the existing instance:
import { getAiChatSdk } from '@sleek/ai-chat-sdk';
const sdk = getAiChatSdk();
sdk.initializeChat();
UI issues
Chat panel not appearing
Symptom: Calling sdk.initializeChat() doesn’t show the chat panel
Common causes:
- Invalid or missing API key
- SDK not initialized before calling
initializeChat()
- JavaScript errors in console
Solution:
Check browser console
Open DevTools (F12) and look for error messages
Verify initialization
try {
const sdk = getAiChatSdk();
sdk.initializeChat();
} catch (error) {
console.error('SDK error:', error);
}
Chat panel appears blank
Symptom: Panel opens but shows blank content
Solution:
- Verify your API key is valid
- Check browser console for network errors
- Ensure you have internet connectivity
- Try clearing browser cache
Badge not appearing
Symptom: Calling sdk.showBadge() doesn’t show the badge
Solution:
// Ensure SDK is initialized first
const sdk = getAiChatSdk();
// Show badge
await sdk.showBadge();
badgeConfig.allowExpand is set to false and there are no prompts- Layout position places it off-screen
Symptom: Calling sdk.showInline() doesn’t show the inline input
Solution: Ensure you’ve configured a valid container selector:
initializeAiChatSdk('your-api-key', {
inlineConfig: {
layout: {
containerSelector: '#chat-container', // Must exist in the DOM
},
},
dataProviders: {
offerRedirectUrlProvider: async (url) => null,
merchantCashbackProvider: async (urls) => ({}),
},
});
// Make sure the container exists before calling showInline
const container = document.querySelector('#chat-container');
if (container) {
await sdk.showInline();
}
Data provider issues
Providers not being called
Symptom: Data providers never execute
Solution: Ensure providers are configured correctly:
dataProviders: {
offerRedirectUrlProvider: async (url) => {
console.log('Provider called for:', url);
// Your implementation
return 'https://example.com/offer';
},
merchantCashbackProvider: async (urls) => {
console.log('Cashback requested for:', urls);
// Your implementation
return {};
},
}
Provider errors
Symptom: SDK stops working after provider throws error
Solution: Always handle errors and return valid fallback values:
const offerRedirectUrlProvider = async (url) => {
try {
const response = await fetch(`/api/offers?url=${url}`);
const data = await response.json();
return data.offerUrl || null;
} catch (error) {
console.error('Provider error:', error);
return null; // Always return null on error
}
};
const merchantCashbackProvider = async (urls) => {
try {
const response = await fetch('/api/cashback', {
method: 'POST',
body: JSON.stringify({ urls }),
});
const data = await response.json();
return data.cashback || {};
} catch (error) {
console.error('Provider error:', error);
return {}; // Always return {} on error
}
};
const offerRedirectUrlProvider = async (url) => {
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 500);
try {
const response = await fetch(url, { signal: controller.signal });
clearTimeout(timeout);
return response.offerUrl;
} catch (error) {
clearTimeout(timeout);
return null;
}
};
Event issues
Events not firing
Symptom: Event listeners are never called
Solution: Ensure listeners are registered during initialization:
initializeAiChatSdk('your-api-key', {
// ... config
}, [
// Event listeners must be passed here
(event) => {
console.log('Event:', event.type, event.data);
}
]);
Event listeners cannot be added after SDK initialization. They must be passed as the third parameter to initializeAiChatSdk().
Network issues
API requests failing
Symptom: Chat not responding, network errors in console
Solution:
Verify API key
Ensure your API key is correct and active
Check network
Verify you have internet connectivity
Enable debug mode
Check console for detailed error messages Check browser console
Look for 401/403 errors indicating authentication issues
Configuration issues
Colors not applying
Symptom: Custom colors don’t appear in the UI
Solution: Verify you’re using the correct configuration structure:
chatConfig: {
styling: {
primaryColor: '#5C59FE', // For light mode
primaryColorDarkMode: '#8B87FF', // For dark mode
colorMode: 'system', // 'light' | 'dark' | 'system'
},
}
Logo not appearing
Symptom: Logo doesn’t show in the chat header
Solution: Check the brand configuration:
chatConfig: {
brand: {
name: 'Your Brand',
logoUrl: 'https://your-app.com/logo.png', // Must be a valid, accessible URL
},
}
- URL not accessible (CORS issues)
- Invalid image format
- Image too large to load
Browser compatibility
The SDK supports modern browsers:
- Chrome 100+
- Firefox 100+
- Safari 15+
- Edge 100+
For best results, ensure users are on the latest browser version.
Debugging tips
Enable debug mode
Always start troubleshooting with debug mode enabled:
initializeAiChatSdk('your-api-key', {
enableDebug: true,
// ... other config
});
Check SDK version
Verify you’re using the latest version:
pnpm list @sleek/ai-chat-sdk
pnpm update @sleek/ai-chat-sdk
Test in incognito mode
Test in incognito/private browsing to rule out:
- Browser extension interference
- Cached data issues
- Cookie problems
Check the console
Always check the browser DevTools Console (F12) for:
- Error messages
- Network failures
- SDK debug logs
Common error messages
”Invalid API key”
Your API key is incorrect or inactive. Verify your key and ensure it’s active.
”AI Chat SDK not initialized”
You’re trying to use getAiChatSdk() before calling initializeAiChatSdk(). Ensure SDK is initialized first:
// Initialize first
const sdk = initializeAiChatSdk('your-api-key', { ... });
// Then use it
sdk.initializeChat();
// Or later, retrieve the instance
const sdk = getAiChatSdk(); // Works after initialization
“Data provider error”
- Ensure providers return correct types (
null or {} on error)
- Add try-catch blocks to all providers
- Never throw exceptions from providers
Getting help
If you’re still experiencing issues, contact our support team.
When contacting support, please include:
- SDK version (
pnpm list @sleek/ai-chat-sdk)
- Browser name and version
- Error messages from console (with
enableDebug: true)
- Code snippet of your SDK initialization
- Steps to reproduce the issue
