Autopilot

API-Referenz für den FlowCaptain-Autopilot-Endpunkt: komplette Gesprächsführung über einen einzigen Endpunkt.

Autopilot

Der Autopilot-Endpunkt übernimmt die komplette Gesprächsführung. Dein Voice Bot leitet nur die Nachrichten weiter und spricht die Antworten aus — FlowCaptain kümmert sich um Begrüßung, Terminsuche, Buchung, Stornierung, Umbuchung und Verabschiedung.

Endpunkt

POST /api/v1/autopilot

Anfrage

{
  "calendarId": "YOUR_CALENDAR_ID",
  "message": "Ich hätte gerne einen Termin nächste Woche",
  "sessionId": null,
  "callerIdNumber": "+491761234567",
  "language": "de"
}

Feld	Typ	Pflicht	Beschreibung
`calendarId`	string	Ja	Deine Kalender-ID — legt fest, welchen Kalender die Anfrage betrifft
`message`	string	Ja	Was der Anrufer gesagt hat (max. 1000 Zeichen).
`sessionId`	string	Nein	Session-ID aus der vorherigen Antwort. Leer lassen oder `null` für ein neues Gespräch.
`callerIdNumber`	string	Nein	Telefonnummer des Anrufers (aus der Telefonie, nicht vom Anrufer gesprochen).
`context`	string	Nein	Zusätzlicher Kontext für das Gespräch (max. 500 Zeichen).
`language`	string	Nein	Sprachhinweis: `"de"` oder `"en"`. Standard: `"de"`.

calendarId ist bei jedem Autopilot-Aufruf erforderlich — ohne sie antwortet der Endpunkt mit 401. Du findest sie vorausgefüllt unter Dashboard → Kalender → API → Integrations-Anleitung. Sende sie als Feld im JSON-Body. Falls deine Plattform den Body in einen Umschlag einpackt (z.B. Retells args-Objekt), übergib sie stattdessen als URL-Query-Parameter — ?calendarId=YOUR_CALENDAR_ID — denn die API liest calendarId nur aus dem Top-Level-Body, der Query-Zeichenkette oder den Routen-Parametern, niemals aus einem verschachtelten args-Objekt.

Antwort

{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "speak": "Nächste Woche Mittwoch um 14:00 Uhr hätte ich etwas frei. Passt Ihnen das?",
  "phase": "booking",
  "step": "confirm_time",
  "done": false
}

Feld	Typ	Beschreibung
`sessionId`	string	Session-ID — bei jedem Folge-Aufruf zurückgeben.
`speak`	string	Text, den der Voice Bot wörtlich aussprechen soll.
`phase`	string	Aktuelle Gesprächsphase (z.B. `greeting`, `booking`, `cancelling`, `farewell`).
`step`	string	Aktueller Schritt innerhalb der Phase.
`done`	boolean	`true` wenn das Gespräch beendet ist — Voice Bot sollte auflegen.
`action`	string	Zuletzt ausgeführte Terminaktion (falls vorhanden, z.B. `booked`).
`data`	object	Zusätzliche strukturierte Daten zur Aktion (falls vorhanden).

Gesprächsverlauf

Ein typisches Gespräch besteht aus mehreren Nachrichten-Paaren:

Neues Gespräch — Sende message ohne sessionId. FlowCaptain antwortet mit einer Begrüßung und einer sessionId.
Folge-Nachrichten — Sende jede weitere Nachricht mit der erhaltenen sessionId. FlowCaptain behält den Kontext bei.
Gesprächsende — Wenn done: true zurückkommt, ist das Gespräch abgeschlossen.

Sessions laufen nach einer Phase der Inaktivität automatisch ab. Wenn eine abgelaufene sessionId gesendet wird, startet FlowCaptain ein neues Gespräch.

Warm Handoff

Wenn dein Voice Bot vor der Übergabe an FlowCaptain bereits Informationen gesammelt hat (z.B. Name, gewünschter Tag), kannst du diese als initialData mitgeben:

{
  "calendarId": "YOUR_CALENDAR_ID",
  "message": "Hallo",
  "initialData": {
    "intent": "appointment_booking",
    "customerName": "Max Mustermann",
    "phoneNumber": "+491761234567",
    "serviceNames": ["Erstberatung"],
    "problemDescription": "Bremsen quietschen",
    "preferredDay": "nächsten Mittwoch",
    "preferredTimeOfDay": "vormittags"
  }
}

Feld	Typ	Beschreibung
`initialData.intent`	string	Aktuell nur `"appointment_booking"`.
`initialData.customerName`	string	Bereits bekannter Name des Anrufers.
`initialData.phoneNumber`	string	Bereits bekannte Telefonnummer.
`initialData.serviceNames`	string[]	Gewünschte Leistungen.
`initialData.problemDescription`	string	Beschreibung des Anliegens.
`initialData.preferredDay`	string	Gewünschter Tag in natürlicher Sprache.
`initialData.preferredTimeOfDay`	string	Gewünschte Tageszeit (z.B. "vormittags", "nachmittags").

initialData wird nur beim Start eines neuen Gesprächs berücksichtigt. Bei einem Warm Handoff überspringt FlowCaptain die bereits geklärten Schritte und startet direkt im Buchungsfluss.

Fehler

Status	Beschreibung
`400`	`message` fehlt oder ist leer.
`401`	API-Schlüssel fehlt/ungültig oder `calendarId` fehlt.
`502`	Der Google Kalender ist nicht mit dem Dienstkonto geteilt (`calendar_not_shared`).

Wichtig für Voice-Bot-Plattformen

Wörtlich aussprechen: Gib den Inhalt von speak exakt wieder — keine Ergänzungen oder Umformulierungen.
done beachten: Bei done: true das Gespräch beenden.
sessionId persistieren: Speichern und bei jedem Folge-Aufruf zurückgeben.
Keine eigenen Antworten: Versuche nicht, Fragen selbst zu beantworten — leite alles an den Autopilot weiter.