# Zoom Meeting Auto-Generation Setup

This document explains how to configure automatic Zoom meeting link generation for counselor appointments.

## Overview

When a portal manager approves a counselor appointment, the system can automatically create a Zoom meeting link if no meeting link is manually provided. This eliminates the need for manual meeting link entry.

## Prerequisites

1. A Zoom account with API access
2. Zoom Server-to-Server OAuth app credentials

## Setup Instructions

### Step 1: Create a Zoom Server-to-Server OAuth App

1. Log in to the [Zoom Marketplace](https://marketplace.zoom.us/)
2. Go to "Develop" → "Build App"
3. Select "Server-to-Server OAuth" app type
4. Fill in the app details:
   - App Name: BYRC Meeting Integration (or your preferred name)
   - Company Name: Your organization name
   - Developer Contact Information: Your email
5. Click "Create"

### Step 2: Configure App Credentials

1. In your Zoom app settings, go to the "App Credentials" tab
2. Copy the following values:
   - **Account ID** (found in the "Basic Information" section)
   - **Client ID**
   - **Client Secret**

### Step 3: Add Environment Variables

Add the following variables to your `.env` file in the backend directory:

```env
ZOOM_ACCOUNT_ID=your_account_id_here
ZOOM_CLIENT_ID=your_client_id_here
ZOOM_CLIENT_SECRET=your_client_secret_here
```

### Step 4: Activate the App

1. In your Zoom app settings, go to the "Activation" tab
2. Click "Activate your app"
3. The app will be activated for your Zoom account

## How It Works

1. When a portal manager approves an appointment:
   - If a meeting link is manually entered, it will be used
   - If the meeting link field is left empty, the system automatically:
     - Creates a Zoom meeting using the booking date and time
     - Sets the meeting topic based on the service, student, and counselor names
     - Calculates the meeting duration from the booking time slots
     - Generates and saves the meeting join URL

2. The meeting link is automatically saved to the booking record

3. Both the student and counselor receive notifications with the meeting link

## Troubleshooting

### Meeting links are not being generated

1. **Check environment variables**: Ensure all three Zoom credentials are set in your `.env` file
2. **Check logs**: Review the Laravel logs (`storage/logs/laravel.log`) for Zoom-related errors
3. **Verify Zoom app activation**: Ensure your Zoom app is activated in the Zoom Marketplace
4. **Check API permissions**: Ensure your Zoom app has permission to create meetings

### Common Error Messages

- **"Zoom credentials not configured"**: Missing or incorrect environment variables. Add ZOOM_ACCOUNT_ID, ZOOM_CLIENT_ID, and ZOOM_CLIENT_SECRET to your .env file.

- **"invalid_client"**: This means your Client ID or Client Secret is incorrect. To fix:
  1. Go to Zoom Marketplace → Your App → App Credentials tab
  2. Verify you copied the correct Client ID and Client Secret (no extra spaces)
  3. Check your .env file - make sure there are no quotes around the values:
     ```
     ZOOM_CLIENT_ID=your_client_id_here
     ZOOM_CLIENT_SECRET=your_client_secret_here
     ```
     NOT: `ZOOM_CLIENT_ID="your_client_id_here"` (no quotes!)
  4. Make sure your Zoom app is activated in the Activation tab
  5. After updating .env, restart your Laravel server/application

- **"invalid_grant"**: Your Account ID is incorrect. Verify ZOOM_ACCOUNT_ID matches the Account ID from your Zoom app's Basic Information section.

- **"Failed to get Zoom access token"**: Invalid credentials or app not activated. Check all three environment variables and ensure the app is activated.

- **"Failed to create Zoom meeting"**: API error - check Zoom app permissions. Ensure your app has permission to create meetings.

## Manual Override

If automatic generation fails or you prefer to use a different meeting platform:
- Simply enter a meeting link manually in the approval dialog
- The system will use your manually entered link instead of generating one

## Notes

- The system gracefully handles Zoom API failures - if automatic generation fails, the appointment can still be approved without a meeting link
- Meeting links can be added manually later if needed
- All Zoom API calls are logged for debugging purposes