Skip to main content
ChattyBox Logo
ChattyBox

Widget Setup & Customization

Add an AI-powered chat widget to your website in under 5 minutes.

Quick Setup​

Getting your chatbot live is simple. You just need to copy a small snippet of code from your dashboard.

Step 1: Get Your Embed Code​

  1. Go to your Dashboard and select your project.
  2. Navigate to the Embed tab.
  3. Select the API key you want to use (or create a new one).
  4. Copy the generated code snippet.

Step 2: Add to Your Website​

Paste the code snippet just before the closing </body> tag on every page where you want the chat widget to appear.

<script
  src="https://chattybox.ai/widget.js?v=7"
  data-api-key="YOUR_API_KEY"
  async
></script>
Pro Tip

That's it! You don't need to configure colors or settings in the code. Everything is managed from your dashboard.

Visual Customization​

ChattyBox comes with a fully integrated visual editor. You can tweak the look and feel of your widget to match your brand perfectly without touching any code.

Dashboard Controls​

  1. Accent Color - Pick your brand's primary color. This affects the launcher, key highlights, and user messages.

  2. Position - Choose where the widget appears on the screen.

  3. Header Title - Set the title shown at the top of the chat window.

  4. Welcome Message - Customize the first message visitors see when they open the chat.

note

Changes made in the dashboard are applied instantly. You do not need to update the embed code on your site.

Advanced Options​

Hide the Widget on Specific Pages​

If you need to hide the widget on selected pages, you can do so with CSS:

.chattybox-widget {
  display: none;
}

Custom Integrations​

Need a more tailored setup than the standard widget?

Contact us at support@chattybox.ai and we can help you choose the right integration approach for your use case.

Multilingual Support​

The ChattyBox widget automatically adapts to your visitors' language preferences, providing a localized experience for users worldwide.

Officially Supported Languages​

The widget interface (buttons, labels, and system messages) is officially supported in 14 languages:

LanguageCodeWidget UIAI Response Quality
EnglishenFull SupportExcellent
FrenchfrFull SupportHigh
GermandeFull SupportHigh
SpanishesFull SupportHigh
ItalianitFull SupportHigh
DutchnlFull SupportHigh
PortugueseptFull SupportHigh
PolishplFull SupportHigh
SwedishsvFull SupportHigh
IndonesianidFull SupportMedium
EstonianetFull SupportMedium
FinnishfiFull SupportMedium
WelshcyFull SupportMedium
CzechcsFull SupportMedium
Extended Language Support

While we officially support 14 languages for the widget interface, the underlying AI can understand and respond in 100+ languages. However, we cannot guarantee high-quality responses for languages outside our officially supported list.

How Language Detection Works​

The widget uses a cascading detection system:

  1. data-locale attribute - Highest priority. Set this on your embed code to force a specific language.
  2. Page <html lang> attribute - The widget checks your page's declared language.
  3. Browser language (navigator.language) - Uses the visitor's browser preferences.
  4. Default fallback - English if no language is detected.

Manual Language Override​

To force the widget to display in a specific language regardless of browser settings, add the data-locale attribute:

<script
  src="https://chattybox.ai/widget.js?v=7"
  data-api-key="YOUR_API_KEY"
  data-locale="de"
  async
></script>
Use Case

This is particularly useful if you have a multilingual website where each language version has its own URL (e.g., /de/, /fr/). Set data-locale to match each page's language for consistent user experience.

Dashboard Language Settings​

The app dashboard allows you to configure widget language preferences per project:

  • Auto-detect (Recommended) - Automatically matches the visitor's browser language
  • Fixed Language - Force the widget to always display in a specific language
  • Allow Script Override - Enable/disable the data-locale attribute override

Access these settings in your Dashboard → Project → Embed tab → Widget Language section.

Content Language Matching​

For the best multilingual experience, your chatbot should return answers in the same language as the user's question. To achieve this:

  1. Scrape all language versions of your documentation using the sitemap_index.xml file
  2. The scraper will automatically tag content with its language
  3. The RAG system retrieves the appropriate language version based on the query

Setup in App Dashboard: When configuring scraping, use your sitemap_index.xml URL (e.g., https://yourdocs.com/sitemap_index.xml) to automatically discover and index all language versions of your content.

Troubleshooting​

Widget Still Shows English​

  • Clear browser cache - The widget.js file may be cached. Hard refresh (Ctrl+F5 / Cmd+Shift+R)
  • Check data-locale - Verify the attribute is set correctly with a supported language code
  • Verify browser language - Check that your browser's preferred language is set correctly
  • Check page HTML lang - Ensure your page has <html lang="de"> (or appropriate code)

Sources Are in Wrong Language​

  • Re-scrape your content - Ensure all language versions are indexed
  • Use sitemap_index.xml - This ensures the scraper finds all /de/, /fr/, etc. URLs
  • Check query language - The AI attempts to match response language to query language

Missing Translations​

  • Check supported languages - Only the 14 languages listed above have guaranteed UI translations
  • Update widget.js - Ensure you're using the latest version (?v=7 or higher)

Best Practices​

  1. Set <html lang> on your pages - Helps with accessibility and widget detection
  2. Test with data-locale during development - Verify each language renders correctly
  3. Scrape all language versions - Use sitemap_index.xml for comprehensive multilingual indexing
  4. Monitor language distribution - Check analytics to see which languages your visitors use most