appointment-scheduler

Appointment Scheduler 📅

Automated appointment management system for service businesses.

Features

1. 예약 접수 — Parse booking requests from DM/KakaoTalk/phone (text-converted) 2. 캘린더 등록 — Auto-sync with Google Calendar / Naver Calendar 3. 충돌 감지 — Prevent double-booking 4. 리마인더 — Auto-notify customers 1 day before + 2 hours before 5. 노쇼 관리 — Track no-shows and flag repeat offenders 6. 대기 명단 — Auto-waitlist when fully booked + auto-notify on cancellation

Target Use Cases

Quick Start

1. Initialize Configuration

node /scripts/init-config.js

This creates config/appointment-scheduler.json with:

2. Process Incoming Request

From text message:

node /scripts/parse-booking.js --text "내일 오후 3시에 컷 예약 가능할까요? - 김철수 010-1234-5678"

From conversation context:

"고객이 예약 요청했어요: [message content]"

The skill will: 1. Parse date/time, service type, customer name, contact 2. Check calendar for conflicts 3. If available → book + confirm 4. If conflict → suggest alternatives or add to waitlist

3. Manual Booking

node /scripts/book.js \
  --date "2026-02-20" \
  --time "15:00" \
  --duration 60 \
  --service "컷" \
  --customer "김철수" \
  --phone "010-1234-5678"

4. Check Schedule

# Today's appointments
node /scripts/check-schedule.js --date today
Specific date
node /scripts/check-schedule.js --date 2026-02-20
This week
node /scripts/check-schedule.js --week

5. Send Reminders

Manual trigger:

node /scripts/send-reminders.js

Auto-trigger via cron:

# Daily at 9:00 AM - send 1-day-before reminders
0 9 * * * node /path/to/skills/appointment-scheduler/scripts/send-reminders.js --type day-before
Hourly - send 2-hour-before reminders
0 * * * * node /path/to/skills/appointment-scheduler/scripts/send-reminders.js --type hour-before

6. Handle No-Shows

# Mark customer as no-show
node /scripts/mark-noshow.js --booking-id abc123
Check no-show stats
node /scripts/noshow-report.js
Flag repeat offenders (3+ no-shows)
node /scripts/noshow-report.js --flag-repeat

7. Waitlist Management

# Add to waitlist
node /scripts/waitlist.js add \
  --date "2026-02-20" \
  --time "15:00" \
  --customer "이영희" \
  --phone "010-9999-8888"
Check waitlist
node /scripts/waitlist.js list --date 2026-02-20
Notify waitlist on cancellation
node /scripts/waitlist.js notify --booking-id abc123

Data Storage

Location: workspace/data/appointments/

data/appointments/
  bookings/
    2026-02-20.json          # Daily booking records
  waitlist/
    2026-02-20.json          # Daily waitlist
  noshow/
    history.json             # No-show records
    flagged-customers.json   # Repeat offenders
  reminders/
    sent.json                # Reminder delivery log

Calendar Integration

Google Calendar

1. Enable Google Calendar API 2. Download OAuth credentials → save as ~/.secrets/google-calendar-credentials.json 3. First run will prompt browser auth 4. Refresh token saved to ~/.secrets/google-calendar-token.json

Sync script:

node /scripts/sync-google-calendar.js

Naver Calendar

Uses Naver Calendar API (if available) or browser automation fallback.

Config: Add Naver account to config/appointment-scheduler.json

Booking Request Parsing

The parser handles natural language like:

Extracted fields:

Conflict Detection

Before confirming: 1. Check existing bookings in date/time slot 2. Calculate service duration overlap 3. If conflict → suggest nearest available slot 4. If fully booked → offer waitlist

Buffer time: Configurable in config (default: 10 min between appointments)

Reminder System

Default timing:

Delivery channels (auto-detect from customer contact):

Customization: Edit timing in config/appointment-scheduler.json

No-Show Management

Tracking:

Auto-flag policy (default):

Query:

# Check customer history
node /scripts/noshow-report.js --customer "김철수"
Monthly stats
node /scripts/noshow-report.js --month 2026-02

Waitlist Auto-Notify

When a booking is cancelled: 1. Find waitlist entries for same date/time 2. Auto-send notification: "예약 자리가 났습니다! 원하시면 예약 가능합니다" 3. First-come-first-served → confirm via reply 4. Auto-book if confirmed within 30 min

Voice Integration

Supports phone call → text → booking flow: 1. Receive call transcript (via STT tool) 2. Parse booking request 3. Confirm availability 4. Send SMS confirmation

Hook Integration

pre-hook: Before booking → check business hours, service availability post-hook: After booking → send confirmation, update calendar, log event conflict-hook: On conflict → trigger alternative suggestion or waitlist flow

Event Bus Integration

Location: events/appointment-YYYY-MM-DD.json

{
  "timestamp": "2026-02-18T15:30:00Z",
  "event": "booking_created",
  "booking_id": "abc123",
  "customer": "김철수",
  "date": "2026-02-20",
  "time": "15:00",
  "service": "컷"
}

Cron Setup

Recommended cron jobs:

