Needle Widget V2
The Needle Widget V2 is a powerful drop-in solution that enables you to add a RAG-powered chatbot to your website in seconds. RAG-powered chatbot helps increase user engagement and streamlines information discovery for your offerings.
You can integrate Widget V2 in two different ways:
- Open as a modal programmatically
- Embed it directly to your webpage
Modal Widget
Needle Modal Widget
Open the widget as a popup/modal programmatically.
1. Add Widget Script
Add the following script tag to your HTML <head> section:
<script src="https://cdn.needle-ai.com/widget/v2/main.js"></script>
2. Open the Modal
Add a custom button to your website to open the widget:
<button onclick="openModal()">Ask AI</button>
Open the modal with the window.needle.openModal(...) function with the options:
function openModal() {
window.needle.openModal({
collectionId: "clt_your_collection_id",
clientKey: "clk_your_client_key",
title: "Ask AI",
initialMessage: "Hi, I am an AI assistant. How can I help you?",
initialSuggestions:
"What are your features?, How do I get started?, Contact support",
theme: "system",
chatTemplateId: "optional_template_id",
});
}
Embedded Widget
Needle Embedded Widget
Embed the widget directly to your webpage.
1. Add Widget Script
Add the following script tag to your HTML <head> section:
<script src="https://cdn.needle-ai.com/widget/v2/main.js"></script>
2. Add Widget Component
Add the widget component to your HTML <body>:
<needle-embedded-widget
collection-id="clt_your_collection_id"
client-key="clk_your_client_key"
title="Ask AI"
initial-message="Hi, I am an AI assistant. How can I help you?"
initial-suggestions="What are your features?, How do I get started?, Contact support"
theme="system"
chat-template-id="optional_template_id"
></needle-embedded-widget>
Reference
Both widgets support following options:
Configuration Options
| Option | Type | Required | Description |
|---|---|---|---|
collection-id | string | Yes | Your Needle collection ID (starts with clt_) |
client-key | string | Yes | Your client key (starts with clk_) |
title | string | No | Widget title (default: "Ask AI") |
initial-message | string | No | Initial greeting message |
initial-suggestions | string | No | Semicolon-separated (;) list of suggestion questions |
theme | string | No | Theme mode: "light", "dark", or "system" |
chat-template-id | string | No | Optional chat template ID for custom system prompt |
Styling Options
The widgets can be customized by using CSS. Here are the available parts:
| CSS Part Selector | Description |
|---|---|
chat-dialog | The modal dialog container for the chat widget |
chat-container | Main container that wraps the entire chat widget |
chat-messages | Container for all chat messages |
chat-message-user | Styling for messages sent by the user |
chat-message-ai | Styling for messages sent by the AI assistant |
chat-message-error | Styling for error messages displayed in chat |
chat-loading-bubble | Loading indicator shown while AI is responding |
chat-suggestion-list | Container for the list of suggestion buttons |
chat-suggestion | Individual suggestion button styling |
chat-input | Container for the chat input area |
chat-input-textarea | Text input field for typing messages |
chat-input-button | Send button in the chat input area |
chat-source | Source attribution for AI responses |
markdown-code | Code block styling in markdown messages |
markdown-code-inline | Inline code styling in markdown messages |
CSS Customization
You can customize the appearance of the widget using CSS parts. Here are some examples:
needle-modal-widget::part(chat-container) {
background: blue;
}
/* or */
needle-embedded-widget::part(chat-container) {
background: blue;
}
You can add these styles to your website's CSS file or include them in a <style> tag in your HTML. Feel free to adjust the colors, sizes, and other properties to match your website's design.
Troubleshooting
If you encounter an Unauthorized Error, verify the following:
- Your collection ID is correct (must start with
clt_) - Your client key is correct (must start with
clk_) - The website is whitelisted properly on widget settings page
- The widget script is properly loaded
- The widget component is properly added to your page
Need Help?
You can contact us anytime by discord or email. We are happy to help!