Autopilot

API reference for the FlowCaptain Autopilot endpoint: full conversation management through a single endpoint.

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": "+4917604069001",
  "language": "en"
}

Field	Type	Required	Description
`calendarId`	string	Yes	Your calendar ID — identifies which calendar the request targets
`message`	string	Yes	What the caller said (max. 1000 characters).
`sessionId`	string	No	Session ID from the previous response. Leave empty or `null` for a new conversation.
`callerIdNumber`	string	No	Caller's phone number (from telephony, not spoken by the caller).
`context`	string	No	Additional context for the conversation (max. 500 characters).
`language`	string	No	Language hint: `"de"` or `"en"`. Default: `"de"`.

calendarId is required on every Autopilot call — without it, the endpoint responds with 401. You find it pre-filled under Calendar › Name › API, section 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": "ready_to_book",
  "done": false
}

Field	Type	Description
`sessionId`	string	Session ID — pass this back with every follow-up call.
`speak`	string	Text the voice bot should speak verbatim.
`phase`	string	Current conversation phase (`greeting`, `booking`, `cancelling`, `rescheduling`, `listing`, `callback`, or `farewell`).
`step`	string	Current step within the phase (e.g. `need_datetime`, `ready_to_book`, `done`). Informational only — drive your flow with `done`.
`done`	boolean	`true` when the conversation is complete — voice bot should hang up.
`action`	string	Most recently performed appointment action (if any, e.g. `booked`).
`data`	object	Additional structured data for the action (if any).

Conversation Flow

A typical conversation consists of multiple message pairs:

New conversation — Send message without sessionId. FlowCaptain responds with a greeting and a sessionId.
Follow-up messages — Send every subsequent message with the received sessionId. FlowCaptain maintains context.
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": "+4917604069001",
    "serviceNames": ["Initial Consultation"],
    "problemDescription": "Brakes are squeaking",
    "preferredDay": "next Wednesday",
    "preferredTimeOfDay": "morning"
  }
}

Field	Type	Description
`initialData.intent`	string	Must be `"appointment_booking"` — without this value, `initialData` is ignored.
`initialData.customerName`	string	Already known caller name.
`initialData.phoneNumber`	string	Already known phone number.
`initialData.serviceNames`	string[]	Desired services (max. 10). Names that don't exist in the calendar are skipped.
`initialData.problemDescription`	string	Description of the caller's issue.
`initialData.preferredDay`	string	Preferred day in natural language.
`initialData.preferredTimeOfDay`	string	Preferred time of day (e.g. "morning", "afternoon").

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

Status	Description
`400`	`message` is missing or empty, a field is too long, or `calendarId` is not a valid ID.
`401`	API key is missing/invalid, or `calendarId` is missing.
`403`	The calendar doesn't belong to the API key's workspace, or the `sessionId` belongs to a different calendar.
`429`	Too many requests (60 per minute per workspace).
`502`	The Google Calendar is not shared with the service account (`calendar_not_shared`).

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.