Autopilot

Autopilot

The Autopilot endpoint handles the entire conversation. Your voice bot just forwards messages and speaks the responses — FlowCaptain takes care of greeting, appointment search, booking, cancellation, rescheduling, and farewell.

Endpoint

POST /api/v1/autopilot

Request

{
  "calendarId": "YOUR_CALENDAR_ID",
  "message": "I'd like to book an appointment next week",
  "sessionId": null,
  "callerIdNumber": "+491761234567",
  "language": "en"
}

calendarId is required on every Autopilot call — without it, the endpoint responds with 401. You find it pre-filled under Dashboard → Calendar → API → Integration Guide. Send it as a field in the JSON body. If your platform wraps the body in an envelope (e.g. Retell's args object), pass it as a URL query parameter instead — ?calendarId=YOUR_CALENDAR_ID — because the API only reads calendarId from the top-level body, the query string, or the route params, never from a nested args object.

Response

{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "speak": "Next Wednesday at 2 PM would work. Does that suit you?",
  "phase": "booking",
  "step": "confirm_time",
  "done": false
}

Conversation Flow

A typical conversation consists of multiple message pairs:

1. New conversation — Send message without sessionId. FlowCaptain responds with a greeting and a sessionId.
2. Follow-up messages — Send every subsequent message with the received sessionId. FlowCaptain maintains context.
3. End of conversation — When done: true is returned, the conversation is complete.

Sessions automatically expire after a period of inactivity. If an expired sessionId is sent, FlowCaptain starts a new conversation.

Warm Handoff

If your voice bot has already collected information before handing off to FlowCaptain (e.g. name, preferred day), you can pass it as initialData:

{
  "calendarId": "YOUR_CALENDAR_ID",
  "message": "Hello",
  "initialData": {
    "intent": "appointment_booking",
    "customerName": "Max Mustermann",
    "phoneNumber": "+491761234567",
    "serviceNames": ["Initial Consultation"],
    "problemDescription": "Brakes are squeaking",
    "preferredDay": "next Wednesday",
    "preferredTimeOfDay": "morning"
  }
}

initialData is only honored when starting a new conversation. With a warm handoff, FlowCaptain skips already-covered steps and starts directly in the booking flow.

Errors

Important for Voice Bot Platforms

• Speak verbatim: Deliver the speak content exactly — no additions or rephrasing.
• Check done: End the call when done is true.
• Persist sessionId: Store and pass it back with every follow-up call.
• No own responses: Never try to answer questions yourself — forward everything to the Autopilot.