Yara Meta WhatsApp Agent

TypeScript backend for a Meta WhatsApp AI agent that recommends personalized Buenos Aires events from Postgres.

Stack

• Express webhook server
• Meta WhatsApp Cloud API transport
• Gemini 2.5 Pro via Google's OpenAI-compatible endpoint
• Drizzle ORM + PostgreSQL
• pg-boss job queue
• Vitest + Supertest

Setup

1. Copy .env.example to .env and fill the required values.
2. Run npm install.
3. Run npm run db:migrate.
4. Import data:
   • npm run db:import:spacetimedb
   • npm run db:import:gcp-export
   • npm run db:import:events
5. Start the server with npm run dev.

Key Endpoints

• GET /health
• GET /webhooks/meta/whatsapp
• POST /webhooks/meta/whatsapp

Commands

• npm run check
• npm test
• npm run build

Notes

• Integration tests use testcontainers and are gated behind RUN_CONTAINER_TESTS=1.
• The default parser model is gemini-2.5-pro.
• Paywall enforcement is disabled by default with PAYWALL_ENABLED=false so testing stays focused on language consistency, recommendations, and the user journey.
• Soft matches are returned by default with ALLOW_SOFT_RECOMMENDATIONS=true so the bot prefers showing the best events over asking extra reframe questions.
• npm run db:import:gcp-export reads the latest Cloud SQL export from GCS and syncs user/profile signal from the GCP-backed SpacetimeDB export.
• Voice transcription, curated plans, and group matching are intentionally deferred, but the service boundaries are ready for those additions.