About

The vf-chatbot-standalone component provides a full-screen conversational interface between a user and an AI system. It is typically accessed through a dedicated route or external site. Designed for more complex interactions, it supports extended dialogues, exploration of multiple topics, and access to documents or detailed support resources.

Usage

When to use this component

Only use the chatbot standalone if there's evidence it helps users:

• Engage in longer sessions or structured tasks such as report generation, data analysis, or learning journeys
• Focus in a distraction-free environment optimized for dialogue
• Interact with the bot as primary interface, rather than a secondary support layer
• Access rich responses such as cards, file previews, or dynamic visualizations

For example, the standalone chatbot works well when users need to complete complex workflows or explore content across multiple interactions. It is also effective when the conversation itself drives the experience, rather than supporting it. Test with users to ensure the dedicated interface supports their goals and provides clear value over embedded alternatives.

When not to use this component

The chatbot standalone opens in a dedicated interface and removes users from their current context. This can interrupt active tasks or create unnecessary friction for users who only need quick or simple guidance.

Avoid using the standalone chatbot for brief interactions, especially when users benefit from staying within the current page or task flow. A chatbot modal or embedded support is usually more appropriate in these cases.

Do not use the standalone chatbot when:

• The task can be resolved with a simple search or static content
• The chatbot does not offer a clear improvement over lighter support mechanisms
• Accessing the chatbot disrupts processes that require deep concentration or formal
• The chatbot lacks the intelligence or depth to sustain a meaningful experience
• The target audience expects or benefits more from traditional, structured interfaces

Test your design without a standalone chatbot first. Well-written content, embedded guidance, or contextual help may meet user needs more effectively without introducing unnecessary complexity.

Deciding between modal vs standalone

The chatbot modal and chatbot standalone are two distinct variants for delivering conversational interfaces. Choose between them based on use case needs and task complexity.

Modal

• For in-context support (e.g. help with current page or workflow)
• Access point is via a floating action button on the page
• Supports simple tasks such as getting information

Standalone

• Suitable for exploratory or focused workflows (e.g. discovering genetic variants)
• Launched via a link (such as "Talk to our AI chat assistant")
• Supports more complex tasks that benefit from sustained engagement

Anatomy

Element	Description
Title bar	Shows the chatbot name, minimise button and close button. The title bar may include a dropdown for selecting categories.
Dialogue section	Scrollable chat window showing the conversation log.
Intro message	A brief onboarding message explaining the purpose and capabilities of the chatbot. Shows the icon, title and short message (Max. 2 lines of text).
Banner	Used to show optional disclaimers or alerts (Max. 3 lines of text). For cases that require user consent, use a blur overlay on the background or a pre-access popup instead, as banners may be missed.
Text input area	Open input field for typing and sending queries. Expands up to 5 lines, after which it becomes scrollable.

Flows

Flow	Details
Suggested prompts	Appear on the initial screen. Provide a quick-start to users with clickable queries. They help to provide context on the type of questions the user can ask on the platform. (Max. 60 characters)
Closing the chat dialogue	Clicking on the close icon "X" triggers a confirmation prompt to prevent accidental loss of the chat log.
Error management	If the chatbot is unable to provide a response to the query, display a clear error message and provide an alternative way for them to get their answers.
Links	Displayed in a clear underlined style. They can be shown inline or as a list.
Source attribution	Chips are shown in relevant paragraphs which cite the sources. Links to the sources and more details can be accessed via a "View sources" button.
Feedback on a query level	Users can assess the AI responses with a thumbs up/thumbs down or optional close/open response fields to give more details.
Category selection	A dropdown in the title bar lets users switch focus areas (e.g LLM version or data source). Single or multi-selection variants can be used depending on the use case.

Working example

You can access working example of standalone version here: Visual Framework Chatbot - Standalone

Visual branding elements and content

The Chatbot branding elements follow EMBL brand guidelines but can be updated to suit your use case. For advice on branding updates please contact the EMBL Communications Team.

Texts shown in the examples are placeholder content. Please review and update all wording to fit your your project needs and ensure it meets legal, accessibility and organisational requirements.

Visual branding elements and content

The Chatbot branding elements follow EMBL brand guidelines but can be updated to suit your use case. For advice on branding updates please contact the EMBL Communications Team.

Texts shown in the examples are placeholder content. Please review and update all wording to fit your your project needs and ensure it meets legal, accessibility and organisational requirements.

Accessibility

The component targets WCAG 2.1 AA accessibility standard.

Installation

1yarn add @visual-framework/vf-chatbot-standalone @visual-framework/vf-chatbot-action-prompt @visual-framework/vf-chatbot-feedback @visual-framework/vf-chatbot-prompt @visual-framework/vf-chatbot-selector @visual-framework/vf-chatbot-sources @visual-framework/vf-chatbot-welcome

