WellAI Bot — Smart Health Connect

A WhatsApp-based health assistant for clinic appointment booking, cancellation, rescheduling, and FAQs. Supports English, Mandarin, and Bahasa Melayu.

What you need before starting

1. WhatsApp Cloud API credentials

From the Meta Developer Dashboard:

• Verify token — any string you choose; used to verify the webhook
• Access token — from your WhatsApp Business app
• Phone number ID — from your WhatsApp Business phone number settings

2. Groq API key

Sign up at console.groq.com and create an API key.

3. Clinic configuration

Create config/clinics.json with your clinic details:

[
  {
    "id": "clinic_001",
    "name": "Central Clinic",
    "address": "123 Main St",
    "phone": "+601234567890",
    "email": "clinic@example.com",
    "working_hours": {
      "Monday":    { "start": "09:00", "end": "17:00" },
      "Tuesday":   { "start": "09:00", "end": "17:00" },
      "Wednesday": { "start": "09:00", "end": "17:00" },
      "Thursday":  { "start": "09:00", "end": "17:00" },
      "Friday":    { "start": "09:00", "end": "17:00" }
    },
    "consultant_whatsapp_ids": ["601234567890"],
    "google_calendar_id": "primary"
  }
]

4. Google Calendar service account key (optional)

Without this the bot still works — appointments are saved but not synced to Google Calendar and reminders are not sent.

To enable Google Calendar:

1. Go to Google Cloud Console, create a project, and enable the Google Calendar API.
2. Go to APIs & Services → Credentials → Create Credentials → Service Account, create one, then go to its Keys tab and download a JSON key.
3. Save the file as config/service-account-key.json.
4. Share each clinic's Google Calendar with the service account email (set permission to Make changes to events).

To find a clinic's calendar ID: open Google Calendar, click the calendar's ⋮ menu → Settings and sharing → scroll to Integrate calendar.

Running the app

Step 1 — Clone

git clone --recurse-submodules <repository-url>
cd wellai-bot

Step 2 — Configure environment

cp .env.example .env

Fill in .env:

WHATSAPP_VERIFY_TOKEN=your_token
WHATSAPP_ACCESS_TOKEN=your_access_token
WHATSAPP_PHONE_NUMBER_ID=your_phone_number_id
GROQ_API_KEY=your_groq_key

# Optional — change these if the default ports conflict with something on your machine
WHATSAPP_HTTP_PORT=5080
MONGO_PORT=27017
POSTGRES_PORT=5432

Step 3 — Add clinic config

Create a config/ folder at the root of this repo (it is gitignored and never pushed):

mkdir config

Drop clinics.json (and optionally service-account-key.json) into it.

Step 4 — Start

docker compose up --build

Step 5 — Expose the webhook

The WhatsApp Cloud API needs a public HTTPS URL. Use ngrok:

ngrok http 5080

Copy the generated URL and go to your Meta Developer Dashboard:

• Use cases → Customize → Step 2 → Configure Webhooks
  • Callback URL: https://<ngrok-url>/webhook
  • Verify token: same value as WHATSAPP_VERIFY_TOKEN
• Subscribe to the messages webhook field.

Useful commands

# Check if all services are running
docker compose ps

# View logs
docker compose logs -f
docker compose logs -f bot
docker compose logs -f scheduler

# Stop
docker compose down

# Stop and wipe all data
docker compose down -v