OrbitDesk

Project Overview

OrbitDesk is a full-featured, multi-tenant SaaS platform that enables businesses to manage customer communications across 7 messaging channels, automate interactions with visual flow builders, and leverage AI chatbots for customer support. Channels include WhatsApp (Cloud API + Baileys QR), Telegram, Facebook Messenger, Instagram DM, Email (SMTP/IMAP), Twilio SMS, and an embeddable Live Chat widget.

Key Capabilities

Architecture

OrbitDesk follows a monorepo structure managed by Turborepo + pnpm workspaces. The platform consists of three application services backed by three data stores.

Tech Stack

Messaging & Inbox

The real-time inbox is the core of OrbitDesk. Agents can manage customer conversations across all connected channels, send messages, assign chats, and track delivery status — all in real time via WebSockets.

WhatsApp Connection Types

Message Types

Conversation Lifecycle

Channel Pipeline (all channels)

Channel Adapters

OrbitDesk ships with a unified ChannelsModule that abstracts every messaging channel behind a common IMessageChannel interface. All adapters share the same pipeline: inbound normalisation → contact upsert → conversation upsert → MongoDB store → WebSocket emit → flow trigger.

Supported Channels

Architecture

Each adapter implements IMessageChannel and self-registers via ChannelRouterService on module init. Inbound messages are normalised to a common NormalizedMessage shape by a per-channel Normalizer before entering the shared pipeline.

Adding a Custom Channel

Implement the IMessageChannel interface, create a Normalizer, register the adapter in ChannelsModule, and add a controller for the inbound webhook. No changes needed to the pipeline, flow engine, or inbox.

Contact Management

Contacts are the CRM backbone. Each contact is scoped to a tenant and identified by phone number. Contacts support custom fields and tags for segmentation.

Flow Automation

The visual flow builder (powered by FlowGram.ai) lets users design automation workflows with a drag-and-drop canvas. Flows are triggered by events and execute a graph of nodes.

Flow Lifecycle

Available Node Types (13)

Trigger Types

Flow Execution Engine

The backend flow engine (FlowExecutorService) traverses the graph from the trigger node, executing each node via the NodeExecutorFactory. Flow sessions (state, variables, execution log) are stored in MongoDB. Webhook-triggered flows run asynchronously — the HTTP response is returned immediately while the flow executes in the background.

Webhook Integration

External services can trigger flow automations by sending HTTP requests to unique webhook URLs. This enables push-based integrations with e-commerce platforms, form builders, payment gateways, and any system that supports outgoing webhooks.

How It Works

When a flow’s trigger type is set to webhook, the system generates a unique UUID token. External services send a POST request to /api/v1/webhooks/{token}. The system validates the request, triggers the flow asynchronously, and returns an immediate 200 response.

Webhook URL

POST https://<your-domain>/api/v1/webhooks/<webhook-token>

The webhook token is a UUID generated automatically when a flow’s trigger type is set to webhook. It is globally unique and serves as both the identifier and access key.

Authentication & Signature Verification

Webhook endpoints are public (no Bearer token required) — access is controlled by the unique token in the URL. For additional security, you can configure an optional HMAC-SHA256 secret.

If a webhook secret is configured, incoming requests must include a valid signature in one of the headers above. The expected format is:

sha256=<hex-encoded HMAC-SHA256 of raw request body>

The system uses timing-safe comparison to prevent timing attacks. Requests with invalid or missing signatures receive a 403 Forbidden response.

Request Format

POST /api/v1/webhooks/a1b2c3d4-e5f6-7890-abcd-ef1234567890?source=shopify HTTP/1.1
Host: app.example.com
Content-Type: application/json
X-Hub-Signature-256: sha256=abcdef1234567890...

{
  "event": "order.created",
  "data": {
    "orderId": "12345",
    "amount": 99.99,
    "customer": {
      "email": "user@example.com",
      "name": "John Doe"
    }
  }
}

The endpoint accepts any valid JSON body. Query parameters, headers, and the full body are all captured and made available as flow variables.

Response

HTTP/1.1 200 OK
Content-Type: application/json

{ "success": true, "message": "Webhook received" }