Sass/CSS

1@import "@visual-framework/vf-chatbot-standalone/index.scss";

JavaScript

1import { VFChatbotStandalone, initVFChatbotStandalone } from "@visual-framework/vf-chatbot-standalone";

Implementation

Basic Setup

1. JavaScript Initialization

1// Or with custom configuration
2const chatbotInstances = initVFChatbotStandalone(config);

where config is the configuration object with different options as described below

Core Configuration Options

1const config = {
2  // Basic Settings
3  title: "AI Assistant",
4  welcome_message: "Welcome! I'm here to help",
5  input_placeholder: "Ask me anything...",
6  welcome_max_suggestions: 4,
7  
8  // Content & Branding
9  disclaimer: 'Custom disclaimer with <a href="/privacy">privacy policy</a>',
10  footnote: 'Custom footnote with <a href="/feedback">feedback link</a>',
11  
12  // Icons & Assets
13  icons: {
14    assistant_avatar: "path/to/assistant-icon.svg",
15    user_avatar: "path/to/user-icon.svg",
16    send_button: "path/to/send-icon.svg",
17    main_logo_url: "path/to/logo.svg"
18  },
19  
20  // API Configuration
21  api: {
22    chat_endpoint: "/api/chat",
23    feedback_endpoint: "/api/feedback", 
24    qa_data_url: "path/to/qa-data.json",
25    headers: {
26      "Content-Type": "application/json",
27      "Authorization": "Bearer your-token"
28    },
29    timeout: 10000
30  },
31  
32  // Feature Toggles
33  features: {
34    enable_welcome: true,
35    enable_feedback: true,
36    enable_sources: true,
37    enable_welcome_suggestions: true,
38    enable_typing_indicator: true,
39    enable_disclaimer: true,
40    enable_predefined_qa: true,
41    enable_fallback_responses: true,
42    enable_qa_data_loading: true,
43    enable_instant_feedback: false
44  }
45};

Service Selector Configuration

The chatbot includes an integrated selector component which can be configured to present different selection options to user:

1const selectorConfig = {
2  selectorContext: {
3    chatbotRoutes: {
4      // Multi-selection settings
5      multiSelect: true,
6      maxMultiSelect: 3,
7      
8      // Search functionality
9      showSearch: true,
10      showSearchThreshold: 5,
11      
12      // "All Services" option
13      showAllServices: true,
14      showAllServicesSelected: true,
15      
16      // Data source
17      routes: "assets/vf-chatbot-selector-services.json",
18      
19      // UI labels
20      placeholder: "Select services",
21      title: "Available Services"
22    }
23  }
24};

Selector Data Format (JSON):

1{
2  "routes": [
3    {
4      "id": "service-1",
5      "title": "Service 1 title"
6    },
7    {
8      "id": "service-2", 
9      "title": "Service 2 title"
10    }
11  ]
12}

Event Handling

Built-in Event Handlers

Chatbot comes with a provision to allow custom event handlers. These handlers can be defined in your code to handle specific actions for different events triggered during interaction with chatbot. Configure custom handlers for chatbot events:

1const config = {
2  handlers: {
3    on_message_send: "handleMessageSend",
4    on_response_receive: "handleResponseReceive", 
5    on_feedback_submit: "handleFeedbackSubmit",
6    on_suggestion_click: "handleSuggestionClick",
7    on_error: "handleError",
8    on_conversation_start: "handleConversationStart",
9    on_conversation_end: "handleConversationEnd"
10  }
11};
12
13// Implement handler functions
14function handleMessageSend(message, conversationId) {
15  console.log('User sent:', message);
16  // Track analytics, log conversations, etc.
17}
18
19function handleResponseReceive(response, sources, prompts) {
20  console.log('Assistant responded:', response);
21  // Process response, update UI, etc.
22}
23
24function handleFeedbackSubmit(feedbackData) {
25  console.log('Feedback received:', feedbackData);
26  // Send to analytics, update models, etc.
27}

Custom Event Listeners

Likewise you can also listen to events emitted by the chatbot for specific interactions:

1// Listen for specific chatbot events
2document.addEventListener('vf-chatbot:message-send', (event) => {
3  const { message, conversationId } = event.detail;
4  // Handle message send
5});
6
7document.addEventListener('vf-chatbot:message-receive', (event) => {
8  const { message, conversationId } = event.detail;
9  // Handle message send
10});
11
12document.addEventListener('vf-chatbot-feedback:submit', (event) => {
13  const { messageId, feedbackType, feedbackText } = event.detail;
14  // Handle feedback submission
15});
16
17document.addEventListener('vf-chatbot-welcome:suggestion-click', (event) => {
18  const { question } = event.detail;
19  // Handle suggestion clicks
20});
21
22document.addEventListener('vf-chatbot:assistant-change', (obj) => {
23  const { selectedRoutes } = obj.selectedAssistants;
24  const { conversationId } = obj.conversationId;
25  // Handle service selection
26});
27
28document.addEventListener('vf-chatbot:error', (event) => {
29  const { message, conversationId } = event.detail;
30  // Handle message send
31});
32
33document.addEventListener('vf-chatbot:conversation-start', (event) => {
34  const { message, conversationId } = event.detail;
35  // Handle conversation start
36});
37
38document.addEventListener('vf-chatbot:conversation-end', (event) => {
39  const { message, conversationId } = event.detail;
40  // Handle conversation end
41});
42

Feedback System Configuration

Feedback (with form)

1const config = {
2  features: {
3    enable_feedback: true,
4    enable_instant_feedback: false // Default
5  }
6};

Instant Feedback (one-click)

1const config = {
2  features: {
3    enable_feedback: true,
4    enable_instant_feedback: true // Thumbs up/down only
5  }
6};

Q&A Data Configuration

Load predefined questions and answers:

1const config = {
2  features: {
3    enable_predefined_qa: true,
4    enable_qa_data_loading: true
5  },
6  api: {
7    qa_data_url: "path/to/qa-data.json"
8  }
9};

Q&A Data Format:

1{
2  "predefinedQA": {
3    "How can I submit genomic data to EMBL-EBI?": {
4      "answer": "To submit genomic data, visit the EMBL-EBI submission portal, where you’ll find step-by-step guides and tools for submitting sequencing data, assemblies, annotations, and more.",
5      "sources": [
6        {
7          "domain": "ebi.ac.uk",
8          "title": "EMBL's European Bioinformatics Institute",
9          "url": "https://www.ebi.ac.uk/",
10          "description": "Run BLAST searches against comprehensive sequence databases at EMBL-EBI."
11        },
12        {
13          "domain": "ena-docs.readthedocs.io",
14          "title": "ENA Documentation",
15          "url": "https://ena-docs.readthedocs.io/en/latest/",
16          "description": "ENA Documentation"
17        }
18      ]
19    }
20  },
21  "fallbackResponses": [
22    {
23      "answer": "I'm sorry, I'm having trouble connecting to my knowledge base right now. Could you try again in a moment?",
24      "prompts": [
25        {
26          "action_text": "Contact support team",
27          "action_url": "tel:+44 1223 494 444"
28        },
29        {
30          "action_text": "Submit a support request",
31          "action_url": "https://www.ebi.ac.uk/about/contact/support/"
32        }
33      ]
34    }
35  ]
36}

API Integration

Chat Endpoint

Your chat API should accept POST requests:

1// Request format
2{
3  "message": "User's question",
4  "conversationId": "unique-id",
5  "context": {
6    "selectedServices": ["service-1", "service-2"]
7  }
8}
9
10// Response format
11{
12  "response": "Assistant's answer",
13  "sources": [
14    {
15      "title": "Documentation Link",
16      "url": "https://example.com/docs"
17    }
18  ],
19  "prompts": [
20    {
21      "action_text": "Learn More",
22      "action_url": "https://example.com/learn"
23    }
24  ]
25}

Custom Welcome Screen

1const config = {
2  features: {
3    enable_welcome: true,
4    enable_welcome_suggestions: true
5  },
6  welcome_logo: true,
7  welcome_message: "Welcome to our AI assistant!",
8  welcome_suggestions_title: "Popular questions:",
9  welcome_max_suggestions: 6
10};

Source Citations

1const config = {
2  features: {
3    enable_sources: true
4  }
5};
6
7// Sources in API response
8{
9  "response": "Here's the information...",
10  "sources": [
11    {
12      "title": "Official Documentation", 
13      "url": "https://docs.example.com",
14      "description": "Complete guide to the platform"
15    }
16  ]
17}

Action Prompts

1// Action prompts in API response
2{
3  "response": "I can help you with that...",
4  "prompts": [
5    {
6      "action_text": "Start Tutorial",
7      "action_url": "https://example.com/tutorial"
8    },
9    {
10      "action_text": "Contact Support", 
11      "action_url": "mailto:support@example.com"
12    }
13  ]
14}

Instance Management

1// Get chatbot configuration
2const config = chatbotInstance.getConfiguration();
3
4// Destroy instance
5chatbotInstance.destroy();

React Integration

The HTML template can be adapted for React applications. See the React syntax section below for implementation details on using the HTML template for the chatbot in JSX components.

Help

• Read the Visual Framework troubleshooting
• Open a ticket
• Chat on Slack