Add Appointment Scheduling to Any Voice Bot in 10 Minutes

What You'll Build

By the end of this tutorial, your voice bot will be able to:

1. Check if a requested time slot is free — in natural language ("next Thursday at 3 PM")
2. Book the appointment on a real Google Calendar
3. Cancel or reschedule existing appointments

This works with any voice platform that supports external API calls or MCP: Retell, Vapi, Bland, Synthflow, or your own custom setup.

Prerequisites

• A Google Calendar (the one your business uses for appointments)
• A FlowCaptain account with an API key (sk_live_...)
• Your calendar shared with FlowCaptain's service account (you'll get the email during setup)

No SDK to install. It's just HTTP requests.

Option A: REST API (works everywhere)

Step 1: Check Availability

Your voice bot captures what the caller says — "Do you have anything free Tuesday at 3?" — and sends it as-is to FlowCaptain. No date parsing needed on your side.

curl -X POST https://api.flowcaptain.ai/api/v1/check-availability \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"query": "Tuesday at 3 PM"}'

Response — slot is free:

{
  "action": "confirm",
  "success": true,
  "humanReadable": "Tuesday, 25.02 at 3:00 PM is available",
  "result": "Time is available",
  "day": "Tuesday",
  "date": "25.02",
  "time": "15:00"
}

Response — slot is taken, alternatives offered:

{
  "action": "suggest",
  "success": false,
  "humanReadable": "3:00 PM on Tuesday, 25.02 is taken. Alternatively: 2:00 PM or 4:00 PM",
  "result": "requested time not available but 2 alternative time slots available",
  "day": "Tuesday",
  "date": "25.02",
  "time1": "14:00",
  "time2": "16:00"
}

The humanReadable field is a full sentence you can feed directly to your voice bot's TTS. The action field tells your bot what to do next: confirm (offer to book), suggest (present alternatives), reject (closed/holiday), or clarify (ambiguous input).

Step 2: Book the Appointment

Once the caller confirms a time, book it:

curl -X POST https://api.flowcaptain.ai/api/v1/book-appointment \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "dateTime": "2026-02-25T15:00:00+01:00",
    "callerName": "Max Mustermann",
    "callerIdNumber": "+491761234567",
    "reason": "Consultation"
  }'

Response:

{
  "action": "booked",
  "success": true,
  "humanReadable": "Appointment confirmed: Tuesday, 25.02 at 3:00 PM",
  "result": "Appointment confirmed",
  "day": "Tuesday",
  "date": "25.02",
  "time": "15:00",
  "appointmentId": "a1b2c3d4-..."
}

The appointment is now on the Google Calendar. FlowCaptain re-checks availability before booking — no double bookings possible even if two people call at the same time.

A note on callerIdNumber: if your voice platform gives you the caller's phone number from the phone system (Retell, Vapi, and most platforms do), pass it here. It's 100% accurate — unlike a phone number the caller says out loud, which may have ASR errors. This makes cancel and reschedule lookups reliable.

Step 3: Cancel or Reschedule

# Cancel
curl -X POST https://api.flowcaptain.ai/api/v1/cancel-appointment \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "callerIdNumber": "+491761234567",
    "language": "en"
  }'

# Reschedule
curl -X POST https://api.flowcaptain.ai/api/v1/reschedule-appointment \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "callerIdNumber": "+491761234567",
    "newDateTime": "2026-02-27T10:00:00+01:00"
  }'

Cancel response:

{
  "action": "cancelled",
  "success": true,
  "humanReadable": "Appointment on Tuesday, 25.02 at 3:00 PM has been cancelled"
}

Reschedule response:

{
  "action": "rescheduled",
  "success": true,
  "humanReadable": "Appointment rescheduled: Thursday, 27.02 at 10:00 AM",
  "previousDay": "Tuesday",
  "previousDate": "25.02",
  "previousTime": "15:00"
}

FlowCaptain finds the appointment by caller ID, validates the new time against business hours and existing bookings, and moves the Google Calendar event. If the new time is taken, it suggests alternatives.

Retell Integration

Via Custom Functions

1. In your Retell agent, go to Tools → Add Custom Function
2. Create a function checkAvailability:
   • URL: https://api.flowcaptain.ai/api/v1/check-availability
   • Method: POST
   • Header: Authorization: Bearer sk_live_your_key_here
   • Parameter: checkAvail (string) — "The appointment request from the caller"

Retell sends {"args": {"checkAvail": "Tuesday at 3"}} — FlowCaptain understands both this format and the direct {"query": "..."} format.

Repeat for bookAppointment, cancelAppointment, and rescheduleAppointment.

Via MCP (recommended)

Even simpler — one URL, no function configuration:

1. Go to Tools → Add MCP
2. Enter URL: https://api.flowcaptain.ai/mcp
3. Add header: Authorization: Bearer sk_live_your_key_here
4. The four tools appear automatically

Your AI agent sees the tool descriptions, understands when to call each one, and handles the conversation flow on its own.

Other Platforms (Vapi, Bland, Synthflow)

Any platform that can make HTTP POST requests can use the REST API from Steps 1-3 above. If the platform supports MCP's Streamable HTTP transport, it can also connect to https://api.flowcaptain.ai/mcp with Accept: application/json, text/event-stream.

The Natural Language Part

You don't need to parse dates on your side. FlowCaptain handles all of these:

• "next Thursday afternoon"
• "morgen um 10" (tomorrow at 10)
• "irgendwann diese Woche" (sometime this week)
• "in 3 Tagen" (in 3 days)
• "Freitag" (Friday)

German and English are auto-detected. The response language matches the input language.

Period queries like "this week" or "next Monday to Wednesday" return the first available slot in that range. Specific queries like "Tuesday at 3" check that exact slot and offer alternatives if it's taken.

What the API Handles

• Opening hours enforcement — won't book outside business hours
• Public holiday detection — per German Bundesland (state)
• Alternative slot suggestions — spaced apart by appointment duration
• Double booking prevention — re-checks calendar before every booking
• Timezone handling — all times in the business's local timezone
• Bilingual responses — German and English, auto-detected

Summary

Both options hit the same backend. Same availability logic, same calendar, same results.

Both options hit the same backend. Same availability logic, same calendar, same results. Start with the curl commands above and go from there.