Customizing Your Chat Widget

Last updated: May 20, 2025

Mastering Your ConvoDocs Chat Widget Customization

The ConvoDocs chat widget is the primary interface for your users to interact with your AI agent. Customizing it effectively is key to providing a seamless and branded user experience on your website. This guide covers all aspects of widget customization and embedding.

Accessing Widget Settings

For each agent you create, you can customize its associated chat widget. These settings are typically found in a dedicated "Widget" or "Appearance" tab within the agent's configuration page.

Detailed Widget Settings

1. Appearance & Branding

  • Theme:
    • Light: A clean, bright interface suitable for websites with lighter color schemes.
    • Dark: A modern, sleek interface ideal for websites with darker backgrounds.
    • Consider an "Auto" or "System" option if available, which respects the user's operating system preference.
  • Brand Colors:
    • Primary Color: Defines the main accent color for interactive elements like send buttons, chat bubbles (for agent or user), and highlights. Choose your main brand color here.
    • Secondary Color (Optional): An additional accent color for less prominent elements, or for hover states.
    • Widget Background Color: The overall background of the chat window.
    • Text Color: The color for general text within the chat. Ensure high contrast against the background (e.g., dark text on light background, light text on dark background).
    • Header Background Color: Specific background color for the widget's header area.
    • Header Text Color: Text color for the widget's header.

    Always preview your color choices to ensure readability and accessibility (WCAG AA contrast ratios are a good benchmark).

  • Custom Widget Icon/Launcher Button:
    • Upload your company logo or a custom icon that users will click to open the chat widget.
    • Supported formats usually include PNG, JPG, SVG. SVG is recommended for scalability.
    • Consider the size and appearance of the icon in its collapsed state.
  • Widget Font (If available): Some systems might allow you to choose from a selection of web-safe fonts or even specify a custom font family to match your website.

2. Position & Display

  • Widget Position on Page:
    • Bottom Right: Most common and often expected by users.
    • Bottom Left: A good alternative, especially if you have other elements on the bottom right.
    • Ensure the widget doesn't obstruct critical navigation or content on your site, especially on mobile devices.
  • Desktop & Mobile Offsets: Fine-tune the spacing of the widget from the edges of the screen (e.g., 20px from the bottom, 20px from the right). This might have separate settings for desktop and mobile views.

3. Text & Prompts

  • Header Text/Title: The text displayed at the top of the open chat widget (e.g., "Chat with Support", "Ask Our AI", your agent's name). Keep it concise and inviting.
  • Welcome Message/Initial Greeting: An optional message automatically sent by the agent when a user first opens the chat (e.g., "Hi there! How can I help you today?"). This can make the interaction more engaging.
  • Placeholder Text for Input Field: The guiding text within the message input area before the user types (e.g., "Type your message...", "Ask a question").
  • User Avatar / Agent Avatar: Option to display default or custom avatars for the user and the agent within the chat conversation.

Embedding the Widget on Your Website

Once you've customized your widget, you'll need to embed it into your website. This typically involves the following steps:

  1. Copy the Embed Code: In the widget settings, there will be a section to get your unique JavaScript embed code snippet. Copy this entire snippet.
  2. Paste into Your Website's HTML:
    • The most common practice is to paste this code just before the closing </body> tag in your website's HTML template(s).
    • If you're using a Content Management System (CMS) like WordPress, Shopify, etc., look for options to add custom JavaScript or scripts to the site footer. Many themes or plugins facilitate this.
    • For Single Page Applications (SPAs) built with frameworks like React, Angular, or Vue, you'll integrate the snippet into your main application template or initialize it within a suitable component lifecycle method.
  3. Verify Installation: After adding the code and deploying your website changes, open your site in a browser and check if the widget appears and functions as expected. Use your browser's developer console to check for any JavaScript errors.

Security Considerations for Widget Embedding

  • Allowed Domains: This is a critical security feature. Ensure your agent's settings restrict the widget to operate *only* on your authorized website domains. This prevents others from copying your widget code and using your agent on their unapproved sites, which could consume your resources.
  • Content Security Policy (CSP): If your website uses a strict CSP, you may need to update it to allow scripts and connections from the ConvoDocs domain that serves the widget. Refer to ConvoDocs documentation for specific CSP directives if required.

Best Practices for Widget Customization & Deployment

  • Consistency with Brand: Ensure the widget's colors, fonts (if customizable), and tone match your overall website branding for a cohesive user experience.
  • Mobile Responsiveness: Test the widget thoroughly on various mobile devices and screen sizes. Ensure it's easy to use and doesn't cover important content.
  • Accessibility: Choose color combinations with sufficient contrast. Ensure keyboard navigation is possible for users who cannot use a mouse.
  • Clear Call to Action: Make the widget launcher icon or button clearly visible and understandable.
  • Performance: While generally optimized, be mindful of the widget's impact on your page load times, especially if you have many other third-party scripts.
  • A/B Test (Advanced): If you have the capability, consider A/B testing different widget positions, colors, or welcome messages to see what resonates best with your users.
  • Regularly Review: Periodically check your live widget to ensure it's working correctly, especially after major website updates or ConvoDocs platform updates.

By thoughtfully customizing and embedding your chat widget, you can create a powerful and user-friendly channel for customers to engage with your ConvoDocs AI agent.

Back to Widget