Autopilot

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

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

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

Field	Type	Required	Description
`message`	string	Yes	What the caller said.
`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).
`language`	string	No	Language hint: `"de"` or `"en"`. Default: `"de"`.

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
}

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 (e.g. `greeting`, `booking`, `cancelling`, `farewell`).
`step`	string	Current step within the phase.
`done`	boolean	`true` when the conversation is complete — voice bot should hang up.

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:

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

Field	Type	Description
`initialData.intent`	string	Currently only `"appointment_booking"`.
`initialData.customerName`	string	Already known caller name.
`initialData.phoneNumber`	string	Already known phone number.
`initialData.serviceNames`	string[]	Desired services.
`initialData.preferredDay`	string	Preferred day in natural language.
`initialData.preferredTimeOfDay`	string	Preferred time of day (e.g. "morning", "afternoon").

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.
`401`	API key is missing or invalid.
`403`	Session belongs to a different calendar.

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.