Available Variables

Webhook data is accessible in all subsequent flow nodes using template syntax:

Example — Using webhook data in a Send Message node:

Dear {{webhook.body.data.customer.name}},

Your order #{{webhook.body.data.orderId}} totaling ${{webhook.body.data.amount}}
has been received. We'll process it shortly.

Token Management

Verification Endpoint

GET /api/v1/webhooks/:token

Returns the flow name and status. Use this to verify connectivity from your external service before sending events.

Security

• HMAC-SHA256 signatures — Optional but recommended for production. Timing-safe comparison prevents timing attacks.
• Header sanitization — authorization, cookie, and set-cookie headers are stripped from trigger data to prevent credential leakage.
• Tenant isolation — Each webhook token maps to exactly one flow and tenant. No cross-tenant access is possible.
• Token rotation — Tokens can be regenerated instantly via API, invalidating the old URL.
• Flow state check — Only ACTIVE flows are triggered. Draft, paused, or archived flows return 403 Forbidden.

Error Responses

cURL Example

# Without signature verification
curl -X POST https://app.example.com/api/v1/webhooks/YOUR_TOKEN \
  -H "Content-Type: application/json" \
  -d '{"event": "order.created", "orderId": "12345"}'

# With HMAC-SHA256 signature
BODY='{"event": "order.created", "orderId": "12345"}'
SECRET="your-webhook-secret"
SIGNATURE="sha256=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | cut -d' ' -f2)"

curl -X POST https://app.example.com/api/v1/webhooks/YOUR_TOKEN \
  -H "Content-Type: application/json" \
  -H "X-Hub-Signature-256: $SIGNATURE" \
  -d "$BODY"

Common Use Cases

REST API Access

OrbitDesk provides scoped API key authentication for external integrations. API keys allow third-party services, automation platforms, and custom applications to access the REST API without requiring user login credentials.

How It Works

API keys are managed from Settings > API Keys (admin-only). Each key is generated with a wcrm_ prefix, and only the SHA-256 hash is stored in the database. The raw key is displayed only once at creation time.

Authentication

API key authentication works alongside existing JWT authentication. Any protected endpoint accepts either a Bearer token or an X-Api-Key header. The system tries JWT first, then falls back to API key validation.

# Authenticate with API key
curl -H "X-Api-Key: wcrm_abc123..." \
  https://your-domain.com/api/v1/contacts

# JWT authentication still works as before
curl -H "Authorization: Bearer eyJhb..." \
  https://your-domain.com/api/v1/contacts

API key requests are automatically scoped to the tenant that created the key via the TenantScopeInterceptor — no manual tenant ID required.

Available Scopes

Each API key is granted specific scopes that control which endpoints it can access. JWT-authenticated users bypass scope checks entirely (full access as before).

Key Management Endpoints

These endpoints require JWT authentication with admin or superadmin role:

Create Key Request

POST /api/v1/api-keys
Authorization: Bearer <admin-jwt-token>
Content-Type: application/json

{
  "name": "Zapier Integration",
  "scopes": ["contacts:read", "contacts:write", "messages:send"],
  "expiresAt": "2027-01-01T00:00:00Z"   // optional, null = never expires
}

Create Key Response

HTTP/1.1 201 Created

{
  "id": "a1b2c3d4-...",
  "name": "Zapier Integration",
  "key": "wcrm_7f3a9b2c4d5e6f...",       // ⚠ shown ONLY once
  "scopes": ["contacts:read", "contacts:write", "messages:send"],
  "expiresAt": "2027-01-01T00:00:00.000Z",
  "createdAt": "2026-02-19T10:30:00.000Z",
  "isActive": true
}

Rate Limiting

All API requests are rate-limited to 100 requests per minute. API key requests are tracked per key ID, while JWT requests are tracked per IP address. Rate limit information is included in response headers:

Use Cases

Security