# Send day-before reminders at 9 AM
0 9 * * * node /path/to/skills/appointment-scheduler/scripts/send-reminders.js --type day-before
Send 2-hour reminders every hour
0 * * * * node /path/to/skills/appointment-scheduler/scripts/send-reminders.js --type hour-before
Sync calendar every 30 min
*/30 * * * * node /path/to/skills/appointment-scheduler/scripts/sync-google-calendar.js
Daily no-show report at 8 PM
0 20 * * * node /path/to/skills/appointment-scheduler/scripts/noshow-report.js --daily

Configuration Template

Location: config/appointment-scheduler.json

{
  "business_name": "MUFI 포토부스",
  "business_hours": {
    "monday": { "open": "10:00", "close": "20:00" },
    "tuesday": { "open": "10:00", "close": "20:00" },
    "wednesday": { "open": "10:00", "close": "20:00" },
    "thursday": { "open": "10:00", "close": "20:00" },
    "friday": { "open": "10:00", "close": "22:00" },
    "saturday": { "open": "10:00", "close": "22:00" },
    "sunday": { "open": "12:00", "close": "18:00" }
  },
  "services": {
    "포토촬영": { "duration": 30, "buffer": 10 },
    "컷": { "duration": 60, "buffer": 10 },
    "펌": { "duration": 120, "buffer": 15 },
    "염색": { "duration": 90, "buffer": 15 }
  },
  "reminders": {
    "day_before": { "enabled": true, "time": "09:00" },
    "hour_before": { "enabled": true, "hours": 2 }
  },
  "noshow_policy": {
    "grace_period_min": 15,
    "flag_threshold": 3,
    "require_deposit_when_flagged": true
  },
  "calendar": {
    "google": {
      "enabled": true,
      "calendar_id": "primary"
    },
    "naver": {
      "enabled": false
    }
  }
}

Troubleshooting

| Issue | Solution | |-------|----------| | 예약 파싱 실패 | Check parse-booking.js output, add custom patterns | | 캘린더 동기화 에러 | Verify OAuth credentials, check token expiry | | 리마인더 미발송 | Check cron job status, verify message tool config | | 중복 예약 발생 | Ensure conflict detection enabled, check buffer time | | 대기 명단 알림 실패 | Check customer contact info, verify message channel |

Advanced Usage

Custom Service Types

Edit config/appointment-scheduler.json:

"services": {
  "신규서비스": { "duration": 45, "buffer": 10 }
}

Block Off Time

# Mark time slot as unavailable
node /scripts/block-time.js \
  --date "2026-02-20" \
  --start "12:00" \
  --end "13:00" \
  --reason "점심시간"

Bulk Import

# Import from CSV
node /scripts/import-bookings.js --file bookings.csv

Export Reports

# Monthly booking report
node /scripts/export-report.js --month 2026-02 --format json
No-show analysis
node /scripts/noshow-report.js --month 2026-02 --export csv

Learned Lessons

> 🐧 Built by 무펭이 — 무펭이즘(Mupengism) 생태계 스킬

1. Initialize Configuration

node /scripts/init-config.js

This creates config/appointment-scheduler.json with:

2. Process Incoming Request

From text message:

node /scripts/parse-booking.js --text "내일 오후 3시에 컷 예약 가능할까요? - 김철수 010-1234-5678"

From conversation context:

"고객이 예약 요청했어요: [message content]"

The skill will: 1. Parse date/time, service type, customer name, contact 2. Check calendar for conflicts 3. If available → book + confirm 4. If conflict → suggest alternatives or add to waitlist

3. Manual Booking

node /scripts/book.js \
  --date "2026-02-20" \
  --time "15:00" \
  --duration 60 \
  --service "컷" \
  --customer "김철수" \
  --phone "010-1234-5678"

4. Check Schedule

# Today's appointments
node /scripts/check-schedule.js --date today
Specific date
node /scripts/check-schedule.js --date 2026-02-20
This week
node /scripts/check-schedule.js --week

5. Send Reminders

Manual trigger:

node /scripts/send-reminders.js

Auto-trigger via cron:

# Daily at 9:00 AM - send 1-day-before reminders
0 9 * * * node /path/to/skills/appointment-scheduler/scripts/send-reminders.js --type day-before
Hourly - send 2-hour-before reminders
0 * * * * node /path/to/skills/appointment-scheduler/scripts/send-reminders.js --type hour-before

6. Handle No-Shows

# Mark customer as no-show
node /scripts/mark-noshow.js --booking-id abc123
Check no-show stats
node /scripts/noshow-report.js
Flag repeat offenders (3+ no-shows)
node /scripts/noshow-report.js --flag-repeat

7. Waitlist Management

# Add to waitlist
node /scripts/waitlist.js add \
  --date "2026-02-20" \
  --time "15:00" \
  --customer "이영희" \
  --phone "010-9999-8888"
Check waitlist
node /scripts/waitlist.js list --date 2026-02-20
Notify waitlist on cancellation
node /scripts/waitlist.js notify --booking-id abc123

| Issue | Solution | |-------|----------| | 예약 파싱 실패 | Check parse-booking.js output, add custom patterns | | 캘린더 동기화 에러 | Verify OAuth credentials, check token expiry | | 리마인더 미발송 | Check cron job status, verify message tool config | | 중복 예약 발생 | Ensure conflict detection enabled, check buffer time | | 대기 명단 알림 실패 | Check customer contact info, verify message channel |