Manvi

A personal AI assistant that works entirely inside WhatsApp. Set reminders, manage daily routines, save contacts, search the web, and forward messages — all by sending a text.

Live: manvi-bot.vercel.app Docs: manvi-bot.vercel.app/documentation

---

Quick start

git clone https://github.com/viswabnath/whatsapp-reminder-bot
cd whatsapp-reminder-bot
npm install
cp .env.example .env   # fill in your keys
npm run dev

Full setup guide — including Meta webhook configuration, Supabase schema, and Vercel deployment — is at manvi-bot.vercel.app/documentation.

---

What it does

Feature	Example
One-off reminders	"Remind me to call the bank at 3 PM"
Interval reminders	"Remind me every 30 mins to drink water"
Daily routines	"Remind me to drink water every day at 10 AM"
Weekly recurring	"Remind me to take out the trash every Tuesday at 8 PM"
Monthly recurring	"Remind me to pay rent on the 1st of every month at 9 AM"
Edit last reminder	"Actually, make that 6 PM"
Birthdays & events	"22nd May is Manu's birthday"
Save contacts	"Save mom as 919876543210"
Message contacts	"Tell mom I'll be 10 minutes late"
Web search	"Who won IPL 2024?"
Delete tasks	"Delete the drink water routine"
Conversational chat	"Explain machine learning simply"
Follow-up questions	"Who was the captain?" (after asking about a match)
Vague time defaults	"Remind me tomorrow morning to call the doctor" → 9:00 AM

---

Stack

• Runtime: Node.js + Express on Vercel
• Database: Supabase (PostgreSQL)
• Messaging: Meta WhatsApp Cloud API
• AI: Gemini 3 Flash → Gemini 2.5 Flash → Groq Llama 3.3 → OpenRouter GPT-4o-mini
• Search: Tavily (primary) + Serper (fallback)
• Timezone: IST (Asia/Kolkata) throughout
• Uptime monitoring: UptimeRobot (pings /api/ping every 5 min, push alert on downtime)

---

Database schema

Table	Purpose
contacts	Address book
personal_reminders	One-off and interval reminders
daily_routines	Daily fixed-time recurring tasks
recurring_tasks	Weekly and monthly recurring tasks (added v1.1)
special_events	Birthdays and anniversaries
interaction_logs	Message log + conversational memory source
api_usage	Daily AI/search quota tracking
system_jobs	Background job health and heartbeat tracking (added v1.1.1)

v1.2.0 migration — run once in Supabase

-- Atomic counter increment for api_usage
CREATE OR REPLACE FUNCTION increment_api_usage(p_date DATE, p_column TEXT)
RETURNS void LANGUAGE plpgsql AS $$
DECLARE col_name TEXT := p_column || '_count';
BEGIN
  EXECUTE format(
    'UPDATE api_usage SET %I = COALESCE(%I, 0) + 1 WHERE usage_date = $1',
    col_name, col_name
  ) USING p_date;
END; $$;

v1.1 migration — run once in Supabase

CREATE TABLE recurring_tasks (
  id               BIGSERIAL PRIMARY KEY,
  phone            TEXT NOT NULL,
  task_name        TEXT NOT NULL,
  reminder_time    TIME NOT NULL,
  recurrence_type  TEXT NOT NULL CHECK (recurrence_type IN ('weekly', 'monthly')),
  day_of_week      INTEGER,
  day_of_month     INTEGER,
  is_active        BOOLEAN DEFAULT TRUE,
  last_fired_date  DATE,
  created_at       TIMESTAMPTZ DEFAULT NOW()
);

-- v1.1.1: Job tracking
CREATE TABLE system_jobs (
    job_name TEXT PRIMARY KEY,
    last_fired TIMESTAMPTZ,
    status TEXT DEFAULT 'active'
);

INSERT INTO system_jobs (job_name, status)
VALUES 
    ('Reminder Dispatch', 'active'),
    ('Routine Dispatch', 'active'),
    ('Recurring Task Dispatch', 'active'),
    ('Event Alert', 'active')
ON CONFLICT (job_name) DO NOTHING;

---

Environment variables

See .env.example for the full list. Requires keys for: Meta, Supabase, Gemini, Groq, OpenRouter, Tavily, Serper.

Variable	Required	Purpose
VERIFY_TOKEN	Yes	Meta webhook handshake token
MY_PHONE_NUMBER	Yes	Your WhatsApp number (digits only, no +)
PHONE_NUMBER_ID	Yes	Meta App → WhatsApp → API Setup
ACCESS_TOKEN	Yes	Meta permanent access token
SUPABASE_URL	Yes	Supabase project URL
SUPABASE_KEY	Yes	Supabase anon public key
GEMINI_API_KEY	Yes	Google AI Studio
GROQ_API_KEY	Yes	Groq console
OPENROUTER_API_KEY	Yes	OpenRouter
TAVILY_API_KEY	Yes	Tavily
SERPER_API_KEY	Yes	Serper.dev
PUBLIC_URL	Yes	Your app URL, no trailing slash — enables self-ping keep-alive
CRON_SECRET	Yes	Protects /api/tick — set the same value in cron-job.org
WEBHOOK_APP_SECRET	Recommended	Meta App Secret — enables webhook signature verification

---

Testing

node test.js

Runs the full v1.1 integration test suite against your live Supabase instance. Inserts test data, verifies all features, and cleans up after every run. No real WhatsApp messages are sent.

Test suites: Supabase connectivity (7 tables), AI intent parsing (20 cases), reminders, routines, special events, contacts, delete tasks, interval reminders, scheduler logic, usage tracking, server routes + ping shape, conversational memory, missing time UX fix, edit task/undo, WhatsApp markdown formatter, vague time defaults, recurring tasks (weekly + monthly), media handling.

---

This is the beginning of the README. Read the rest at the original. Read the full README ↗