> ## 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.

# Voice AI Bot Integration

> Build a voice assistant that books appointments using meetergo API

Integrate meetergo with voice AI platforms like Vapi, Retell, or custom voice bots to enable phone-based appointment booking.

## Overview

A voice AI bot can use meetergo's API to:

1. Check available time slots in real-time
2. Book appointments without requiring an email address
3. Provide instant confirmation to callers

```mermaid theme={null}
sequenceDiagram
    participant Caller
    participant Voice AI
    participant meetergo API

    Caller->>Voice AI: "I'd like to book an appointment"
    Voice AI->>meetergo API: GET /v4/booking-availability
    meetergo API-->>Voice AI: Available time slots
    Voice AI->>Caller: "I have Monday at 2pm or Tuesday at 10am"
    Caller->>Voice AI: "Tuesday at 10am works"
    Voice AI->>meetergo API: POST /v4/booking
    meetergo API-->>Voice AI: Booking confirmed
    Voice AI->>Caller: "You're all set for Tuesday at 10am!"
```

## Prerequisites

* meetergo account with API access enabled
* API key from [my.meetergo.com/admin/api-keys](https://my.meetergo.com/admin/api-keys)
* A meeting type created in your meetergo dashboard

## Setup

### 1. Get Your Meeting Type ID

1. Go to your meetergo dashboard
2. Navigate to **Meeting Types**
3. Click on the meeting type you want to use for voice bookings
4. Copy the ID from the URL: `https://my.meetergo.com/meeting-types/{meetingTypeId}/edit`

### 2. Enable Phone-Only Bookings

By default, bookings require an attendee email. For voice bots, enable phone-only bookings.

**Option A — Dashboard UI:**

1. Open the meeting type in your dashboard
2. Go to **Advanced** → **Core Booking Settings**
3. Toggle on **Allow phone-only booking**
4. Save

**Option B — API:**

```bash theme={null}
curl -X PATCH "https://api.meetergo.com/v4/meeting-type/{meetingTypeId}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-meetergo-api-user-id: YOUR_USER_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "meetingOptions": {
      "allowPhoneOnlyBooking": true
    }
  }'
```

<Info>
  With `allowPhoneOnlyBooking` enabled, you can create bookings using just the caller's phone number—no email required. Email bookings via the standard booking page continue to work on the same meeting type.
</Info>

### 3. Set Up SMS Confirmation (Optional)

Since phone-only bookings have no email address, email confirmations are automatically skipped. To send an SMS confirmation to the caller instead, set up a Workflow:

1. Open the meeting type → **Workflows**
2. Create a workflow with trigger **Booking Confirmation**
3. Set the action to **Send SMS to attendee**
4. Customize the message content per language
5. Save

The workflow fires for all bookings on this meeting type. Callers who book via voice bot receive the SMS; web bookers receive the standard email — the same meeting type handles both.

### 4. Get Your User ID

Retrieve your user ID for API requests:

```bash theme={null}
curl -X GET "https://api.meetergo.com/v4/user/me" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## API Endpoints for Voice Bots

Your voice AI needs two main API calls as LLM tools:

### 1. Get Available Time Slots

Fetch available booking windows for the meeting type:

```bash theme={null}
curl -X GET "https://api.meetergo.com/v4/booking-availability?meetingTypeId={meetingTypeId}&start=2024-01-15&end=2024-01-22" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-meetergo-api-user-id: YOUR_USER_ID"
```

**Response:**

```json theme={null}
{
  "timezone": "Europe/Berlin",
  "timeframes": [
    { "start": "2024-01-15T08:00:00.000Z", "end": "2024-01-15T16:00:00.000Z" }
  ],
  "dates": [
    {
      "date": "2024-01-15",
      "spots": [
        { "startTime": "2024-01-15T14:00:00.000+01:00" },
        { "startTime": "2024-01-15T14:30:00.000+01:00" }
      ]
    },
    {
      "date": "2024-01-16",
      "spots": [
        { "startTime": "2024-01-16T10:00:00.000+01:00" },
        { "startTime": "2024-01-16T10:30:00.000+01:00" }
      ]
    }
  ],
  "earliestAvailableDate": "2024-01-15"
}
```

### 2. Book an Appointment

Create a booking with the caller's information:

```bash theme={null}
curl -X POST "https://api.meetergo.com/v4/booking" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-meetergo-api-user-id: YOUR_USER_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "meetingTypeId": "{meetingTypeId}",
    "start": "2024-01-16T10:00:00Z",
    "phoneOnlyBooking": true,
    "icsDescription": "Call summary: Customer wants to discuss enterprise pricing.",
    "attendee": {
      "fullname": "John Doe",
      "phone": "+4915123456789",
      "notes": {
        "utm_source": "voice_bot"
      }
    }
  }'
