Forms and Services Functionality - Comprehensive Documentation

Table of Contents

1. Overview
2. Architecture
3. Setup and Configuration
4. Technical Requirements
5. Workflow
6. Early Detection System
7. API Integration
8. Frontend Integration
9. Configuration Examples
10. Troubleshooting

---

Overview

The Forms and Services functionality enables the chatbot to:

• List available forms when users request to see what forms are available
• Email forms to users when they request a specific form
• List available services when users want to see what services can be requested
• Process service requests by sending notifications to administrators

This system transforms the chatbot from a simple Q&A tool into a complete customer service solution that can handle actionable requests.

Key Features

• Early Detection: Pattern-based detection intercepts form/service requests before LLM processing
• Multi-language Support: Supports English, Farsi, Arabic, French, Spanish, German, and Turkish
• Domain-specific Configuration: Each domain can have its own forms and services
• Automatic Email Delivery: Forms can be automatically emailed to users
• Service Request Notifications: Service requests trigger email notifications to administrators
• Frontend Integration: Structured responses enable rich UI components (clickable buttons, lists)

---

Architecture

System Components

┌─────────────────────────────────────────────────────────────┐
│                    User Query                                │
│              "show available forms"                          │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│           Intent Detection Preprocessor                        │
│  - Pattern matching for common form/service requests         │
│  - Tool identification                                     │
└────────────────────┬────────────────────────────────────────┘
                     │
         ┌───────────┴───────────┐
         │                       │
         ▼                       ▼
┌──────────────────┐   ┌──────────────────┐
│  Special Tool    │   │  Normal LLM Flow │
│  Detected        │   │  (if no match)    │
└────────┬─────────┘   └──────────────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────────┐
│           Handler Functions                                  │
│  - list_forms_handler()                                      │
│  - email_form_handler()                                      │
│  - list_services_handler()                                   │
│  - request_service_handler()                                 │
└────────────────────┬────────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────────┐
│           Manager Classes                                    │
│  - FormManager (loads forms.json)                           │
│  - ServiceManager (loads services.json)                      │
└────────────────────┬────────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────────┐
│           Response with Structured Data                      │
│  - message_type: "forms_list" | "services_list"            │
│  - clickableForms: [...]                                    │
│  - clickableServices: [...]                                 │
└────────────────────┬────────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────────┐
│           Frontend (Flutter App)                             │
│  - FormsListWidget                                           │
│  - ServicesListWidget                                        │
└─────────────────────────────────────────────────────────────┘

Components

The system is organized around these responsibilities:

Component	Role
Intent detection	Identifies common form and service requests before full LLM processing
Form manager	Loads and serves form definitions from per-domain forms.json
Service manager	Loads and serves service definitions from per-domain services.json
Handlers	Execute list-forms, email-form, list-services, and request-service actions
API layer	Exposes query endpoints and returns structured responses for the client
Client (Flutter)	Renders clickable form and service lists from structured API responses

Per-domain configuration lives under your domain folder:

{domain_folder}/
├── forms/
│   └── forms.json
└── services/
    └── services.json

---

Setup and Configuration

Prerequisites

1. Domain Folder Structure: Each domain must have a folder structure:

   {SEARCH_DOMAIN_FOLDER}/{domain_name}/
   ├── forms/
   │   └── forms.json
   └── services/
       └── services.json

2. Environment Variable: Ensure EARLY_DETECTION=true in your .env file:

   EARLY_DETECTION=true

3. Domain Path: The SEARCH_DOMAIN_FOLDER setting must point to your domains directory.

Forms Configuration (forms.json)

Location: {SEARCH_DOMAIN_FOLDER}/{domain_name}/forms/forms.json

Structure

