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. Ihr 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

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

Feld	Typ	Pflicht	Beschreibung
`message`	string	Ja	Was der Anrufer gesagt hat.
`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).
`language`	string	Nein	Sprachhinweis: `"de"` oder `"en"`. Standard: `"de"`.

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.

Gesprächsverlauf

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

Neues Gespräch — Senden Sie message ohne sessionId. FlowCaptain antwortet mit einer Begrüßung und einer sessionId.
Folge-Nachrichten — Senden Sie 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 Ihr Voice Bot vor der Übergabe an FlowCaptain bereits Informationen gesammelt hat (z.B. Name, gewünschter Tag), können Sie diese als initialData mitgeben:

{
  "message": "Hallo",
  "initialData": {
    "intent": "appointment_booking",
    "customerName": "Max Mustermann",
    "phoneNumber": "+491761234567",
    "serviceNames": ["Erstberatung"],
    "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 Dienstleistungen.
`initialData.preferredDay`	string	Gewünschter Tag in natürlicher Sprache.
`initialData.preferredTimeOfDay`	string	Gewünschte Tageszeit (z.B. "vormittags", "nachmittags").

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 oder ist ungültig.
`403`	Session gehört zu einem anderen Kalender.

Wichtig für Voice-Bot-Plattformen

Wörtlich aussprechen: Geben Sie 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: Versuchen Sie nicht, Fragen selbst zu beantworten — leiten Sie alles an den Autopilot weiter.