• SHA-256 hashed storage — Raw keys are never stored. Only the cryptographic hash is persisted.
• One-time key reveal — The raw key is shown only at creation. It cannot be retrieved afterward.
• Scope enforcement — Each key is limited to specific scopes. Missing scopes return 403 Forbidden.
• Key expiration — Optional expiry date. Expired keys are automatically rejected.
• Tenant isolation — API keys are scoped to a single tenant. No cross-tenant access possible.
• Rate limiting — Per-key rate limiting prevents abuse (100 req/min default).
• Revocation — Keys can be instantly revoked or deleted from the Settings UI or API.
• Max 20 active keys per tenant to prevent key sprawl.

Error Responses

cURL Examples

# List contacts with API key
curl -H "X-Api-Key: wcrm_7f3a9b2c4d5e6f..." \
  https://your-domain.com/api/v1/contacts

# Create a contact
curl -X POST -H "X-Api-Key: wcrm_7f3a9b2c4d5e6f..." \
  -H "Content-Type: application/json" \
  -d '{"phone": "+1234567890", "name": "John Doe", "email": "john@example.com"}' \
  https://your-domain.com/api/v1/contacts

# Send a message
curl -X POST -H "X-Api-Key: wcrm_7f3a9b2c4d5e6f..." \
  -H "Content-Type: application/json" \
  -d '{"conversationId": "conv-uuid", "type": "text", "content": "Hello!"}' \
  https://your-domain.com/api/v1/messages

Templates & Campaigns

WhatsApp Message Templates

Templates are pre-approved message formats required by Meta for outbound messaging outside the 24-hour window. They go through a review process before they can be used.

Template components: Header (text/image/video), Body (text with variables), Footer (text), Buttons (quick reply / URL). Sync with Meta Business Account via API.

Campaigns (Bulk Messaging)

Campaigns enable sending templates to a list of contacts at scale. Campaign statuses: Draft Scheduled Running Completed Failed

Each campaign tracks totalRecipients, sentCount, and failedCount for delivery reporting.

AI Chatbots

OrbitDesk integrates with agents.fastlab.ai to provide AI-powered chatbots with Retrieval-Augmented Generation (RAG) and optional AI Function Calling. Each tenant can create multiple chat agents with their own knowledge bases and tool capabilities.

How It Works

1. Create a Chat Agent — Define name, description, and behavior in Chat Agents
2. Upload Datasources — Files (PDF, text), URLs, or raw text for RAG indexing
3. Enable AI Function Calling — Optionally give the agent tools to take actions (CRM lookups, bookings, flow triggers)
4. Assign to Conversations — Bot automatically responds to incoming messages
5. Human Handoff — Configurable keywords trigger transfer to a live agent

Two Agent Modes

AI Function Calling

When AI Function Calling is enabled on a chat agent, incoming messages are routed to the Orbit FastAPI AI service instead of the standard RAG path. The service runs an autonomous tool-calling loop:

Available Tools (5)

Configuring Tool Calling via the UI

Tool calling is configured in Chat Agents — no API calls or seeders required.

1. Open Chat Agents and click Add Agent or the edit icon on an existing agent.
2. Scroll to the AI Function Calling section and toggle it on.
3. Configure the fields:

The configuration is stored on the ChatAgent record in PostgreSQL as toolsEnabled (boolean) and toolsConfig (JSON).

AI Service (FastAPI)

The standalone Python microservice at services/ai/ handles both RAG and tool-calling paths:

• POST /api/v1/agent/chat — Agentic tool-calling loop (OpenAI or Anthropic)
• POST /chat/completion — Multi-provider LLM chat
• POST /rag/query — RAG queries against indexed datasources
• GET /health — Health check endpoint

The service is stateless — all context (contact info, conversation ID, tool config) is passed per-request by NestJS. Authentication uses short-lived HS256 JWTs (INTERNAL_JWT_SECRET) that expire after 2 minutes. See services/ai/REQUIREMENTS.md for the full API spec.

AI Voice Calling

OrbitDesk includes a full AI-powered voice calling system built on Twilio for telephony and OpenAI Realtime API for conversational AI. AI voice agents can make outbound calls, converse naturally with contacts, execute tool calls, and qualify leads — all autonomously.

Voice Call Flow

Core Components

Voice Agent Configuration

Available Agent Tools

Voice Campaigns

