Zapidly

Multi-tenant agent CRM. Chat preview, leads with form fields, HITL inbox, JSON flows interpreted in-process (nudges via Inngest). WhatsApp via Zernio.

Design: docs/architecture.md (overview), AGENTS.md (for coding agents), docs/agent-runtime.md, docs/agent-flow-as-data.md.

Run locally

Full walkthrough (Postgres on Mac, Inngest, ngrok / NEXT_PUBLIC_APP_URL): docs/setup.md.

npm install
npx prisma migrate deploy && npx prisma generate && npm run db:seed
npm run dev

Open http://localhost:3000/demo and talk as a customer. Pick the same lead on the left to continue that conversation.

OpenAI (full LLM test)

Add to .env and restart npm run dev:

OPENAI_API_KEY=sk-...
OPENAI_CHAT_MODEL=gpt-4o-mini

Gemini/Anthropic still work if those keys are set and OpenAI is not. Without any key, classify/extract use heuristics.

Zernio WhatsApp

Set zerino_api_key (or ZERNIO_API_KEY) and zerino_sandbox_number (or ZERNIO_SANDBOX_NUMBER). Seed / Channels binds that sandbox number to the dev tenant.

Inbound: POST /api/webhooks/zernio (message.received). The URL must be public HTTPS. Set ZERNIO_WEBHOOK_SECRET (and the same secret on the Zernio webhook) for X-Zernio-Signature - required in production; optional only for local dev.

Outbound replies use the Zernio inbox API once a WhatsApp conversation id is stored from the inbound webhook. Chat preview does not send to WhatsApp.

Inngest is only required for delayed nudges (npx inngest-cli@latest dev). Full behavior: docs/nudges.md.

Nudge timing is NUDGE_AFTER_OVERRIDE or PT1H after the lead’s last message (not after the agent reply). With a second Zernio webhook to production, nudges may run on Inngest Cloud while you watch local :8288 - use one webhook + local stack when debugging, or open the Inngest Cloud dashboard for production.

For local testing, set NUDGE_AFTER_OVERRIDE=PT5M in .env. Talk stages already include a catalog nudge; you do not need to re-seed unless the agent flow was built without one.

Register a second Zernio webhook for ngrok (production webhook can stay - you may get duplicate replies while both are active):

pnpm proxy   # set NEXT_PUBLIC_APP_URL from banner, restart pnpm dev
pnpm zernio:webhook:dev

npm test covers flow validation and the interpreter.

Public HTTPS (Zernio / any device) - ngrok

pnpm dev      # terminal 1
pnpm proxy    # terminal 2 - ngrok tunnel, prints NEXT_PUBLIC_APP_URL banner

1. Install ngrok: brew install ngrok/ngrok/ngrok
2. Add NGROK_AUTHTOKEN=… to .env (dashboard)
3. Copy the https://… URL from the banner into NEXT_PUBLIC_APP_URL, restart pnpm dev
4. Open /admin or /channels from any device

For a stable URL across restarts, set NGROK_DOMAIN=your-name.ngrok.app (reserved domain on a paid ngrok plan).

pnpm proxy:stop
pnpm proxy:status

Production on a VPS with your own domain: see nginx/zapidly-ssl.example.conf.