# Implementation Plan: WhatsApp & Agent Defaults for New Users

## Overview
Automatically configure WhatsApp sessions, AI model settings, and appointment agents when new users register.

## Requirements Summary
1. **WhatsApp Session**: Auto-create session with Auto-Reply enabled, GPT-3.5-turbo as default AI model
2. **Assistant Agent**: Create default agent for appointments using company name as agent name
3. **Agent Capabilities**: Enable Appointments and WhatsApp in agent prompts settings

---

## Current Architecture Analysis

### User Creation Flow (`/server/routes/auth-routes.ts`)
- POST `/api/auth/register` creates user, assigns plan, initializes credits
- No automatic WhatsApp session or agent creation currently

### WhatsApp System (`/plugins/whatsapp-integration/`)
- **Sessions**: `whatsappSessions` table stores session data
- **Settings**: `whatsappSettings` table stores:
  - `defaultAiModel` (currently defaults to "gpt-4o")
  - `autoReplyEnabled` (currently defaults to `false`)
  - `defaultAgentId` (reference to agent)

### Agents System (`/server/routes/agent-routes.ts`)
- **Agent Types**: `incoming` (conversational AI) or `flow` (campaign)
- **Agent Schema Fields**:
  - `appointmentBookingEnabled` (default: `false`)
  - `messagingWhatsappEnabled` (default: `false`)
  - `llmModel` (default: "gpt-4o-mini")

### Agent Templates (`seed-agent-templates.ts`)
- Pre-configured templates available including "Appointment Setter"
- Can be leveraged for default agent creation

---

## Implementation Strategy

### Phase 1: Database & Schema Preparation

#### 1.1 Add Default Configuration Fields to User Schema
**File**: `/shared/schema.ts`

Add optional default configuration fields:
```typescript
export const users = pgTable("users", {
  // ... existing fields
  
  // New fields for default configuration
  autoCreateWhatsappSession: boolean("auto_create_whatsapp_session").default(true),
  autoCreateAppointmentAgent: boolean("auto_create_appointment_agent").default(true),
  defaultCompanyName: text("default_company_name"), // for agent naming
});
```

#### 1.2 Create Migration
Generate and run Drizzle migration:
```bash
npm run db:generate
npm run db:migrate
```

---

### Phase 2: Service Layer - User Onboarding Service

#### 2.1 Create New Service: User Onboarding Service
**File**: `/server/services/user-onboarding-service.ts`

Create a dedicated service to handle post-registration setup:

```typescript
import { storage } from "../storage";
import { whatsappService } from "../../plugins/whatsapp-integration/server/whatsapp-service";
import { agentService } from "../services/agent-service";

interface OnboardingConfig {
  userId: string;
  companyName?: string;
  createWhatsappSession?: boolean;
  createAppointmentAgent?: boolean;
}

export class UserOnboardingService {
  /**
   * Complete user onboarding with WhatsApp and Agent setup
   */
  async completeOnboarding(config: OnboardingConfig): Promise<{
    whatsappSession?: any;
    appointmentAgent?: any;
    errors?: string[];
  }> {
    const result: any = {};
    const errors: string[] = [];

    try {
      // Step 1: Create WhatsApp Session (if enabled)
      if (config.createWhatsappSession !== false) {
        result.whatsappSession = await this.createDefaultWhatsappSession(config.userId);
      }

      // Step 2: Create Appointment Agent (if enabled)
      if (config.createAppointmentAgent !== false) {
        result.appointmentAgent = await this.createDefaultAppointmentAgent(
          config.userId,
          config.companyName || "Assistant"
        );
      }

      // Step 3: Link Agent to WhatsApp Settings
      if (result.whatsappSession && result.appointmentAgent) {
        await this.linkAgentToWhatsapp(config.userId, result.appointmentAgent.id);
      }

    } catch (error) {
      errors.push(error.message);
      result.errors = errors;
    }

    return result;
  }

  /**
   * Create default WhatsApp session with auto-reply enabled
   */
  private async createDefaultWhatsappSession(userId: string) {
    // Create session via Evolution API
    const sessionData = {
      userId,
      sessionName: "Default Session",
      autoReplyEnabled: true,
      defaultAiModel: "gpt-3.5-turbo", // Requirement: use GPT-3.5-turbo
      defaultAiMode: "auto",
    };

    return await whatsappService.createSession(sessionData);
  }

  /**
   * Create default appointment agent
   */
  private async createDefaultAppointmentAgent(userId: string, agentName: string) {
    // Use Appointment Setter template or create custom
    const agentData = {
      userId,
      name: `${agentName} Assistant`,
      type: "incoming",
      llmModel: "gpt-3.5-turbo", // Match WhatsApp AI model
      appointmentBookingEnabled: true, // Enable appointments
      messagingWhatsappEnabled: true, // Enable WhatsApp messaging
      systemPrompt: this.getDefaultAppointmentPrompt(agentName),
      personality: "professional",
      language: "en",
    };

    return await agentService.createAgent(agentData);
  }

  /**
   * Link agent to WhatsApp settings
   */
  private async linkAgentToWhatsapp(userId: string, agentId: string) {
    await storage.updateWhatsappSettings(userId, {
      defaultAgentId: agentId,
    });
  }

  /**
   * Get default system prompt for appointment agent
   */
  private getDefaultAppointmentPrompt(companyName: string): string {
    return `You are ${companyName}'s virtual assistant. Your primary role is to:
    
1. Schedule and manage appointments
2. Answer frequently asked questions
3. Provide professional customer service
4. Handle appointment confirmations and reminders

Always be polite, efficient, and accurate when scheduling appointments.`;
  }
}

export const userOnboardingService = new UserOnboardingService();
```

---

### Phase 3: Update Registration Flow

