WhatsAgent

WhatsAgent is a WhatsApp-only conversational automation platform built on the Nexusbert vision.

This repository starts with a production-oriented design for v1:

• WhatsApp Cloud API webhook ingestion
• Conversation processing and agent orchestration
• Outbound delivery with 24-hour session policy handling
• Durable storage, retries, and observability

Design Documents

• docs/architecture/whatsagent-v1.md - end-to-end system architecture and runtime flow
• docs/architecture/data-model.md - relational schema for conversations, messages, and delivery state
• docs/architecture/api-contracts.md - internal API contracts and webhook shapes
• docs/architecture/implementation-plan.md - phased build plan with acceptance criteria
• docs/architecture/service-boundaries.md - repository layout and service responsibilities
• docs/architecture/jaspers-merge-guide.md - what was ported from Jasper sample

Scope

This version intentionally focuses on WhatsApp only. No multi-channel abstractions are required for v1.

Quick Start

1. Copy .env.example to .env and fill values.
2. Install dependencies:
   • npm install
3. Run tests (default memory drivers):
   • npm test
4. Start services:
   • npm run dev:webhook
   • npm run dev:orchestrator
   • npm run dev:delivery
   • npm run dev:agent

Production Infra Mode

1. Start infrastructure:
   • npm run infra:up
2. Set .env:
   • DB_DRIVER=postgres
   • QUEUE_DRIVER=redis
3. Apply schema:
   • npm run db:migrate
4. Start services in separate terminals:
   • npm run dev:webhook
   • npm run dev:orchestrator
   • npm run dev:delivery

This mode uses PostgreSQL and Redis (streams) so services can run as separate processes with durable queue consumption.

One-Command Dev Stack

• npm run dev:stack

This command:

1. starts Docker infrastructure (Postgres + Redis),
2. applies database schema migration,
3. starts webhook, orchestrator, delivery, and agent services together.

Use Ctrl+C to stop all services started by the stack command.

Security and Runtime Notes

• Internal endpoints under /internal/* are protected when INTERNAL_API_KEY is set.
  • send header: x-internal-api-key: <your-key>
• Webhook route has basic IP rate limiting.
  • tune with WEBHOOK_RATE_LIMIT_PER_MINUTE
• Redis stream consumers can be grouped/tuned with:
  • QUEUE_CONSUMER_GROUP
  • QUEUE_CONSUMER_NAME

Jasper Alignment (WhatsApp API)

WhatsAgent now mirrors Jasper's strongest WhatsApp API pattern in delivery:

• send optional read receipt + typing indicator before reply,
• send message through /{phone_number_id}/messages Graph endpoint,
• support text, interactive, template, and raw request-body passthrough payloads.

Config:

• WA_SEND_READ_BEFORE_REPLY=true|false toggles read+typing pre-send behavior.

Meta WhatsApp Env Mapping

These are the key variables that align with Meta WhatsApp Cloud API:

• WA_ACCESS_TOKEN -> temporary/permanent system user access token
• WA_PHONE_NUMBER_ID -> WhatsApp phone number ID used for /{phone_number_id}/messages
• WA_APP_SECRET -> app secret used for webhook signature verification (X-Hub-Signature-256)
• WA_VERIFY_TOKEN -> your custom webhook verify token for GET /webhook
• WA_API_BASE_URL -> Graph API base (https://graph.facebook.com/v22.0 by default)

Optional but commonly tracked in Meta setup:

• APP_ID / WA_APP_ID (not required by runtime send path)
• WABA_ID (not required by runtime send path)

Installable NPM Package

Local install test

1. Build package:
   • npm run build
2. Link globally:
   • npm link
3. Use CLI:
   • whatsagent help
   • whatsagent init
   • whatsagent docs
   • whatsagent migrate
   • whatsagent start all

Publish to npm

1. Ensure package name availability (whatsagent may already be taken).
2. Make sure you are on the branch/commit to publish.
3. Run full checks:
   • npm run typecheck
   • npm test
4. Build dist artifacts:
   • npm run build
5. Validate package contents:
   • npm pack --dry-run
6. Bump version:
   • npm version patch
   • or npm version minor
   • or npm version major
7. Login:
   • npm login
8. Publish:
   • npm publish --access public
9. Verify from clean shell:
   • npm i -g whatsagent
   • whatsagent help

Consumers can then install with:

• npm i -g whatsagent (global CLI)
• or npm i whatsagent and run with npx whatsagent ...

Post-install flow

After install, users can run:

1. whatsagent help - list commands.
2. whatsagent docs - launch local docs at http://localhost:4173.
3. whatsagent init - create .env in current folder.
4. configure .env with Meta WhatsApp keys.
5. whatsagent migrate then whatsagent start all.

Operations

• docs/operations/runbook.md - incident and replay procedures
• docs/operations/launch-checklist.md - launch gate checklist