backend-service/docs/MEETING_JOIN_GUIDE.md

Meeting Join Implementation Guide

Overview

This guide explains how to properly implement the meeting join functionality with personalized user information and admin differentiation.

Issues Addressed

1. Name Prepopulation: Users now join meetings with their actual name instead of "Booking ID"
2. Admin Differentiation: Admin users get special moderator privileges in the meeting
3. Personalized Links: Each user gets a personalized meeting URL with their display name

API Endpoint

GET /api/meetings/:id/link

Returns a personalized meeting link for the authenticated user.

Authentication: Required (JWT token)

Parameters:

• id (path parameter): The booking ID

Response (200 OK):

{
  "booking_id": 123,
  "meeting_url": "https://meet.jit.si/booking-123-1234567890-abc123#userInfo.displayName=\"John Doe\"",
  "display_name": "John Doe",
  "is_admin": false,
  "scheduled_at": "2024-01-15T10:00:00Z",
  "duration": 60,
  "status": "scheduled"
}

Error Responses:

• 400 Bad Request: Invalid booking ID
• 401 Unauthorized: User not authenticated
• 403 Forbidden: User doesn't have permission to access this meeting
• 404 Not Found: Booking not found or meeting link not available

Frontend Implementation

Step 1: Fetch Personalized Meeting Link

Instead of using the jitsi_room_url directly from the booking response, call the new endpoint:

// When user clicks "Join Meeting" button
async function joinMeeting(bookingId) {
  try {
    const response = await fetch(`/api/meetings/${bookingId}/link`, {
      headers: {
        'Authorization': `Bearer ${userToken}`
      }
    });
    
    if (!response.ok) {
      throw new Error('Failed to get meeting link');
    }
    
    const data = await response.json();
    
    // Open the personalized meeting URL
    window.open(data.meeting_url, '_blank');
    
    // Optionally show user info
    console.log(`Joining as: ${data.display_name}`);
    console.log(`Admin privileges: ${data.is_admin}`);
    
  } catch (error) {
    console.error('Error joining meeting:', error);
    alert('Failed to join meeting. Please try again.');
  }
}

Step 2: Update Booking Display Component

function BookingCard({ booking }) {
  const handleJoinMeeting = async () => {
    try {
      const response = await fetch(`/api/meetings/${booking.id}/link`, {
        headers: {
          'Authorization': `Bearer ${localStorage.getItem('token')}`
        }
      });
      
      const data = await response.json();
      window.open(data.meeting_url, '_blank');
    } catch (error) {
      console.error('Error:', error);
    }
  };

  return (
    <div className="booking-card">
      <h3>Booking #{booking.id}</h3>
      <p>Scheduled: {new Date(booking.scheduled_at).toLocaleString()}</p>
      <p>Duration: {booking.duration} minutes</p>
      
      {booking.status === 'scheduled' && booking.jitsi_room_url && (
        <button onClick={handleJoinMeeting}>
          Join Meeting
        </button>
      )}
    </div>
  );
}

How It Works

For Regular Users

1. User calls /api/meetings/:id/link with their JWT token
2. Backend verifies the user owns the booking
3. Backend generates a personalized Jitsi URL with the user's name:

   https://meet.jit.si/room-id#userInfo.displayName="John Doe"
   

4. User joins the meeting with their name pre-filled

For Admin Users

1. Admin calls /api/meetings/:id/link with their JWT token
2. Backend verifies admin status (can access any booking)
3. Backend generates a personalized Jitsi URL with admin privileges:

   https://meet.jit.si/room-id#userInfo.displayName="Dr. Smith"&config.startWithAudioMuted=false&config.startWithVideoMuted=false
   

4. Admin joins with moderator privileges and audio/video enabled by default

Display Name Logic

The system determines the display name in this order:

1. First Name + Last Name: If both are available
2. Email: If name fields are empty
3. Fallback: Uses email as last resort

Security Considerations

1. Authentication Required: All meeting link requests require valid JWT token
2. Authorization Check:
   • Regular users can only access their own bookings
   • Admin users can access any booking
3. No Direct URL Sharing: The personalized URL includes user-specific information
4. Token Expiration: JWT tokens expire, requiring re-authentication

Migration Notes

Existing Code

If your frontend currently uses:

// OLD WAY - Don't use this anymore
<a href={booking.jitsi_room_url} target="_blank">Join Meeting</a>

Updated Code

Change to:

// NEW WAY - Use the API endpoint
<button onClick={() => joinMeeting(booking.id)}>Join Meeting</button>

Testing

Test as Regular User

1. Login as a regular user
2. Create a booking
3. Call /api/meetings/{booking_id}/link
4. Verify the response includes your name in the URL
5. Open the URL and confirm your name appears in Jitsi

Test as Admin

1. Login as admin
2. Get any booking ID
3. Call /api/meetings/{booking_id}/link
4. Verify is_admin: true in response
5. Open the URL and confirm moderator privileges

Test Authorization

1. Try to access another user's booking as a regular user
2. Should receive 403 Forbidden error
3. Admin should be able to access any booking

Troubleshooting

Issue: Name shows as "Booking ID"

Solution: Ensure you're using the new /api/meetings/:id/link endpoint instead of the raw jitsi_room_url

Issue: Admin doesn't have moderator privileges

Solution: Verify the user's is_admin field is set to true in the database

Issue: 403 Forbidden error

Solution: Regular users can only access their own bookings. Verify the booking belongs to the authenticated user.

Issue: Meeting URL not available

Solution: The booking might not have a Jitsi room created yet. This can happen if payment hasn't been completed or if there was an error during booking creation.

Future Enhancements

Potential improvements for the future:

1. Waiting Room: Add a waiting room for participants before admin joins
2. Recording Control: Give admin ability to start/stop recording
3. Participant Limits: Enforce maximum participant limits
4. Custom Branding: Add custom Jitsi branding for the therapy practice
5. Meeting Analytics: Track join times, duration, and participant count