> ## Documentation Index
> Fetch the complete documentation index at: https://developer.meetergo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Routing & Round-Robin

> Distribute bookings across team members automatically

Route incoming bookings to the right team member using queues and round-robin distribution.

## Overview

meetergo supports several routing strategies:

| Strategy               | Description                           | Use Case                   |
| ---------------------- | ------------------------------------- | -------------------------- |
| **Round-Robin**        | Distribute evenly across team members | Sales teams, support       |
| **Weighted**           | Assign based on capacity/experience   | Mixed seniority teams      |
| **Availability-Based** | Route to whoever is free              | Maximum booking efficiency |

## Queues

Queues manage how bookings are distributed across multiple hosts for a meeting type.

### Get Queues

```javascript theme={null}
// Get all queues for a workspace
const response = await fetch(
  `https://api.meetergo.com/v4/queue/workspace/${workspaceId}`,
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'x-meetergo-api-user-id': userId
    }
  }
);

const queues = await response.json();
```

### Get Queue Details

```javascript theme={null}
const response = await fetch(
  `https://api.meetergo.com/v4/queue/${queueId}`,
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'x-meetergo-api-user-id': userId
    }
  }
);

const queue = await response.json();
// Returns queue with user assignments and capacities
```

### Update Queue

Modify user assignments or capacities:

```javascript theme={null}
await fetch(`https://api.meetergo.com/v4/queue/meeting-type/${meetingTypeId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
    'x-meetergo-api-user-id': userId
  },
  body: JSON.stringify({
    users: [
      { userId: 'user-1-uuid', weight: 2 },  // Gets 2x bookings
      { userId: 'user-2-uuid', weight: 1 },
      { userId: 'user-3-uuid', weight: 1 }
    ]
  })
});
```

### Get Next Available Host

Find who should receive the next booking:

```javascript theme={null}
const response = await fetch(
  `https://api.meetergo.com/v4/queue/${queueId}/next`,
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'x-meetergo-api-user-id': userId
    }
  }
);

const { nextHosts } = await response.json();
// Returns ordered list of hosts for next booking
```

## User Groups

Organize queue members into groups for tiered routing:

### Create User Group

```javascript theme={null}
const response = await fetch('https://api.meetergo.com/v4/queue-user-group', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
    'x-meetergo-api-user-id': userId
  },
  body: JSON.stringify({
    name: 'Senior Sales',
    queueId: queueId,
    userIds: ['user-1-uuid', 'user-2-uuid'],
    priority: 1  // Lower = higher priority
  })
});
```

### Update User Group

```javascript theme={null}
await fetch(`https://api.meetergo.com/v4/queue-user-group/${groupId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
    'x-meetergo-api-user-id': userId
  },
  body: JSON.stringify({
    name: 'Enterprise Sales',
    userIds: ['user-1-uuid', 'user-2-uuid', 'user-3-uuid']
  })
});
```

## Booking with Routing

When creating bookings, you can specify routing preferences:

### Book with Specific Host

```javascript theme={null}
await fetch('https://api.meetergo.com/v4/booking', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
    'x-meetergo-api-user-id': userId
  },
  body: JSON.stringify({
    meetingTypeId: meetingTypeId,
    start: '2024-01-15T14:00:00Z',
    hostIds: ['specific-host-uuid'],  // Force specific host
    attendee: {
      email: 'client@example.com',
      fullname: 'Client Name'
    }
  })
});
```

### Book with Queue (Round-Robin)

```javascript theme={null}
// Get availability with queue routing
const availabilityResponse = await fetch(
  `https://api.meetergo.com/v4/booking-availability?` + new URLSearchParams({
    meetingTypeId: meetingTypeId,
    start: '2024-01-15',
    end: '2024-01-22',
    queueId: queueId  // Use queue for host selection
  }),
  { headers }
);

const { availableSlots } = await availabilityResponse.json();