{
  "forms": {
    "{form_type}": {
      "name": {
        "en": "English Name",
        "fa": "نام فارسی",
        "ar": "الاسم العربي",
        "fr": "Nom français",
        "es": "Nombre español",
        "de": "Deutscher Name",
        "tr": "Türkçe ad"
      },
      "url": "https://example.com/forms/{form_type}",
      "keywords": {
        "en": ["keyword1", "keyword2", "keyword3"],
        "fa": ["کلمه کلیدی 1", "کلمه کلیدی 2"],
        "ar": ["كلمة مفتاحية 1", "كلمة مفتاحية 2"],
        "fr": ["mot-clé 1", "mot-clé 2"],
        "es": ["palabra clave 1", "palabra clave 2"],
        "de": ["Schlüsselwort 1", "Schlüsselwort 2"],
        "tr": ["anahtar kelime 1", "anahtar kelime 2"]
      },
      "email_template": {
        "subject": {
          "en": "{form_name} - {domain_title}",
          "fa": "{form_name} - {domain_title}"
        },
        "body": {
          "en": "Dear {user_name},\n\nThank you for your request...",
          "fa": "عزیز {user_name}،\n\nاز درخواست شما متشکرم..."
        }
      },
      "active": true
    }
  },
  "metadata": {
    "version": "1.0",
    "last_updated": "2024-01-25",
    "domain": "{domain_name}",
    "supported_languages": ["en", "fa", "ar", "fr", "es", "de", "tr"]
  }
}

Field Descriptions

Form Object:

• name (object, required): Localized form names for each language
• url (string, required): URL to the form (must start with http:// or https://)
• keywords (object, required): Keywords for form detection, organized by language
• email_template (object, optional): Email template for sending forms
  • subject: Email subject template (supports {form_name}, {domain_title})
  • body: Email body template (supports {user_name}, {form_name}, {form_url}, {domain_title})
• active (boolean, required): Whether the form is currently available

Metadata:

• version (string): Configuration version
• last_updated (string): Last update date
• domain (string): Domain name
• supported_languages (array): List of supported language codes

Services Configuration (services.json)

Location: {SEARCH_DOMAIN_FOLDER}/{domain_name}/services/services.json

Structure

{
  "services": {
    "{service_id}": {
      "id": "{service_id}",
      "name": {
        "en": "English Service Name",
        "fa": "نام سرویس فارسی"
      },
      "description": {
        "en": "Service description in English",
        "fa": "توضیحات سرویس به فارسی"
      },
      "icon": "🧻",
      "category": "room_amenities",
      "active": true
    }
  },
  "metadata": {
    "version": "1.0",
    "detection_keywords": {
      "en": "room service",
      "fa": "سرویس اتاق"
    },
    "confirmation_message": {
      "en": "Your request for {service_name} has been sent to our team. Someone will assist you shortly.",
      "fa": "درخواست شما برای {service_name} به تیم ما ارسال شد. به زودی کسی به شما کمک خواهد کرد."
    },
    "supported_languages": ["en", "fa"]
  }
}

Field Descriptions

Service Object:

• id (string, required): Unique service identifier
• name (object, required): Localized service names
• description (object, optional): Localized service descriptions
• icon (string, optional): Emoji or icon identifier for the service
• category (string, optional): Service category (e.g., "room_amenities", "food_beverage")
• active (boolean, required): Whether the service is currently available

Metadata:

• version (string): Configuration version
• detection_keywords (object, required): Keywords for detecting service requests (one string per language, NOT arrays)
• confirmation_message (object, required): Message shown after service request (supports {service_name} placeholder)
• supported_languages (array): List of supported language codes

---

Technical Requirements

Backend Requirements

1. Python 3.11+

2. Dependencies:

   • FastAPI
   • Pydantic (for request/response models)
   • Email sending capability (SMTP configuration)

3. Settings:

   EARLY_DETECTION=true  # Enable early detection
   SEARCH_DOMAIN_FOLDER=/path/to/domains  # Domain folder path

4. Email Configuration (for form emailing):

   SMTP_HOST=smtp.example.com
   SMTP_PORT=587
   SMTP_USER=your-email@example.com
   SMTP_PASSWORD=your-password
   SMTP_FROM=noreply@example.com

Frontend Requirements

1. Flutter/Dart (for aventora-bot)
2. WebSocket Support (for real-time communication)
3. JSON Parsing (for structured messages)

Database Requirements

• PostgreSQL (for storing chat logs and form submissions)
• Tables:
  • chat_logs: Stores conversation history
  • form_submissions: Stores form request logs (if implemented)
  • service_requests: Stores service request logs (if implemented)

---

Workflow

1. List Forms Workflow

User Query: "show available forms"
    │
    ▼
Early Detection (ComprehensivePatternDetection)
    │
    ├─ Pattern Match: LIST_FORMS detected
    │
    ▼
list_forms_handler()
    │
    ├─ FormManager.load_domain_forms(domain)
    │   └─ Loads forms.json from disk
    │
    ├─ FormManager.get_available_forms(domain)
    │   └─ Filters active forms
    │
    ├─ For each form:
    │   └─ FormManager.get_form_info(domain, form_type, language)
    │       └─ Returns localized name and URL
    │
    ▼
Response:
{
  "answer": "Here are the available forms:\n1. Employment Form\n2. Contact Form",
  "message_type": "forms_list",
  "clickableForms": [
    {"type": "employment", "name": "Employment Form", "url": "https://..."},
    {"type": "contact", "name": "Contact Form", "url": "https://..."}
  ],
  "complete": true,
  "continue": false
}
    │
    ▼
WebSocket Handler
    │
    ├─ Adds message_type and clickableForms to message_data
    │
    ▼
Frontend (Flutter)
    │
    ├─ Parses ASSISTANT_STRUCTURED message
    │
    ├─ Detects messageType == "forms_list"
    │
    ▼
FormsListWidget
    │
    └─ Displays clickable form buttons

2. Email Form Workflow

User Query: "send me the employment form"
    │
    ▼
Early Detection
    │
    ├─ Pattern Match: EMAIL_FORM detected
    │
    ▼
email_form_handler()
    │
    ├─ FormManager.detect_form_type_from_query()
    │   └─ Matches keywords: "employment" → "employment"
    │
    ├─ FormManager.get_form_info(domain, "employment", language)
    │   └─ Returns form name and URL
    │
    ▼
Response:
{
  "answer": "I can send you the Employment Application Form. Please confirm your email address.",
  "message_type": "form_request",
  "formData": {
    "form_type": "employment",
    "form_name": "Employment Application Form",
    "form_url": "https://...",
    "form_id": "employment"
  },
  "complete": false,
  "continue": true,
  "action_needed": "confirm_email_send"
}
    │
    ▼
Frontend
    │
    ├─ Displays form request UI
    │
    ├─ User confirms email
    │
    ▼
POST /query/send-form-email
    │
    ├─ send_form_email_handler()
    │   └─ Sends email using email_template
    │
    ▼
Confirmation message sent to user

3. List Services Workflow

User Query: "what services are available?"
    │
    ▼
Early Detection
    │
    ├─ Pattern Match: REQUEST_SERVICE detected (or LIST_FORMS pattern)
    │
    ▼
list_services_handler()
    │
    ├─ ServiceManager.load_domain_services(domain)
    │   └─ Loads services.json from disk
    │
    ├─ ServiceManager.get_available_services(domain, language)
    │   └─ Filters active services, localizes names
    │
    ▼
Response:
{
  "answer": "Here are the available services:",
  "message_type": "services_list",
  "clickableServices": [
    {"id": "towels", "name": "Extra Towels", "description": "...", "icon": "🧻"},
    {"id": "water", "name": "Drinking Water", "description": "...", "icon": "💧"}
  ],
  "complete": true,
  "continue": false
}
    │
    ▼
Frontend
    │
    └─ ServicesListWidget displays service buttons

4. Request Service Workflow

User clicks service button: "towels"
    │
    ▼
Frontend sends: "I want to request towels service"
    │
    ▼
Early Detection
    │
    ├─ Pattern Match: REQUEST_SERVICE detected
    │
    ▼
request_service_handler()
    │
    ├─ ServiceManager.get_service_info(domain, "towels", language)
    │   └─ Returns service details
    │
    ├─ Email notification sent to admin
    │   └─ Includes user name, email, service name
    │
    ▼
Response:
{
  "answer": "Your request for Extra Towels has been sent to our team. Someone will assist you shortly.",
  "complete": true,
  "continue": false
}

---

Early Detection System

Overview

Intent detection uses pattern matching to identify common form and service requests before the query reaches the full LLM pipeline. This provides:

• Fast response for routine requests (list forms, email a form, request a service)
• Consistent behavior for well-defined intents
• Lower cost by avoiding unnecessary LLM calls for common actions

How It Works

1. User message is checked against language-specific intent patterns
2. If a supported intent is detected with sufficient confidence, the request is routed to the appropriate handler
3. If no intent matches, the message continues through the normal conversational LLM flow

Supported Intents

Intent	User goal
List forms	See which forms are available
Email form	Receive a specific form by email
List services	See which services can be requested
Request service	Submit a service request to your team
Email transcript	Receive a copy of the conversation

Configuration

Enable or disable intent detection in your Domain Assistant environment configuration:

EARLY_DETECTION=true   # Enable (recommended for forms/services deployments)
EARLY_DETECTION=false  # Disable — all requests go through the full LLM flow

Custom intent patterns and terminology are configured per domain. Contact your Aventora administrator or support for domain-specific tuning.

---

API Integration

Endpoints

1. Query Endpoint (with Early Detection)

POST /query/

{
  "question": "show available forms",
  "domain": "kalano",
  "language": "en",
  "name": "John Doe",
  "email": "john@example.com",
  "user_id": 123,
  "domain_metadata": {}
}

Response (Forms List):

{
  "answer": "Here are the available forms:\n1. Employment Application Form\n2. Contact Form",
  "message_type": "forms_list",
  "clickableForms": [
    {
      "type": "employment",
      "name": "Employment Application Form",
      "url": "https://kalano.com/forms/employment"
    },
    {
      "type": "contact",
      "name": "Contact Form",
      "url": "https://kalano.com/forms/contact"
    }
  ],
  "complete": true,
  "continue": false,
  "session": [...]
}

Response (Form Request):

{
  "answer": "I can send you the Employment Application Form. Please confirm your email address.",
  "message_type": "form_request",
  "formData": {
    "form_type": "employment",
    "form_name": "Employment Application Form",
    "form_url": "https://kalano.com/forms/employment",
    "form_id": "employment"
  },
  "complete": false,
  "continue": true,
  "session": [...]
}

2. Send Form Email Endpoint

POST /query/send-form-email

{
  "form_id": "employment",
  "user_email": "john@example.com",
  "user_name": "John Doe",
  "language": "en",
  "domain": "kalano"
}

Response:

{
  "message": "The Employment Application Form has been sent to your email.",
  "success": true
}

3. Request Service Endpoint

POST /query/request-service

{
  "service_id": "towels",
  "user_name": "John Doe",
  "user_email": "john@example.com",
  "language": "en",
  "domain": "kalano"
}

Response:

{
  "message": "Your request for Extra Towels has been sent to our team. Someone will assist you shortly.",
  "success": true
}

WebSocket Integration

The WebSocket handler (Agent/server/websocket.py) processes responses and adds structured data:

if resp.get("message_type") == "forms_list":
    message_data["message_type"] = resp.get("message_type")
    message_data["clickableForms"] = resp.get("clickableForms")

if resp.get("message_type") == "services_list":
    message_data["message_type"] = resp.get("message_type")
    message_data["clickableServices"] = resp.get("clickableServices")

---

Frontend Integration

Flutter Integration (aventora-bot)

1. Message Parsing

The ChatScreenD widget parses structured messages:

if (value.startsWith('ASSISTANT_STRUCTURED:')) {
  final structuredData = value.substring(21);
  final messageData = jsonDecode(structuredData);
  
  final messageType = messageData['messageType'];
  final clickableForms = messageData['clickableForms'];
  final clickableServices = messageData['clickableServices'];
  
  _addMessageToChat(
    messageId,
    assistantText,
    'assistant',
    null,
    nowMs,
    messageType: messageType,
    clickableForms: clickableForms,
    clickableServices: clickableServices,
  );
}

2. Forms List Widget

FormsListWidget displays clickable form buttons:

if (widget.message.messageType?.toLowerCase() == 'forms_list' && 
    widget.message.clickableForms != null) {
  return FormsListWidget(
    forms: widget.message.clickableForms!,
    onFormSelected: widget.onUserResponse,
    isRTL: widget.isRTL,
  );
}

3. Services List Widget

ServicesListWidget displays clickable service buttons:

if (widget.message.messageType?.toLowerCase() == 'services_list' && 
    widget.message.clickableServices != null) {
  return ServicesListWidget(
    services: widget.message.clickableServices!,
    onServiceRequested: widget.onUserResponse,
    isRTL: widget.isRTL,
  );
}

4. Trigger Phrases

The "View Forms" button sends a trigger phrase:

void _onFormsButtonPressed() {
  String triggerPhrase;
  switch (currentLanguage) {
    case 'fa':
      triggerPhrase = 'لیست فرم‌ها را نشان بده';
      break;
    case 'ar':
      triggerPhrase = 'أظهر قائمة النماذج';
      break;
    default:
      triggerPhrase = 'show available forms';
  }
  _sendMessage(triggerPhrase);
}

Message Format

Structured Message Format:

ASSISTANT_STRUCTURED:{"text":"...","messageType":"forms_list","clickableForms":[...]}

Fields:

• text: Human-readable message text
• messageType: "forms_list" | "services_list" | "form_request" | "admin_call_form" | null
• clickableForms: Array of form objects (if messageType == "forms_list")
• clickableServices: Array of service objects (if messageType == "services_list")
• formData: Form request data (if messageType == "form_request")
• adminCallFormData: Inline form for "talk to admin" (if messageType == "admin_call_form")

Admin Call Form (messageType == "admin_call_form")

When the user says "talk to admin" / "can I speak with an administrator", the backend returns messageType: "admin_call_form" and adminCallFormData with an inline form (no regex parsing). The frontend should render the form and, on submit, send a continue request with:

• admin_call_name: from field id: "name"
• admin_call_phone: from field id: "phone"
• admin_call_subject: from field id: "subject"
• admin_call_preferred_channel: one of "sms" | "wmsg" | "phone" from field id: "preferred_channel"

adminCallFormData shape:

• intro: string (optional message)
• fields: [{ id, type, label, required, value?, options? }] — id is "name" | "phone" | "subject" | "preferred_channel"; preferred_channel has options: [{ value: "sms"|"wmsg"|"phone", label }]
• submit_label: string for the submit button

---

Configuration Examples

Example 1: Healthcare Domain Forms

{
  "forms": {
    "patient_intake": {
      "name": {
        "en": "Patient Intake Form",
        "fa": "فرم پذیرش بیمار"
      },
      "url": "https://hospital.example.com/forms/patient-intake",
      "keywords": {
        "en": ["intake", "patient form", "registration", "admission"],
        "fa": ["پذیرش", "فرم بیمار", "ثبت نام", "بستری"]
      },
      "email_template": {
        "subject": {
          "en": "Patient Intake Form - {domain_title}",
          "fa": "فرم پذیرش بیمار - {domain_title}"
        },
        "body": {
          "en": "Dear {user_name},\n\nPlease complete the Patient Intake Form at:\n{form_url}\n\nThank you.",
          "fa": "عزیز {user_name}،\n\nلطفاً فرم پذیرش بیمار را در لینک زیر تکمیل کنید:\n{form_url}\n\nمتشکرم."
        }
      },
      "active": true
    },
    "appointment": {
      "name": {
        "en": "Appointment Booking Form",
        "fa": "فرم رزرو نوبت"
      },
      "url": "https://hospital.example.com/forms/appointment",
      "keywords": {
        "en": ["appointment", "booking", "schedule", "visit"],
        "fa": ["نوبت", "رزرو", "وقت", "ویزیت"]
      },
      "active": true
    }
  },
  "metadata": {
    "version": "1.0",
    "domain": "hospital",
    "supported_languages": ["en", "fa"]
  }
}

Example 2: Hotel Domain Services

{
  "services": {
    "room_service": {
      "id": "room_service",
      "name": {
        "en": "Room Service",
        "fa": "سرویس اتاق"
      },
      "description": {
        "en": "Order food and beverages to your room",
        "fa": "سفارش غذا و نوشیدنی به اتاق شما"
      },
      "icon": "🍽️",
      "category": "food_beverage",
      "active": true
    },
    "laundry": {
      "id": "laundry",
      "name": {
        "en": "Laundry Service",
        "fa": "خدمات لباسشویی"
      },
      "description": {
        "en": "Request laundry and dry cleaning services",
        "fa": "درخواست خدمات لباسشویی و خشک‌شویی"
      },
      "icon": "👔",
      "category": "housekeeping",
      "active": true
    }
  },
  "metadata": {
    "version": "1.0",
    "detection_keywords": {
      "en": "room service",
      "fa": "سرویس اتاق"
    },
    "confirmation_message": {
      "en": "Your request has been sent to our team. We'll assist you shortly.",
      "fa": "درخواست شما به تیم ما ارسال شد. به زودی به شما کمک خواهیم کرد."
    },
    "supported_languages": ["en", "fa"]
  }
}

---

Troubleshooting

Issue: Intent Detection Not Triggering

Symptoms:

• User query "show available forms" goes to LLM instead of handler
• Expected structured responses (forms_list, services_list) not returned

Solutions:

1. Check environment variable:

   EARLY_DETECTION=true

2. Verify domain configuration — ensure forms.json and services.json exist for the domain
3. Test phrasing — try explicit phrases such as "show available forms" or "send me the employment form"
4. Language — confirm the request language matches configured patterns for that domain

Issue: Forms Not Loading

Symptoms:

• Error: "Forms file not found"
• Empty forms list returned

Solutions:

1. Check File Path:

   {SEARCH_DOMAIN_FOLDER}/{domain_name}/forms/forms.json

2. Verify JSON Structure:

   • Validate JSON syntax
   • Ensure forms and metadata keys exist
   • Check required fields: name, url, keywords, active

3. Check Permissions:

   • Ensure file is readable
   • Check file encoding (must be UTF-8)

4. Clear cache: Restart the Domain Assistant service or contact your administrator to refresh the forms cache for the domain.

Issue: Services Not Loading

Symptoms:

• Error: "Services file not found"
• Empty services list returned

Solutions:

1. Check File Path:

   {SEARCH_DOMAIN_FOLDER}/{domain_name}/services/services.json

2. Verify JSON Structure:

   • Validate JSON syntax
   • Ensure services and metadata keys exist
   • Check detection_keywords is a dictionary (not array)

3. Validate Detection Keywords:

   // ✅ Correct
   "detection_keywords": {
     "en": "room service",
     "fa": "سرویس اتاق"
   }
   
   // ❌ Wrong (arrays not supported)
   "detection_keywords": {
     "en": ["room", "service"],
     "fa": ["سرویس", "اتاق"]
   }

Issue: Frontend Not Displaying Forms/Services

Symptoms:

• Backend returns clickableForms but frontend shows plain text

Solutions:

1. Check Message Type:

   • Verify message_type is set in response
   • Check WebSocket handler adds messageType to message_data

2. Verify Frontend Parsing:

   • Check ASSISTANT_STRUCTURED: prefix is present
   • Verify JSON parsing in ChatScreenD
   • Check messageType comparison (case-insensitive)

3. Check Widget Conditions:

   // Ensure both conditions are met
   messageType?.toLowerCase() == 'forms_list' &&
   clickableForms != null

4. Debug Logging:

   print('DEBUG: messageType=$messageType');
   print('DEBUG: clickableForms=$clickableForms');

Issue: Email Not Sending

Symptoms:

• Form request succeeds but email not received

Solutions:

1. Check SMTP Configuration:

   SMTP_HOST=smtp.example.com
   SMTP_PORT=587
   SMTP_USER=your-email@example.com
   SMTP_PASSWORD=your-password
   SMTP_FROM=noreply@example.com

2. Verify Email Template:

   • Check email_template exists in forms.json
   • Verify placeholders: {user_name}, {form_name}, {form_url}, {domain_title}

3. Check Logs:

   • Look for email sending errors
   • Verify email address format

Issue: Pattern Not Matching

Symptoms:

• Query should match pattern but doesn't

Solutions:

1. Test Pattern Manually:

   import re
   pattern = r"(show|list|tell me).*(forms|documents|papers)"
   query = "show available forms"
   match = re.search(pattern, query, re.IGNORECASE)
   print(match)  # Should not be None

2. Check Case Sensitivity:

   • Patterns use re.IGNORECASE flag
   • But verify query is lowercased in detection

3. Add Debug Logging:

   logger.info(f"Testing pattern: {pattern}")
   logger.info(f"Against query: {query}")
   logger.info(f"Match result: {match}")

4. Consider Variations:

   • Add more patterns for common phrasings
   • Test with typos and variations

Common Configuration Errors

1. Missing Required Fields:

   // ❌ Missing "active" field
   {
     "name": {...},
     "url": "...",
     "keywords": {...}
   }
   
   // ✅ Correct
   {
     "name": {...},
     "url": "...",
     "keywords": {...},
     "active": true
   }

2. Invalid URL Format:

   // ❌ Missing http://
   "url": "example.com/forms/employment"
   
   // ✅ Correct
   "url": "https://example.com/forms/employment"

3. Wrong Detection Keywords Format:

   // ❌ Array instead of string
   "detection_keywords": {
     "en": ["room", "service"]
   }
   
   // ✅ Correct
   "detection_keywords": {
     "en": "room service"
   }

---

Best Practices

Forms Configuration

1. Use Descriptive Keywords:

   • Include common variations and synonyms
   • Add both full form names and abbreviations
   • Consider typos and common misspellings

2. Localize Thoroughly:

   • Provide translations for all supported languages
   • Use native speakers for translations
   • Test with native speakers

3. Keep URLs Updated:

   • Use absolute URLs (https://)
   • Test URLs regularly
   • Provide fallback URLs if needed

Services Configuration

1. Clear Service Names:

   • Use descriptive, user-friendly names
   • Keep names concise
   • Avoid technical jargon

2. Helpful Descriptions:

   • Explain what the service does
   • Include any prerequisites or requirements
   • Set user expectations

3. Appropriate Categories:

   • Group related services
   • Use consistent category names
   • Consider UI grouping

Pattern Design

1. Start Broad, Then Narrow:

   • Begin with general patterns
   • Add specific patterns for edge cases
   • Test with real user queries

2. Avoid Over-Matching:

   • Be specific enough to avoid false positives
   • Test patterns with unrelated queries
   • Monitor false positive rates

3. Document Patterns:

   • Comment complex patterns
   • Explain why patterns are needed
   • Keep pattern database organized

Performance

1. Cache Management:

   • Forms and services are cached in memory
   • Clear cache after configuration changes
   • Monitor cache size for large domains

2. Early Detection First:

   • Always enable early detection for cost savings
   • Monitor detection accuracy
   • Adjust patterns based on metrics

3. Error Handling:

   • Gracefully handle missing files
   • Provide fallback messages
   • Log errors for debugging

---

Conclusion

The Forms and Services functionality provides a powerful way to extend the chatbot beyond simple Q&A. By following this documentation, you can:

• Configure forms and services for your domain
• Understand the complete workflow from user query to response
• Troubleshoot common issues
• Extend the system with new patterns and handlers

For additional support, refer to:

• domain-chatbot/docs/Technical-documentation.md - General technical documentation
• domain-chatbot/docs/Features.md - Feature overview
• domain-chatbot/docs/APIs.md - API documentation