Skip to content

Getting Started

Prerequisites

  • Python 3.13+
  • uv (package manager)
  • Node.js 22+ (for the operator console frontend)
  • A Meta WhatsApp Business account with Cloud API access

Clone and install

git clone git@gitlab.com:humansys-demos/product/heka/heka-agent.git
cd heka-agent

# Install Python dependencies
uv sync

# Install frontend dependencies
cd apps/operator-console-v2
npm ci
cd ../..

Environment variables

Create a .env file (not committed):

# Meta WhatsApp Cloud API
META_PHONE_NUMBER_ID=your_phone_number_id
META_ACCESS_TOKEN=your_access_token
META_VERIFY_TOKEN=your_webhook_verify_token
META_APP_SECRET=your_app_secret

# Anthropic (AI agent)
ANTHROPIC_API_KEY=your_anthropic_key

# Cloudflare R2 (media storage)
R2_ACCOUNT_ID=your_account_id
R2_ACCESS_KEY_ID=your_access_key
R2_SECRET_ACCESS_KEY=your_secret_key
R2_BUCKET_NAME=heka-media

# Auth
JWT_SECRET_KEY=a-random-secret-for-jwt

# Database (optional — defaults to heka_conversations.db)
HEKA_DB_PATH=heka_conversations.db

Run the server

# Development mode (auto-reload)
uv run uvicorn heka.webhook.app:create_app --factory --reload --port 8000

# Or via __main__
uv run python -m heka

The server starts at http://localhost:8000. The SQLite database is created automatically on first run.

Run the frontend

cd apps/operator-console-v2
npm run dev

Opens at http://localhost:5173 with a proxy to the backend.

Run tests

# Full test suite
uv run pytest

# Specific test file
uv run pytest tests/campaigns/test_router.py

# With coverage
uv run pytest --cov=heka

# Type checking
uv run pyright

# Linting
uv run ruff check

# Formatting
uv run ruff format --check

Project structure

heka-agent/
├── src/heka/              # Python backend (FastAPI)
├── apps/
│   └── operator-console-v2/  # React frontend
├── tests/                 # pytest test suite
├── docs/                  # Developer documentation (this site)
├── work/                  # Epic/story artifacts (RaiSE governance)
├── governance/            # Guardrails and ADRs
├── fly.toml               # Fly.io deployment config
├── Dockerfile             # Multi-stage build (backend + frontend)
├── pyproject.toml         # Python project config
└── mkdocs.yml             # Documentation site config

Webhook setup (for development)

To receive WhatsApp messages locally, use a tunnel:

# With ngrok
ngrok http 8000

# Configure the webhook URL in Meta Developer Console:
# https://your-ngrok-url.ngrok-free.app/webhook

Set your META_VERIFY_TOKEN in both the .env file and the Meta Developer Console.