```

You can use `icsDescription` to pass a conversation summary into the calendar invite, and `notes` to pass UTM parameters for CRM tracking. See [Create Booking](/api-reference/bookings/create-booking) for all available fields.

<Note>
  Both conditions must be met for phone-only booking: `phoneOnlyBooking: true` in the request body AND `allowPhoneOnlyBooking` enabled on the meeting type. When both are set, you can omit the `email` field and only provide the `phone` number.
</Note>

**Response:**

```json theme={null}
{
  "appointmentId": "booking-uuid",
  "secret": "secret-token-xyz"
}
```

## LLM Tool Definitions

Configure these tools in your voice AI platform:

### Tool 1: Check Availability

```json theme={null}
{
  "name": "check_availability",
  "description": "Check available appointment times for the next 7 days",
  "parameters": {
    "type": "object",
    "properties": {
      "startDate": {
        "type": "string",
        "description": "Start date in YYYY-MM-DD format"
      },
      "endDate": {
        "type": "string",
        "description": "End date in YYYY-MM-DD format"
      }
    },
    "required": ["startDate", "endDate"]
  }
}
```

### Tool 2: Book Appointment

```json theme={null}
{
  "name": "book_appointment",
  "description": "Book an appointment at a specific time",
  "parameters": {
    "type": "object",
    "properties": {
      "startTime": {
        "type": "string",
        "description": "Appointment start time in ISO 8601 format"
      },
      "callerName": {
        "type": "string",
        "description": "Full name of the caller"
      },
      "callerPhone": {
        "type": "string",
        "description": "Phone number of the caller"
      }
    },
    "required": ["startTime", "callerName", "callerPhone"]
  }
}
```

## Example Implementation

Here's a Node.js implementation for handling voice bot requests:

```javascript theme={null}
const express = require('express');
const app = express();
app.use(express.json());

const MEETERGO_API_KEY = process.env.MEETERGO_API_KEY;
const MEETERGO_USER_ID = process.env.MEETERGO_USER_ID;
const MEETING_TYPE_ID = process.env.MEETING_TYPE_ID;

const headers = {
  'Authorization': `Bearer ${MEETERGO_API_KEY}`,
  'x-meetergo-api-user-id': MEETERGO_USER_ID,
  'Content-Type': 'application/json'
};

// Tool: Check availability
app.post('/tools/check-availability', async (req, res) => {
  const { startDate, endDate } = req.body;

  const response = await fetch(
    `https://api.meetergo.com/v4/booking-availability?` + new URLSearchParams({
      meetingTypeId: MEETING_TYPE_ID,
      start: startDate,
      end: endDate
    }),
    { headers }
  );

  const data = await response.json();

  // Format slots for voice output
  const allSlots = data.dates.flatMap(d => d.spots);
  const formattedSlots = allSlots.map(slot => {
    const date = new Date(slot.startTime);
    return {
      iso: slot.startTime,
      readable: date.toLocaleString('en-US', {
        weekday: 'long',
        month: 'long',
        day: 'numeric',
        hour: 'numeric',
        minute: '2-digit'
      })
    };
  });

  res.json({ availableSlots: formattedSlots });
});