// Book - host will be assigned by queue
await fetch('https://api.meetergo.com/v4/booking', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    meetingTypeId: meetingTypeId,
    start: availableSlots[0].start,
    // No hostIds - queue assigns automatically
    attendee: {
      email: 'client@example.com',
      fullname: 'Client Name'
    }
  })
});
```

## Handoffs

Transfer bookings between team members:

### Handoff to User

```javascript theme={null}
await fetch('https://api.meetergo.com/v4/handoff/appointment', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
    'x-meetergo-api-user-id': userId
  },
  body: JSON.stringify({
    appointmentId: appointmentId,
    targetUserId: 'new-host-uuid'
  })
});
```

### Get Available Handoff Options

```javascript theme={null}
const response = await fetch(
  `https://api.meetergo.com/v4/handoff/available-handoffs?appointmentId=${appointmentId}`,
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'x-meetergo-api-user-id': userId
    }
  }
);

const { users, queues } = await response.json();
// Returns available users and queues for handoff
```

### Bulk Handoff

Transfer multiple appointments at once (e.g., when someone goes on vacation):

```javascript theme={null}
const response = await fetch('https://api.meetergo.com/v4/handoff/bulk', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
    'x-meetergo-api-user-id': userId
  },
  body: JSON.stringify({
    fromUserIds: ['user-going-on-vacation'],
    targetUserId: 'backup-user-uuid',
    startDate: '2024-12-20',
    endDate: '2024-12-31'
  })
});

const { handedOff, failed } = await response.json();
console.log(`Transferred ${handedOff} appointments`);
```

## Common Patterns

### Sales Team Routing

```javascript theme={null}
// Create a queue with weighted distribution
// Senior reps get more leads

const salesQueue = {
  meetingTypeId: demoMeetingTypeId,
  users: [
    { userId: seniorRep1, weight: 3 },  // 30% of leads
    { userId: seniorRep2, weight: 3 },  // 30% of leads
    { userId: juniorRep1, weight: 2 },  // 20% of leads
    { userId: juniorRep2, weight: 2 }   // 20% of leads
  ]
};
```

### Support Team with Tiers

```javascript theme={null}
// Tier 1 handles first, overflow to Tier 2

// Create Tier 1 group (priority 1)
await createUserGroup({
  name: 'Tier 1 Support',
  queueId: supportQueueId,
  userIds: [support1, support2, support3],
  priority: 1
});

// Create Tier 2 group (priority 2)
await createUserGroup({
  name: 'Tier 2 Support',
  queueId: supportQueueId,
  userIds: [seniorSupport1, seniorSupport2],
  priority: 2
});
```

### Coverage During Absence

```javascript theme={null}
// When team member goes on vacation
async function setupVacationCoverage(userId, backupUserId, startDate, endDate) {
  // 1. Bulk handoff existing appointments
  await fetch('https://api.meetergo.com/v4/handoff/bulk', {
    method: 'POST',
    headers,
    body: JSON.stringify({
      fromUserIds: [userId],
      targetUserId: backupUserId,
      startDate,
      endDate
    })
  });

  // 2. Add availability exception
  await fetch('https://api.meetergo.com/availability-exception/user', {
    method: 'POST',
    headers: { ...headers, 'x-meetergo-api-user-id': userId },
    body: JSON.stringify({
      startDate,
      endDate,
      isAvailable: false,
      name: 'Vacation'
    })
  });
}
```

## Best Practices

<Check>
  **Balance workloads** - Use weights to match capacity and experience
</Check>

<Check>
  **Set up backup coverage** - Always have handoff targets defined
</Check>

<Check>
  **Monitor distribution** - Track booking counts per team member
</Check>

<Check>
  **Use groups for tiers** - Organize by skill level or availability
</Check>

## Next Steps

<CardGroup cols={2}>
  <Card title="Bookings" icon="calendar-check" href="/developer-docs/core-concepts/bookings">
    Create and manage bookings
  </Card>

  <Card title="Availability" icon="clock" href="/developer-docs/core-concepts/availability">
    Configure team availability
  </Card>
</CardGroup>