Voice campaigns enable automated bulk outbound calling with AI agents. Campaigns support scheduling, concurrency control, retry logic, and DNC compliance.

Call Lifecycle

Other terminal states: FAILED NO_ANSWER BUSY CANCELED

Post-Call Processing

After each call ends, a Bull queue pipeline performs:

1. Transcription — Full conversation transcript stored as JSON
2. Summarization — AI-generated call summary via Orbit FastAPI
3. Sentiment Analysis — POSITIVE / NEUTRAL / NEGATIVE / MIXED / UNKNOWN
4. Lead Qualification — HOT / WARM / COLD with score, interests, and next steps
5. Cost Calculation — Per-minute, TTS, STT, and LLM token costs tracked
6. Webhook Dispatch — call.completed, lead.qualified events sent to tenant webhooks

Knowledge Bases

Voice knowledge bases provide real-time information retrieval during live calls. When the AI agent needs specific information, it queries the knowledge base via pgvector semantic search.

Embeddings are generated via OpenAI text-embedding-3-small (1536 dimensions) and stored with pgvector for fast similarity search.

Voice Analytics Dashboard

The analytics dashboard provides 8 visualization panels:

Per-Tenant API Key Isolation

Each tenant configures their own API keys for voice services in Settings > Integrations:

• OpenAI API Key — Used for Realtime API and embeddings. Encrypted at rest (AES), synced to Orbit FastAPI.
• ElevenLabs API Key — Optional, for premium voice synthesis. Encrypted at rest.
• Twilio Credentials — Account SID + Auth Token for telephony. Encrypted at rest.

Keys are resolved per-request: tenant-specific key first, with global environment variable as fallback.

Plugin System

OrbitDesk has a modular plugin architecture. Plugins extend functionality and are installed per-tenant from the marketplace.

Plugins can be FREE or PAID, and have visibility: GLOBAL (all tenants) or TENANT (specific tenant). Custom plugins can be uploaded as .tgz packages.

Multi-Tenancy & Authentication

Tenant Isolation

Every resource (contacts, conversations, flows, templates, etc.) is scoped to a tenantId. The API extracts tenant context from the JWT token, ensuring complete data isolation between organizations.

Authentication Methods

OrbitDesk supports two authentication methods. Both extract tenant context automatically:

Role-Based Access Control

Tenant Onboarding

Subscription Plans

Each plan defines limits: maxAgents, maxContacts, maxMessagesPerMonth, plus a flexible features JSON for feature flags. Plans can be priced and sorted in the marketplace.

Dashboard & Analytics

The home dashboard provides a real-time overview of key metrics, cached in Redis for 5 minutes.

7-Day Message Volume Chart — Line/bar chart showing inbound vs outbound messages over the past week, powered by ApexCharts.

Subscriptions & Billing

OrbitDesk includes a complete subscription and billing system with support for multiple payment gateways. Tenants can subscribe to plans with resource limits, and superadmins can manage plans, configure payment providers, and manually assign plans.

Payment Gateways

Plan Management

Superadmins can create and manage subscription plans with configurable resource limits:

Subscription Lifecycle

Webhook Events

Usage Tracking

The PlanLimitsService tracks resource usage across seven dimensions and enforces limits automatically:

Payment Provider Configuration

Payment providers are configured via the Superadmin panel. Credentials are stored encrypted using AES encryption and masked in API responses (only last 4 characters shown). Only one provider can be active at a time.

API Reference

All API endpoints are prefixed with /api/v1. Interactive Swagger docs are available at /api/docs in development.

Auth

Conversations

Messages

Contacts

Flows

Webhooks (Flow Triggers)

Templates

Chat Agents

WhatsApp

Channel Adapters (public inbound)

Plans & Subscriptions

Webhooks (Payment)

Superadmin — Plans

Superadmin — Payment Providers

API Keys

Voice Agents

Voice Knowledge Bases

Voice Campaigns

Calls

Phone Numbers

Voice Analytics

Twilio Webhooks (Voice)

DNC (Do Not Call)

Other

Data Models

PostgreSQL (Prisma ORM)

Relational data for entities that need ACID guarantees, foreign keys, and complex queries.

