scriptertech/zammad-ai-chatbot repository overview

⁠Zammad AI Chatbot Middleware & Floating Widget

An enterprise-ready, truly agentic conversational AI support platform for Zammad Helpdesk. Powered by any OpenAI-Compatible LLM Gateway (vLLM, Ollama, LiteLLM, OpenAI, Bifrost, LM Studio) running models, SQLite FTS5 hybrid retrieval, and packed with an embeddable customer-facing chat widget and full-featured RBAC Admin Control Center.

⁠🌟 Key Features

• 🤖 Autonomous Tool Calling (OpenAI compatible): Dynamically inspects tickets, creates escalation tickets in Zammad, appends customer logs, searches internal documentation, or searches the web when grounded context is insufficient.
• 📎 In-Chat Document Ingestion: Customers can upload error logs, system specs, or documents (.pdf, .docx, .txt, .md, .csv, .json, images, cumulative 5MB) directly inside chat for real-time AI analysis.
• 📚 Grounded Knowledge Base & 2-Way Sync: SQLite FTS5 BM25 search combined with dense vector embeddings. Bi-directionally syncs articles between Zammad Helpdesk and the chatbot index.
• 🛡️ Zero-Token Guardrails & Scope Shield: Fast pre-flight regex and keyword interception blocks out-of-scope prompts (coding, math, creative fiction) without burning LLM tokens.
• 🔐 Ticket Creation Access Policies & Account Protection: Configure widget access to Smart Account Protection (guests/leads submit freely; existing customer emails require password login to prevent impersonation), Members Only (strict verified customer login), or Open to Anyone.
• 🔀 Multi-Department Ticket Routing: Intelligently classifies customer inquiries and routes escalation tickets to designated Zammad groups (Technical Support, Billing, Sales).
• 🌐 Standalone Web Portal & In-Widget Portal Linking: Dual experience: full-featured Open-WebUI inspired web chat (/) with off-canvas responsive mobile drawer, plus an embeddable floating widget (/static/widget.js) with one-click shortcut (↗) to jump directly to the web portal.
• 💬 Embeddable Floating Chat Widget & Live Studio: Pure Vanilla JS/CSS widget with HTTP/2 SSE typewriter streaming, custom color theming, and a live WYSIWYG studio in /admin with custom geometry and vertical/horizontal edge offsets.
• 🎛️ Enterprise RBAC Admin Center (/admin): Minimalist single-page management console for prompt tuning, guardrail simulation, knowledge management, and user roles.

⁠🚀 Quick Start with Docker

⁠1. One-Line Run

docker run -d \
  --name zammad-ai-chatbot \
  -p 8000:8000 \
  -v zammad-ai-data:/data \
  -e BOT_NAME="Zammad AI" \
  -e OPENAI_URL="https://llm-gateway.yourdomain.com/v1" \
  -e OPENAI_API_KEY="your-llm-api-key" \
  -e OPENAI_MODEL="google/gemma-4" \
  -e ZAMMAD_URL="https://zammad.yourdomain.com" \
  -e ZAMMAD_API_TOKEN="your-zammad-api-token" \
  -e ZAMMAD_DEFAULT_GROUP="Users" \
  -e INITIAL_ADMIN_USERNAME="admin" \
  scriptertech/zammad-ai-chatbot:latest

⁠2. Docker Compose

Create a docker-compose.yml:

services:
  zammad-ai-chatbot:
    image: scriptertech/zammad-ai-chatbot:latest
    container_name: zammad-ai-chatbot
    restart: unless-stopped
    ports:
      - "8000:8000"
    environment:
      - BOT_NAME=Zammad AI
      # Any OpenAI-compatible gateway (vLLM, Ollama, LiteLLM, OpenAI, Bifrost, LM Studio)
      - OPENAI_URL=https://llm-gateway.yourdomain.com/v1
      - OPENAI_API_KEY=your-llm-api-key
      - OPENAI_MODEL=google/gemma-4
      - OPENAI_EMBEDDING_MODEL=voyageai/voyage-4-nano
      - OPENAI_VERIFY_SSL=true
      - ZAMMAD_URL=https://zammad.yourdomain.com
      - ZAMMAD_API_TOKEN=your-zammad-api-token
      - ZAMMAD_DEFAULT_GROUP=Users
      - ZAMMAD_KB_ENABLED=true
      - ZAMMAD_VERIFY_SSL=true
      - INITIAL_ADMIN_USERNAME=admin
      # Leave blank to auto-generate a secure random 14-char password printed in logs
      - INITIAL_ADMIN_PASSWORD=
    volumes:
      - chatbot-data:/data
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/healthz')"]
      interval: 15s
      timeout: 5s
      retries: 3

volumes:
  chatbot-data:

Launch the container:

docker compose up -d

⁠🔐 First Login & Admin Setup

1. Check your container startup logs to retrieve the auto-generated initial admin password:

   docker logs zammad-ai-chatbot | grep -A 4 "\[BOOTSTRAP\]"
   

   Copy
2. Open your browser and navigate to:

   http://localhost:8000/admin
   

   Copy
3. Log in with:
   • Username: admin (or your configured INITIAL_ADMIN_USERNAME)
   • Password: retrieved from the startup log (or your INITIAL_ADMIN_PASSWORD)
4. From /admin, you can manage department routing, upload knowledge base documents, configure allowed/forbidden topics, and customize your embeddable widget.

⁠⚙️ Environment Variables Reference

⁠💻 1-Line Embed Code for Websites

Paste this script tag before the closing </body> tag on any website, documentation portal, or customer dashboard:

<script 
  src="https://your-chatbot-domain.com/static/widget.js" 
  data-api-url="https://your-chatbot-domain.com" 
  data-bot-name="Zammad AI" 
  data-primary-color="#1c2430" 
  data-greeting="Hi! How can I help you today?" 
  data-position="right" 
  defer>
</script>

⁠Widget Attributes:

• data-api-url: Base URL where this container is hosted.
• data-bot-name: Title displayed in the chat header.
• data-primary-color: Hex color theme for header and action buttons (e.g. #1c2430, #3898ec, #10b981).
• data-greeting: Initial message shown to visitors.
• data-position: Position of the floating launcher button (right or left).

⁠☸️ Kubernetes Helm Chart (OCI Registry)

The official Helm chart is packaged and published to Docker Hub's OCI registry.

⁠Installation

# Pull and install directly via Helm OCI
helm install zammad-ai oci://registry-1.docker.io/scriptertech/zammad-ai-chatbot \
  --namespace support \
  --create-namespace \
  --set config.openaiUrl="https://llm-gateway.yourdomain.com/v1" \
  --set secrets.openaiApiKey="your-llm-api-key" \
  --set config.openaiModel="google/gemma-4" \
  --set config.zammadUrl="https://zammad.yourdomain.com" \
  --set secrets.zammadApiToken="your-zammad-api-token"

⁠🛠️ Autonomous Function Calling Tools

When conversing with visitors, the LLM autonomously triggers the following tools:

⁠🩺 Health Check & Monitoring

The container exposes a standard Kubernetes liveness/readiness probe:

curl -f http://localhost:8000/healthz
# Response: {"status":"ok","service":"zammad-ai-chatbot","version":"0.3.6"}

⁠📄 License

Distributed under the MIT License. Built with ❤️ by the Scriptertech.