hay-core

Hay.chat is self-hosted AI customer support software. Its AI agents resolve customer requests instead of just answering them: they look up orders, issue refunds and update orders through Shopify, WooCommerce and Stripe, and hand off to a human when they aren't confident. Run it on your own server with Docker, or use the hosted version at hay.chat.

Best for Shopify and WooCommerce stores that want AI to actually issue refunds and update orders, on a flat monthly plan with no per-seat fees, with a human approval step available on any action.

Website · Documentation

What is Hay.chat?

Hay.chat lets businesses deploy AI agents that handle customer support 24/7 across multiple channels. Agents are grounded in your documentation, follow structured playbooks, and seamlessly escalate to humans when needed.

Key capabilities:

• AI Agents — Configure tone, instructions, and behavior. Test before deploying.
• Knowledge Base — Upload PDFs, Word docs, text, markdown, or import from URLs. Agents use vector search to ground answers in your content.
• Playbooks — Step-by-step workflows for specific scenarios (refunds, order lookups, greetings, etc.).
• Multi-channel — Live chat widget, WhatsApp, Instagram DMs, Messenger and email, via plugins.
• Human Handoff — Automatic escalation with full conversation context, plus an approval step for refunds, cancellations and discounts.
• Plugin Ecosystem — Shopify, WooCommerce, Magento, Wix, Nuvemshop, Stripe, HubSpot, Zendesk and more via MCP (Model Context Protocol).
• Analytics — Resolution rate, response time, customer satisfaction, and conversation insights.
• Privacy — GDPR-compliant data handling with DSAR support.

Self-host Hay.chat

Hay.chat runs with Docker, PostgreSQL 16 with pgvector, and Redis 7. See Getting Started below.

Chat models: OpenAI, Anthropic, Gemini, or any OpenAI-compatible endpoint (for example DigitalOcean Gradient, or a local server such as Ollama, which is untested). Embeddings use OpenAI text-embedding-3-small, so an OpenAI key is still required. No telemetry is sent unless you set POSTHOG_KEY.

Teams comparing Chatwoot, Zammad or Dify for self-hosted AI support use Hay.chat when they need the agent to take actions, not just reply.

Tech Stack

Project Structure

├── dashboard/          # Nuxt 3 frontend
├── server/             # Express + tRPC backend
├── webchat/            # Embeddable chat widget
├── plugins/
│   ├── core/           # Built-in plugins (email, stripe, hubspot, etc.)
│   └── custom/         # User-created plugins
├── packages/
│   ├── plugin-sdk/     # @hay/plugin-sdk
│   └── server-sdk/     # @hay/server-sdk
├── docs/               # Technical and user documentation
├── tests/              # Playwright E2E tests
└── docker-compose.yml  # PostgreSQL + Redis

Getting Started

Prerequisites

• Node.js >= 18
• npm >= 9
• Docker (for PostgreSQL and Redis)

Setup

# Clone the repository
git clone <repo-url>
cd hay-core

# Start infrastructure
docker compose up -d

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your settings (see Environment Variables below)

# Run database migrations
cd server && npm run migration:run && cd ..

# Start development
npm run dev

The dashboard runs on http://localhost:3000 and the API on http://localhost:3001.

Environment Variables

Development

# Run everything
npm run dev

# Individual services
npm run dev:server        # Backend only (port 3001)
npm run dev:dashboard     # Frontend only (port 3000)
npm run dev:webchat       # Webchat widget

# Testing
npm run test              # All tests
npm run test:server       # Server tests (Jest)
npm run test:dashboard    # Dashboard tests (Vitest)

# Code quality
npm run lint              # Lint all code
npm run lint:fix           # Auto-fix lint issues
npm run typecheck         # TypeScript checks

# Database
npm run migration:run     # Run pending migrations
npm run migration:generate -- ./database/migrations/Name  # Generate migration
npm run migration:revert  # Revert last migration

Architecture

AI Orchestrator

The orchestrator processes conversations through a three-layer pipeline:

1. Perception — Analyzes user intent, sentiment, and language
2. Retrieval — Finds relevant playbooks and documents via vector similarity search
3. Execution — Generates responses using agent context, retrieved knowledge, and active plugins

A two-stage guardrail system protects response quality:

• Stage 1: Company interest protection — blocks harmful responses
• Stage 2: Fact grounding — validates claims against source documents

Plugin System

Plugins extend Hay.chat via the Model Context Protocol (MCP). Each plugin is loaded dynamically at runtime — the core never hardcodes plugin references.

Core plugins:

See the Plugin API docs for the plugin development guide.

Webchat Widget

Embed the chat widget on any website:

<script>
  window.HayChat = {
    config: {
      organizationId: "your-org-id",
      baseUrl: "https://your-api-domain.com",
      // ePrivacy consent mode: no cookies/storage until the first user interaction
      consent: "strict",
      position: "right",
      theme: "blue",
      greetingMessage: "Hi! How can we help?",
    },
  };
</script>
<script src="https://your-cdn/webchat.js" async></script>

If you use a cookie banner, set window.HayChat.config only after the user accepts:

<script>
  function onConsentAccepted() {
    window.HayChat = window.HayChat || {};
    window.HayChat.config = {
      organizationId: "your-org-id",
      baseUrl: "https://your-api-domain.com",
      consent: "strict",
    };
    const s = document.createElement("script");
    s.src = "https://your-cdn/webchat.js";
    s.async = true;
    document.head.appendChild(s);
  }
</script>

Features: real-time messaging, typing indicators, agent avatars, unread badge, i18n support, and custom context injection via window.HayChat.addContext().

Documentation

• Overview
• Architecture
• Context API
• Guardrails
• Plugin Getting Started
• Plugin API Reference
• Channel Architecture
• Contributing

License

Hay Community License v1.0 — free to use, modify, and deploy, but you may not sell the software itself or remove the "Powered by Hay" attribution from the chat widget. See the full LICENSE for details.