// Tool: Book appointment
app.post('/tools/book-appointment', async (req, res) => {
  const { startTime, callerName, callerPhone } = req.body;

  const response = await fetch('https://api.meetergo.com/v4/booking', {
    method: 'POST',
    headers,
    body: JSON.stringify({
      meetingTypeId: MEETING_TYPE_ID,
      start: startTime,
      phoneOnlyBooking: true,
      attendee: {
        fullname: callerName,
        phone: callerPhone
      }
    })
  });

  if (!response.ok) {
    const error = await response.json();
    return res.status(400).json({
      success: false,
      message: 'Failed to book appointment',
      error
    });
  }

  const booking = await response.json();

  res.json({
    success: true,
    message: `Appointment confirmed`,
    bookingId: booking.appointmentId
  });
});

app.listen(3000);
```

## Voice AI Platform Integration

### Vapi

Add these as custom tools in your Vapi assistant:

```javascript theme={null}
// vapi-tools.js
export const tools = [
  {
    type: "function",
    function: {
      name: "checkAvailability",
      description: "Check available appointment slots",
      parameters: {
        type: "object",
        properties: {
          startDate: { type: "string" },
          endDate: { type: "string" }
        }
      }
    },
    server: {
      url: "https://your-server.com/tools/check-availability"
    }
  },
  {
    type: "function",
    function: {
      name: "bookAppointment",
      description: "Book an appointment",
      parameters: {
        type: "object",
        properties: {
          startTime: { type: "string" },
          callerName: { type: "string" },
          callerPhone: { type: "string" }
        }
      }
    },
    server: {
      url: "https://your-server.com/tools/book-appointment"
    }
  }
];
```

### Retell AI

Configure the tools in your Retell dashboard or via API:

```javascript theme={null}
const retellTools = [
  {
    name: "check_availability",
    description: "Get available appointment times",
    url: "https://your-server.com/tools/check-availability",
    speak_during_execution: true,
    speak_after_execution: false
  },
  {
    name: "book_appointment",
    description: "Book an appointment for the caller",
    url: "https://your-server.com/tools/book-appointment",
    speak_during_execution: true,
    speak_after_execution: true
  }
];
```

## Best Practices

<Check>
  **Enable phone-only booking** - Callers shouldn't need to provide an email
</Check>

<Check>
  **Format times for speech** - Convert ISO dates to natural language ("Tuesday at 2pm")
</Check>

<Check>
  **Limit date range** - Query 7-14 days ahead to keep responses manageable
</Check>

<Check>
  **Handle timezone** - Use the caller's timezone or ask for preference
</Check>

<Check>
  **Confirm before booking** - Always repeat the selected time before confirming
</Check>

<Warning>
  **Validate phone numbers** - Ensure phone numbers are in E.164 format (+1234567890)
</Warning>

## Sample Voice Script

Here's a sample conversation flow for your voice AI:

```
AI: "Hi! I can help you schedule an appointment. What day works best for you?"

Caller: "Do you have anything on Tuesday?"

AI: [calls check_availability]
AI: "I have openings on Tuesday at 10am, 2pm, and 4pm. Which works for you?"

Caller: "2pm sounds good"

AI: "Great! I have Tuesday at 2pm. Can I get your name?"

Caller: "John Smith"

AI: "Thanks John. I'll book that for you now."
AI: [calls book_appointment]
AI: "You're all set! Your appointment is confirmed for Tuesday at 2pm. You'll receive a confirmation shortly. Is there anything else I can help with?"
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="400 Bad Request on booking">
    * Verify `allowPhoneOnlyBooking` is enabled on your meeting type
    * Check the phone number format (use E.164: +1234567890)
    * Ensure the selected time slot is still available
  </Accordion>

  <Accordion title="No available slots returned">
    * Verify the meeting type ID is correct
    * Check that the date range is in the future
    * Ensure the host has availability configured
  </Accordion>

  <Accordion title="Authentication errors">
    * Verify your API key is correct and not expired
    * Ensure the `x-meetergo-api-user-id` header matches your user ID
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Webhooks" icon="webhook" href="/developer-docs/webhooks/overview">
    Get notified when bookings are created or cancelled
  </Card>

  <Card title="CRM Sync" icon="database" href="/developer-docs/recipes/sync-with-crm">
    Sync voice bookings to your CRM
  </Card>
</CardGroup>