#### 3.1 Modify Auth Routes
**File**: `/server/routes/auth-routes.ts`

Update the `/api/auth/register` endpoint:

```typescript
import { userOnboardingService } from "../services/user-onboarding-service";

// In POST /api/auth/register handler
router.post("/register", async (req, res) => {
  // ... existing validation and user creation code ...

  // Create user
  const user = await storage.createUser(userData);

  // NEW: Complete onboarding (async - don't block registration)
  setImmediate(async () => {
    try {
      await userOnboardingService.completeOnboarding({
        userId: user.id,
        companyName: user.company || user.name,
        createWhatsappSession: true,
        createAppointmentAgent: true,
      });
    } catch (error) {
      console.error("Onboarding error:", error);
      // Don't fail registration if onboarding fails
    }
  });

  // ... rest of existing response code ...
});
```

---

### Phase 4: WhatsApp Settings Service Update

#### 4.1 Update WhatsApp Settings Defaults
**File**: `/plugins/whatsapp-integration/server/whatsapp-settings-service.ts`

Add method to ensure default settings exist:

```typescript
/**
 * Ensure WhatsApp settings exist for user with correct defaults
 */
async ensureDefaultSettings(userId: string): Promise<WhatsappSettings> {
  const existing = await this.getSettings(userId);
  
  if (existing) {
    // Update if missing critical defaults
    if (existing.defaultAiModel === null || existing.defaultAiModel === undefined) {
      await this.updateSettings(userId, {
        defaultAiModel: "gpt-3.5-turbo",
        autoReplyEnabled: true,
      });
    }
    return existing;
  }

  // Create new settings with defaults
  return await this.createSettings({
    userId,
    defaultAiModel: "gpt-3.5-turbo",
    autoReplyEnabled: true,
    defaultAiMode: "auto",
  });
}
```

---

### Phase 5: Admin Panel Updates

#### 5.1 Add Onboarding Configuration to Admin Settings
**File**: `/server/routes/admin/global-settings-routes.ts`

Add new global settings for onboarding control:

```typescript
// Add to global settings
"onboarding_auto_create_whatsapp": true,
"onboarding_auto_create_agent": true,
"onboarding_default_ai_model": "gpt-3.5-turbo",
"onboarding_agent_template": "appointment-setter",
```

#### 5.2 Update Admin Frontend
**File**: `/client/src/pages/admin/AgentPromptsPage.tsx` (if exists)

Add ability to configure defaults via admin panel at `/admin?tab=agent-prompts`:

- Toggle for automatic agent creation
- Toggle for automatic WhatsApp session creation
- Default AI model selection
- Agent template selection

---

### Phase 6: Testing & Validation

#### 6.1 Unit Tests
**File**: `/server/services/__tests__/user-onboarding-service.test.ts`

Test cases:
- WhatsApp session creation with correct defaults
- Agent creation with appointment/WhatsApp enabled
- Error handling (registration succeeds even if onboarding fails)
- Agent-WhatsApp linking

#### 6.2 Integration Tests
Test full registration flow:
1. Register new user
2. Verify WhatsApp session exists
3. Verify agent exists
4. Verify agent has appointments/WhatsApp enabled
5. Verify WhatsApp settings reference agent

#### 6.3 Manual Testing Checklist
- [ ] New registration creates WhatsApp session
- [ ] WhatsApp session has Auto-Reply = true
- [ ] WhatsApp session has AI Model = gpt-3.5-turbo
- [ ] New registration creates appointment agent
- [ ] Agent name includes company/user name
- [ ] Agent has appointmentBookingEnabled = true
- [ ] Agent has messagingWhatsappEnabled = true
- [ ] WhatsApp settings defaultAgentId links to agent
- [ ] Registration completes successfully even if onboarding fails

---

## File Changes Summary

### New Files
1. `/server/services/user-onboarding-service.ts` - Main onboarding service
2. `/server/services/__tests__/user-onboarding-service.test.ts` - Unit tests

### Modified Files
1. `/shared/schema.ts` - Add onboarding configuration fields
2. `/server/routes/auth-routes.ts` - Integrate onboarding into registration
3. `/plugins/whatsapp-integration/server/whatsapp-settings-service.ts` - Add ensureDefaultSettings
4. `/server/routes/admin/global-settings-routes.ts` - Add onboarding settings
5. `/client/src/pages/admin/AgentPromptsPage.tsx` - Admin UI updates

---

## Rollout Strategy

### Phase 1: Backend Implementation (Week 1)
- Implement service layer
- Update registration flow
- Add database migration

### Phase 2: Admin Panel (Week 2)
- Add admin controls
- Update global settings

### Phase 3: Testing (Week 2-3)
- Unit tests
- Integration tests
- Manual testing

### Phase 4: Deployment (Week 3)
- Staging deployment
- Production deployment
- Monitor for issues

---

## Risk Mitigation

### Potential Issues & Solutions

1. **Evolution API Rate Limits**
   - Solution: Queue session creation if rate limited
   - Retry logic with exponential backoff

2. **User Registration Performance**
   - Solution: Async onboarding (non-blocking)
   - Don't fail registration if onboarding fails

3. **Existing Users**
   - Solution: Only apply to new registrations
   - Optional: Admin tool to retroactively apply

4. **Plan Limits**
   - Solution: Check plan limits before creating
   - Graceful degradation if limits reached

---

## Success Metrics

- 100% of new users have WhatsApp session configured
- 100% of new users have appointment agent created
- 0% increase in registration failure rate
- < 2 second additional processing time for registration (async)

---

## Future Enhancements

1. Allow users to opt-out during registration
2. Multi-language agent prompts
3. Industry-specific agent templates
4. Onboarding customization per plan tier
5. Analytics on onboarding completion rates