Skip to main content

Configuration Guide

This comprehensive guide covers all configuration options available in the NextGen OpenAI Chatbot plugin.

Configuration Overview​

Access the configuration by navigating to: Extensions > My Extensions > NextGen OpenAI Chatbot > Configure

The configuration is organized into several sections:

1. OpenAI Authentication Configuration​

Enable Plugin​

  • Purpose: Master switch to enable/disable the plugin
  • Default: Disabled
  • Recommendation: Enable only after completing all setup steps

OpenAI API Key​

  • Purpose: Your secret API key from OpenAI
  • Format: Starts with sk-
  • Security: Never share this key publicly
  • Testing: Use the "Test API Key" button to verify connection

Assistant ID​

  • Purpose: The ID of your OpenAI Assistant
  • Format: Starts with asst_
  • Location: Found in your OpenAI Platform > Assistants section

2. OpenAI Assistant Configuration​

Chatbot Name​

  • Purpose: Display name for your chatbot
  • Example: "Sarah", "ShopBot", "AI Assistant"
  • Visibility: Appears next to the avatar in the chat interface
  • Tip: Choose a name that matches your brand personality

3. Customer Authentication​

Only for Authenticated Users​

  • Purpose: Restrict chatbot access to logged-in customers only
  • Default: Disabled (available to all visitors)
  • Use Case: Premium support for registered customers

Customer Group Restrictions​

  • Purpose: Limit access to specific customer groups
  • Dependency: Only works when "Only for authenticated users" is enabled
  • Example: VIP customers, Premium members

4. Free Text Fields​

Additional Instructions​

  • Purpose: Extra instructions for the assistant
  • Usage: Provide context-specific guidelines
  • Example: "Always mention our 30-day return policy"
  • Requirement: Enable 'fetch_initial_chat_guidelines' function

FAQ Data​

  • Purpose: Store frequently asked questions and answers
  • Format: Free text format
  • Access: Assistant can reference this data when responding
  • Requirement: Enable 'get_faqs' function

Meta Information​

  • Purpose: General knowledge base for the assistant
  • Alternative: Use instead of uploading files to OpenAI
  • Content: Company policies, product information, etc.
  • Requirement: Enable 'get_meta_information' function

5. Contact Form AI Assistant​

Enable Form Integration​

  • Purpose: Add AI assistance to contact forms
  • Feature: Provides suggestions before form submission
  • Benefit: Reduces form submissions by answering questions instantly

Include Selectors​

  • Purpose: CSS selectors for textareas to include
  • Default: textarea[name='comment'],textarea[name='message'],textarea[name='nachricht']
  • Format: Comma-separated CSS selectors
  • Customization: Add your specific form field selectors

Exclude Selectors​

  • Purpose: CSS selectors for textareas to exclude
  • Default: .no-ai,.admin-area textarea,.internal-notes,[name='rating']
  • Use Case: Prevent AI from assisting with admin or sensitive fields

6. OpenAI Configuration​

User Input Maximum Length​

  • Purpose: Limit the length of user messages
  • Default: 400 characters
  • Range: 2-unlimited characters
  • Consideration: Longer messages cost more API credits

Search Results Limit​

  • Purpose: Maximum number of products returned in searches
  • Default: 8 products
  • Range: 1-50 products
  • Balance: More results = better coverage but higher API costs

Product Description Limits​

  • Detail View: Maximum 1500 characters (default)
  • Search Results: Maximum 500 characters (default)
  • Purpose: Reduce API token usage while maintaining quality

Category and Property Options​

  • Return Category IDs: Include category IDs in responses
  • Property IDs as Keys: Use property IDs as keys in responses
  • Purpose: Enhanced integration with custom implementations

7. Content Optimization​

Category Blacklist​

  • Purpose: Exclude specific categories from AI responses
  • Benefit: Reduce noise and improve response quality
  • Example: Exclude "Legal" or "Terms" categories

Category Level Filter​

  • Purpose: Set starting level for category breadcrumbs
  • Default: 0 (root level)
  • Use Case: Skip top-level categories like "Catalogue"

Manufacturer Filters​

  • Purpose: Exclude specific manufacturers from AI responses
  • Use Case: Hide discontinued or problematic brands

Property Group Management​

  • Blacklist: Exclude specific property groups
  • Whitelist: Include only specific property groups
  • Max Options: Limit properties per group (default: 20)
  • Impact: Significantly affects AI performance and costs

8. Appearance Settings​

Avatar Configuration​

  • Options: Female (default), Male, or Custom
  • Custom Avatar: Upload 240x240px transparent image
  • Format: PNG recommended for transparency

Loading Icons​

  • Chat Loading: Blue, Dark, Golden, Red, Green
  • Delete Loading: Red (default), Blue, Dark, Golden, Green
  • Purpose: Match your brand colors

Layout Options​

  • Scroll Button Position: Left or Right side
  • Purpose: Accommodate different layouts

Configuration Best Practices​

Security​

  • ✅ Never share your API key
  • ✅ Use environment variables for sensitive data
  • ✅ Regularly monitor API usage

Performance​

  • ✅ Use property whitelists instead of blacklists
  • ✅ Limit product description lengths
  • ✅ Set appropriate search result limits

User Experience​

  • ✅ Choose intuitive chatbot names
  • ✅ Provide clear FAQ content
  • ✅ Test all configurations before going live

Cost Management​

  • ✅ Monitor OpenAI usage regularly
  • ✅ Set appropriate input length limits
  • ✅ Optimize property and category filters

Testing Your Configuration​

  1. Save Configuration: Always save before testing
  2. Clear Cache: Run bin/console cache:clear
  3. Test API Connection: Use the built-in test button
  4. Frontend Testing: Verify chatbot appears and responds
  5. Feature Testing: Test all enabled features

Advanced Configuration Tips​

For Large Catalogs​

  • Use property whitelists aggressively
  • Increase category level filter
  • Consider manufacturer blacklists

For Multilingual Stores​

  • Configure FAQ data in multiple languages
  • Test chatbot responses in all languages
  • Consider language-specific instructions

For High-Traffic Stores​

  • Monitor API usage closely
  • Implement user authentication if needed
  • Consider response caching strategies

Next Steps: After configuration, explore the Features Overview to understand all capabilities.