Skip to content

Heka Developer Portal

Heka is an AI-powered WhatsApp campaign manager built on Meta's Cloud API. It handles inbound message processing, AI-driven conversation agents, campaign orchestration, template sending, and operator handoff — all through a single FastAPI server deployed on Fly.io.

What Heka does

WhatsApp Cloud API ←→ Heka Server ←→ Operator Console
                         ↕
                    AI Agent (Claude)
                         ↕
                    Campaign Funnel
  • Receives WhatsApp messages via Meta webhook
  • Responds using Claude-powered conversation agents with tenant-specific instructions
  • Tracks contacts through campaign funnels (qualification → scheduling → enrollment)
  • Sends template messages (individual, batch, blast) with delivery tracking
  • Manages operator handoff for human-in-the-loop conversations

Interfaces

Heka exposes three interfaces for developers and agents:

Interface For Description
REST API Frontend, integrations 75+ endpoints for campaigns, contacts, conversations, templates
CLI Human developers heka command for campaign admin operations
MCP Server AI agents (Claude Code) 5 tools for campaign phase/resource management

Live endpoints

Environment URL
Production https://heka-operator.fly.dev
Swagger UI https://heka-operator.fly.dev/docs
ReDoc https://heka-operator.fly.dev/redoc
OpenAPI spec https://heka-operator.fly.dev/openapi.json

Tech stack

Component Technology
Backend Python 3.13, FastAPI, Pydantic
Database SQLite (WAL mode, on Fly.io volume)
AI Anthropic Claude API
Channel Meta WhatsApp Cloud API
Media Cloudflare R2
Frontend React + Vite (operator-console-v2)
Deploy Fly.io (single machine, heka-operator)
CLI Typer + httpx
MCP FastMCP (stdio transport)

Source layout

src/heka/
├── agent/          # AI conversation responder (Claude)
├── auth/           # JWT authentication
├── campaigns/      # Campaign CRUD, funnel, pipeline, agent, inference
├── channels/       # Meta adapter, Graph API, sender, rate limiter
├── cli/            # Typer CLI (heka command)
├── conversations/  # Message send/receive, timeline, ownership
├── handoff/        # Human takeover protocol
├── leads/          # Lead state calculator
├── mcp/            # MCP server (campaign admin tools)
├── media/          # R2 media storage + serving
├── persistence/    # SQLite schema, repository, models
├── push/           # Web push notifications
├── segments/       # Contact segmentation engine
├── templates/      # WhatsApp template management
└── webhook/        # FastAPI app, Meta webhook handler