tiledesk-server

Tiledesk exposes a comprehensive REST API built on Express.js that manages the full lifecycle of customer support requests (tickets) from creation through closure. The system implements configurable department-based routing logic that automatically assigns incoming requests to appropriate departments based on rules, availability, and skill matching. Request state transitions (open → assigned → closed) are tracked in MongoDB with real-time WebSocket notifications to connected agents, enabling synchronous multi-agent awareness of request status changes without polling.

Tiledesk implements a message handling layer that abstracts multiple communication channels (web chat, WhatsApp, Telegram, Facebook Messenger) through a unified message model stored in MongoDB. Messages are routed through the Chat21 integration layer, which normalizes incoming messages from different channels into a standard format, persists them with full conversation history, and broadcasts them to connected agents via WebSocket. The system maintains channel-specific metadata (phone numbers, user IDs, platform-specific fields) while presenting a unified conversation interface to support agents.

Tiledesk implements a system services layer that executes background jobs triggered by internal events or scheduled intervals. Services include request cleanup (archiving old closed requests), email digest generation, webhook retry processing, and knowledge base indexing. Services are implemented as Node.js modules that subscribe to events (via EventEmitter or RabbitMQ) or run on schedules (via node-cron or similar). Services are decoupled from the main request processing path, allowing long-running operations to complete without blocking API responses. The system maintains a service registry that tracks which services are running and their health status, enabling monitoring and restart capabilities.

Tiledesk provides a Dockerfile and Docker Compose configuration for containerized deployment. The Docker image includes Node.js 16.17.0, all npm dependencies, and the Tiledesk application code. Configuration is managed through environment variables (loaded from .env file or Docker secrets), allowing the same image to be deployed across development, staging, and production without rebuilding. The Dockerfile supports both standalone deployment (with embedded MongoDB) and integration with external MongoDB and Redis instances. Docker Compose templates are provided for quick local development with MongoDB and Redis services pre-configured.

Tiledesk implements a multi-strategy authentication system using Passport.js that supports JWT tokens, basic authentication, and OAuth (including Google OAuth). The system validates credentials against MongoDB user records and issues JWT tokens for stateless API access. Role-based access control (RBAC) is enforced at the middleware level, with roles including admin, agent, and guest, combined with project-level permissions to create fine-grained authorization rules. Each protected route checks both the user's role and their project membership before allowing access.

Tiledesk provides a dual knowledge base system: FAQ knowledge bases (structured Q&A pairs) and general knowledge bases (unstructured documents). Both are stored in MongoDB and indexed for retrieval. The system integrates with retrieval-augmented generation (RAG) capabilities, allowing bots and agents to query knowledge bases semantically to find relevant answers before responding to customers. Knowledge base entries are tagged, categorized, and versioned, with support for enabling/disabling entries without deletion. The retrieval layer supports both keyword matching and semantic similarity (via embeddings) to find the most relevant knowledge base articles.

Tiledesk implements a bot handler system that executes custom bot logic in response to incoming messages. Bot handlers are JavaScript functions that receive the full request context (customer message, conversation history, request metadata) and can call external LLMs (OpenAI, Anthropic, etc.) or execute custom logic. The system injects context from the request (customer name, department, previous messages) into the bot handler, allowing bots to make context-aware decisions. Bot handlers can query knowledge bases, call external APIs, or escalate to human agents based on custom conditions. The execution is asynchronous and supports timeout handling to prevent hung bots from blocking request processing.

Tiledesk uses WebSockets (via Socket.io or native WebSocket) to enable real-time bidirectional communication between the server and connected clients (agents, customers, dashboards). The system implements an event-driven architecture where message events, request state changes, and agent status updates are broadcast to all subscribed clients. Events are published through a central event emitter (Node.js EventEmitter or RabbitMQ if configured), and clients subscribe to specific event channels (e.g., 'request:123:message', 'agent:status'). The WebSocket layer maintains a registry of connected clients and their subscriptions, allowing selective broadcasting to avoid flooding all clients with irrelevant events.

Tiledesk includes an email notification system that sends transactional emails to customers and agents based on request events (new message, request assigned, request closed, etc.). The system uses HTML email templates stored in the filesystem (template/email/ directory) and renders them with dynamic data (customer name, request ID, message content) using a template engine. Emails are sent via SMTP using configurable credentials (Gmail, SendGrid, custom SMTP servers). The notification system is event-driven, triggered by request state changes or message arrivals, and supports conditional sending (e.g., only email if agent is offline). Email sending is asynchronous to avoid blocking request processing.

Tiledesk implements a webhook system that allows external systems to subscribe to internal events (message received, request assigned, request closed, etc.). Webhooks are configured per-project with a target URL and event filters. When a subscribed event occurs, Tiledesk sends an HTTP POST request to the webhook URL with a JSON payload containing the event data. The system implements retry logic with exponential backoff for failed webhook deliveries, and maintains a webhook delivery log for debugging and compliance. Webhooks are delivered asynchronously to avoid blocking request processing, and support signature verification (HMAC) to allow webhook consumers to validate that requests originated from Tiledesk.

Tiledesk implements a multi-tenant architecture where each project is an isolated workspace with its own requests, knowledge bases, agents, and settings. Users are assigned to projects with specific roles (admin, agent, guest) that determine their permissions within that project. The system maintains a project-to-user mapping in MongoDB, allowing a single user to have different roles across multiple projects. Project settings (name, description, settings) are stored separately from user data, enabling project-level configuration without affecting other projects. The permission system is enforced at the middleware level, checking both user role and project membership before allowing access to project resources.

Tiledesk implements a quota system that limits resource usage per project, including API requests, message volume, and knowledge base entries. Quotas are configured per project and enforced at the API middleware level, returning HTTP 429 (Too Many Requests) when limits are exceeded. The system tracks quota usage in Redis (for fast lookups) and MongoDB (for persistence), with configurable quota windows (per minute, per hour, per day). Quota enforcement is transparent to the application logic; middleware checks quota before processing requests and increments counters after successful completion. The system supports different quota tiers (free, pro, enterprise) with different limits per tier.