MongoDB (Mongoose ODM)

Document store for high-volume, time-series data that benefits from flexible schemas.

Real-Time (WebSocket)

OrbitDesk uses Socket.IO on the /chat namespace for real-time communication. JWT authentication is required for connection.

Rooms: tenant:{tenantId} (tenant-wide events), conversation:{conversationId} (per-conversation events)

Security

Project Structure

whatsapp-crm/
├── apps/
│   ├── api/                    # NestJS Backend (REST + WebSocket)
│   │   ├── prisma/             #   Prisma schema, migrations, seed
│   │   └── src/
│   │       ├── common/         #   Shared guards, decorators, schemas
│   │       ├── modules/        #   Feature modules (auth, contacts, flows,
│   │       │                   #   voice-agents, twilio-voice, voice-campaigns,
│   │       │                   #   voice-knowledge-base, voice-analytics, calls...)
│   │       └── main.ts         #   App bootstrap
│   ├── web/                    # React Frontend (SPA)
│   │   └── src/
│   │       ├── pages/          #   Page components (inbox, flows, settings,
│   │       │                   #   voice-agents, voice-campaigns, calls,
│   │       │                   #   phone-numbers, voice-analytics...)
│   │       ├── router/         #   Route definitions
│   │       ├── services/       #   API client (Axios + TanStack Query)
│   │       └── layouts/        #   App shell, sidebar, topbar
│   └── plugins/                # Installable plugin packages
│       ├── orbitdesk-plugin-email/
│       ├── orbitdesk-plugin-google-sheets/
│       ├── orbitdesk-plugin-twilio/
│       └── orbitdesk-plugin-whatsapp-qr/
├── packages/
│   ├── shared/                 # Shared types, validators, constants
│   └── ui/                     # UI component library (Tailwind-based)
├── services/
│   └── ai/                     # FastAPI Python AI service
├── docker/                     # Dockerfiles + Nginx configs
├── scripts/                    # Deployment & backup scripts
├── .github/workflows/          # CI/CD pipelines
├── turbo.json                  # Turborepo configuration
├── pnpm-workspace.yaml         # Workspace definition
├── docker-compose.prod.yml     # Production Docker Compose
└── ecosystem.config.cjs        # PM2 configuration

Environment Variables

All environment variables are defined in .env at the project root. Copy from .env.example and configure for your environment.

Deployment

OrbitDesk supports two deployment strategies on Ubuntu servers. See DEPLOYMENT.md for the complete step-by-step guide.

docker compose -f docker-compose.prod.yml up -d

sudo bash scripts/deploy-bare-metal.sh

Server Requirements

Required Ports (Firewall)

Internal ports (3000, 3002, 5432, 27017, 6379, 8000) should NOT be exposed publicly.

CI/CD Pipeline

GitHub Actions workflows for automated deployment on push to main.

Pipeline Flow

Required GitHub Secrets

Workflow Files

• .github/workflows/deploy-docker.yml — Docker-based deployment
• .github/workflows/deploy-bare-metal.yml — Artifact-based deployment via SCP + PM2

Developer Setup

Prerequisites

• Node.js 20 (with corepack enabled)
• pnpm 9.15.4 (via corepack)
• Docker (for databases) or local PostgreSQL 16, MongoDB 7, Redis 7
• Python 3.11 (for AI service)

Quick Start

# 1. Clone the repository
git clone https://github.com/your-org/whatsapp-crm.git
cd whatsapp-crm

# 2. Install dependencies
corepack enable
pnpm install

# 3. Start databases (Docker)
docker compose -f docker/docker-compose.yml up -d

# 4. Configure environment
cp .env.example .env
# Edit .env with your settings

# 5. Setup database
pnpm db:generate
pnpm db:migrate
pnpm db:seed

# 6. Start development servers
pnpm dev
# Web:  http://localhost:3000
# API:  http://localhost:3002
# Docs: http://localhost:3002/api/docs

# 7. (Optional) Start AI service
cd services/ai
python3.11 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
uvicorn main:app --reload --port 8000

Useful Commands

Frequently Asked Questions