Anruf starten

Startet einen ausgehenden Anruf zu einem Lead — entweder mit einem gespeicherten Agenten, oder mit einem Agenten, der nur für diesen einen Anruf existiert ("inline"/"one-time" Agent).

Endpunkt

POST /api/calls/initiate

Authentifizierung

Erfordert ein gültiges Bearer-JWT. Der Anruf wird mit der project_id aus dem Token verknüpft.

Request-Body

Genau eine der beiden Agent-Angaben verwenden — niemals beide gleichzeitig:

Feld	Typ	Erforderlich	Beschreibung
lead_id	string	ja	ID des anzurufenden Leads.
agent_id	string	nein	ID eines gespeicherten Agenten.
agent	object	nein	Konfiguration für einen einmaligen ("inline") Agenten. Siehe unten.

Wird keiner der beiden angegeben, verwendet der Anruf den Standard-Agenten der Telefonnummer.

Variante A: gespeicherter Agent

{
  "lead_id": "123e4567-e89b-12d3-a456-426614174000",
  "agent_id": "456e7890-e89b-12d3-a456-426614174000"
}

Variante B: Inline-Agent (einmaliger Anruf)

Für einen Anruf, dessen Skript nur für diesen einen Anruf existiert — ohne vorher einen Agenten anzulegen, abzufragen und wieder zu löschen.

{
  "lead_id": "123e4567-e89b-12d3-a456-426614174000",
  "agent": {
    "name": "Einmaliger Anruf: Mieterhöhung, Wohnung 3B",
    "template_agent_id": "456e7890-e89b-12d3-a456-426614174000",
    "ttl_minutes": 120,
    "configuration": {
      "agentSettings": {
        "firstMessage": "Guten Tag, hier spricht ein KI-Assistent der Hausverwaltung Muster. Spreche ich mit Frau {{last_name}}?",
        "prompt": "Du überbringst eine Nachricht: die Miete für Wohnung 3B steigt ab 01.02.2027 um 42 Euro. Beantworte keine Rückfragen, sondern nimm sie auf und sage zu, dass die Hausverwaltung sich meldet."
      }
    }
  }
}

Felder innerhalb von agent:

Feld	Typ	Erforderlich	Beschreibung
name	string	nein	Label für CRM und Logs. Standard: datierter Name "One-time call …". Max. 255 Zeichen.
configuration	object	ja*	Die Agent-Konfiguration. agentSettings.firstMessage und agentSettings.prompt sind erforderlich — ohne template_agent_id direkt, mit template_agent_id zusammen (siehe unten).
template_agent_id	string	nein	ID eines gespeicherten Agenten, dessen Konfiguration als Basis dient. Stimme, Buchung, Transfer und Provider-Einstellungen werden übernommen; nur das Skript ändert sich.
ttl_minutes	integer	nein	Minuten, die der Agent den Anruf überlebt, bevor er gelöscht wird. Standard 120, Bereich 5–1440. Muss die Nachbearbeitung (Transkript, Zusammenfassung, Outcome, Webhook) überleben.

* Ohne template_agent_id müssen agentSettings.firstMessage und agentSettings.prompt direkt in configuration stehen. Mit template_agent_id reicht es, nur das zu überschreiben, was sich ändern soll — alles andere wird aus dem Template übernommen.

Verhalten

• Gegenseitiger Ausschluss: agent_id und agent dürfen nicht zusammen gesendet werden — das ergibt 400.
• Inline-Agent wird gespeichert. Auch ein Inline-Agent wird als echte Agent-Zeile angelegt, weil die Nachbearbeitung nach dem Anruf (Zusammenfassung, Outcome-Klassifikation, Kunden-Webhook, E-Mail-Benachrichtigung) die Agent-Konfiguration erneut liest. Er läuft über dieselbe Prüfung wie POST /api/agents (EU-AI-Act-Offenlegung in der ersten Nachricht, Längenlimit für den Zusammenfassungs-Prompt, Sprachrechte, staff-only Provider-Felder) — ein Inline-Agent ist eine Abkürzung, keine zweite Tür in die Konfiguration.
• EU-AI-Act-Offenlegung: agentSettings.firstMessage muss offenlegen, dass ein KI-Assistent spricht (z. B. "… ein KI-Assistent von …"). Fehlt das, wird der Request mit 400 abgelehnt.
• Automatisches Löschen (TTL): Der Inline-Agent läuft nach ttl_minutes ab und wird von einem Hintergrund-Job eingesammelt. Er erscheint währenddessen nicht in der Agenten-Liste und zählt nicht gegen das Plan-Limit für KI-Assistenten.
• template_agent_id: Die Konfiguration des Templates ist die Merge-Basis; das Request-configuration wird Schlüssel für Schlüssel darüber gelegt. Ein explizites JSON-null entfernt einen vom Template übernommenen Block (z. B. um Buchung oder Transfer für diesen einen Anruf abzuschalten). Stimme, Buchung, Transfer, Provider-Einstellungen und die E-Mail-Benachrichtigung nach dem Anruf werden mit übernommen.
• Fehlgeschlagener Anruf-Start: Schlägt der Wählversuch fehl, bleibt der Inline-Agent bis zum Ablauf der TTL erhalten statt sofort gelöscht zu werden — ein Fehler hier beweist nicht, dass nichts gewählt wurde.

Erfolgsantwort

{
  "success": true,
  "message": "Call initiated successfully",
  "provider_call_id": "call-id-123",
  "agent_id": "9f1c0f7e-2a44-4f9e-9a0b-2b7c1d3e4f50"
}

agent_id ist nur bei einem Inline-Agenten enthalten — es ist die ID des einmalig angelegten Agenten. Darüber lässt er sich der Anruf-Aktivität zuordnen oder vorzeitig löschen, statt auf den Ablauf zu warten. Bei Verwendung eines gespeicherten agent_id oder des Standard-Agenten fehlt dieses Feld in der Antwort.

Fehlerantworten

agent_id und agent gleichzeitig gesendet

{
  "success": false,
  "message": "Send either agent_id or agent, not both: agent_id names a stored agent, agent defines a one-time one.",
  "provider_call_id": null
}

Fehlende EU-AI-Act-Offenlegung in der ersten Nachricht

{
  "success": false,
  "message": "First message must disclose that the caller is an AI (EU AI Act Art. 50). Add an AI disclosure to the start of the agent's first message, e.g. '… ein KI-Assistent von …' or '… an AI assistant from …'.",
  "agent": null
}

agentSettings.firstMessage oder agentSettings.prompt fehlt

{
  "success": false,
  "message": "agent.configuration.agentSettings.prompt is required and must not be empty",
  "provider_call_id": null
}

Unbekannter template_agent_id

{
  "success": false,
  "message": "template_agent_id 456e7890-e89b-12d3-a456-426614174000 not found in this project",
  "provider_call_id": null
}

Unzureichendes Guthaben / nicht genug Minuten

{
  "success": false,
  "message": "Insufficient minutes to start this call",
  "provider_call_id": null
}

Datenbank- oder Providerfehler

{
  "success": false,
  "message": "Failed to initiate call: ...",
  "provider_call_id": null
}