Zum Hauptinhalt springen
POST
/
api
/
user
/
assistant
Assistenten erstellen
curl --request POST \
  --url https://app.famulor.de/api/user/assistant \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "voice_id": 123,
  "language_id": 123,
  "type": "<string>",
  "mode": "<string>",
  "timezone": "<string>",
  "initial_message": "<string>",
  "system_prompt": "<string>",
  "llm_model_id": 123,
  "multimodal_model_id": 123,
  "chat_llm_fallback_id": 123,
  "turn_detection_threshold": 123,
  "secondary_language_ids": [
    123
  ],
  "knowledgebase_id": 123,
  "knowledgebase_mode": "<string>",
  "phone_number_id": 123,
  "tool_ids": [
    123
  ],
  "tools": [
    {}
  ],
  "tts_emotion_enabled": true,
  "voice_stability": 123,
  "voice_similarity": 123,
  "speech_speed": 123,
  "llm_temperature": 123,
  "synthesizer_provider_id": 123,
  "transcriber_provider_id": 123,
  "allow_interruptions": true,
  "fillers": true,
  "filler_config": {},
  "record": true,
  "enable_noise_cancellation": true,
  "wait_for_customer": true,
  "max_duration": 123,
  "max_silence_duration": 123,
  "max_initial_silence_duration": 123,
  "ringing_time": 123,
  "reengagement_interval": 123,
  "reengagement_prompt": "<string>",
  "end_call_on_voicemail": true,
  "voice_mail_message": "<string>",
  "endpoint_type": "<string>",
  "endpoint_sensitivity": 123,
  "interrupt_sensitivity": 123,
  "min_interrupt_words": 123,
  "ambient_sound": "<string>",
  "ambient_sound_volume": 123,
  "is_webhook_active": true,
  "webhook_url": "<string>",
  "send_webhook_only_on_completed": true,
  "include_recording_in_webhook": true,
  "post_call_evaluation": true,
  "post_call_schema": [
    {
      "name": "<string>",
      "type": "<string>",
      "description": "<string>"
    }
  ],
  "variables": {},
  "conversation_inactivity_timeout": 123,
  "conversation_ended_retrigger": true,
  "conversation_ended_webhook_url": "<string>"
}
'
{
  "message": "Assistant created successfully",
  "data": {
    "id": 789,
    "name": "Sales Assistant",
    "status": "inactive",
    "type": "outbound",
    "mode": "pipeline"
  }
}
Einen neuen KI-Assistenten mit spezifizierter Konfiguration erstellen
Dieser Endpunkt ermöglicht es Ihnen, einen neuen KI-Assistenten mit umfassenden Konfigurationsoptionen zu erstellen.

Engine-Modi

Die API unterstützt drei Engine-Modi mit unterschiedlichen Fähigkeiten:
ModusBeschreibungErforderliche Felder
pipelineKlassische STT → LLM → TTS Pipelinellm_model_id
multimodalEchtzeit Multimodal-KImultimodal_model_id
dualplexMultimodal “Brain” + Custom TTS-Voicemultimodal_model_id

Request Body

Erforderliche Kernfelder

name
string
erforderlich
Der Name des Assistenten (max. 255 Zeichen)
voice_id
integer
erforderlich
Die Voice-ID für den Assistenten. Verwenden Sie den Endpunkt Stimmen abrufen mit dem Query-Parameter mode, um kompatible Stimmen für Ihren Engine-Modus zu erhalten.
language_id
integer
erforderlich
Die Language-ID für den Assistenten. Verwenden Sie den Endpunkt Sprachen abrufen, um verfügbare Sprachen zu erhalten.
type
string
erforderlich
Der Assistenten-Typ. Optionen: inbound, outbound
mode
string
erforderlich
Der Engine-Modus. Optionen: pipeline, multimodal, dualplex
timezone
string
erforderlich
Die Zeitzone des Assistenten (z.B. “Europe/Berlin”, “America/New_York”)
initial_message
string
erforderlich
Die erste Nachricht, die der Assistent beim Start des Anrufs spricht (max. 200 Zeichen)
system_prompt
string
erforderlich
Der System-Prompt, der Verhalten und Persönlichkeit des Assistenten definiert

Modus-spezifische Felder

llm_model_id
integer
Die LLM-Model-ID. Erforderlich für den Modus pipeline.Verwenden Sie den Endpunkt Modelle abrufen, um verfügbare Modelle zu erhalten.
multimodal_model_id
integer
Die Multimodal-Model-ID. Erforderlich für die Modi multimodal und dualplex.Verwenden Sie den Endpunkt Modelle abrufen, um verfügbare Multimodal-Modelle zu erhalten.
chat_llm_fallback_id
integer
Fallback-LLM-Model-ID für Tool-Calls in multimodal/dualplex. Optional.
turn_detection_threshold
number
Empfindlichkeit der Turn-Detection in multimodal/dualplex (0-1). Standard: auto

Sekundäre Sprachen

secondary_language_ids
integer[]
Array zusätzlicher Language-IDs, die der Assistent sprechen kann. Der Assistent erkennt die Sprache automatisch und wechselt entsprechend.
"secondary_language_ids": [2, 3, 4]

Knowledgebase-Einstellungen

knowledgebase_id
integer
Die Knowledgebase-ID, die an diesen Assistenten angehängt werden soll
knowledgebase_mode
string
Wie die Knowledgebase verwendet wird. Optionen:
  • function_call - Die KI ruft eine Funktion zur Suche auf (erforderlich für multimodal/dualplex)
  • prompt - Wissen wird in den Prompt injiziert (nur pipeline)

Telefonnummer

phone_number_id
integer
Die ID einer Telefonnummer, die dem Assistenten zugewiesen werden soll. Muss zu Ihrem Konto gehören.
Für inbound Assistenten darf die Telefonnummer kein Caller-ID Typ sein und darf nicht bereits einem anderen inbound Assistenten zugewiesen sein.

Custom Mid-Call Tools

tool_ids
integer[]
Array von IDs für Custom Mid-Call Tools, die angehängt werden sollen. Jedes Tool muss zu Ihrem Konto gehören.
"tool_ids": [1, 5, 12]

Built-in Tools

tools
array
Array aktivierter Built-in Tools. Jedes Tool hat ein type-Feld und tool-spezifische Felder.
"tools": [
  {
    "type": "call_transfer",
    "phone_number": "+1234567890",
    "description": "Weiterleiten, wenn der Kunde menschlichen Support wünscht"
  },
  {
    "type": "warm_call_transfer",
    "supervisor_phone": "+1234567891",
    "outbound_phone_id": 7,
    "description": "An einen menschlichen Ansprechpartner weiterleiten, wenn der Kunde mit einer echten Person sprechen möchte.",
    "custom_sip": false,
    "caller_id_mode": "outbound_number",
    "hold_music": "hold_music",
    "hold_music_volume": 80,
    "hold_message": "Bitte warten Sie, während ich Sie mit einem Ansprechpartner verbinde.",
    "summary_instructions": "Kurz aus Ihrer Sicht: Wer ruft an, warum, warum wird ein Mensch benötigt. 2–3 Sätze.",
    "briefing_initial_message": "Hallo! Ich habe einen Anrufer, der Unterstützung braucht. Darf ich die Situation kurz schildern?",
    "connected_message": "Sie sind jetzt mit einem Ansprechpartner verbunden."
  },
  {
    "type": "collect_keypad",
    "timeout": 5,
    "stop_key": "#"
  },
  {
    "type": "end_call",
    "description": "Anruf beenden, wenn der Kunde die Zufriedenheit bestätigt"
  }
]

Voice- und TTS-Einstellungen

tts_emotion_enabled
boolean
Standard:"true"
Ob emotionale Text-to-Speech Synthese aktiviert ist
voice_stability
number
Standard:"0.70"
Voice-Stability (0-1). Höher = konsistenter
voice_similarity
number
Standard:"0.50"
Voice-Similarity (0-1). Höher = näher am Original
speech_speed
number
Standard:"1.00"
Sprechgeschwindigkeit-Multiplikator (0.7-1.2)
llm_temperature
number
Standard:"0.10"
LLM-Temperatur (0-1). Niedriger = deterministischer
synthesizer_provider_id
integer
Custom TTS Provider-ID. Wenn nicht gesetzt, wird anhand der Sprache automatisch ausgewählt. Siehe Synthesizer-Provider abrufen.
transcriber_provider_id
integer
Custom STT Provider-ID. Wenn nicht gesetzt, wird anhand der Sprache automatisch ausgewählt. Nur pipeline. Siehe Transcriber-Provider abrufen.

Call-Behavior-Einstellungen

allow_interruptions
boolean
Standard:"true"
Ob Unterbrechungen durch den Anrufer erlaubt sind.
Kann für multimodal und dualplex nicht deaktiviert werden.
fillers
boolean
Standard:"false"
Ob Filler-Audio während der Verarbeitung verwendet werden soll (z.B. “äh”, “einen Moment”).
Nur verfügbar im Modus pipeline.
filler_config
object
Benutzerdefinierte Füller-Profile pro Kategorie. Wenn nicht angegeben, werden sprachabhängige Standardwerte verwendet. Jede Kategorie ist ein Array kurzer Phrasen.
  • positive: Füller für zustimmende Antworten (z.B. “Super!”, “Perfekt!”)
  • negative: Füller für ablehnende/neutrale Antworten (z.B. “Hmm.”, “Mhm.”)
  • question: Füller beim Verarbeiten einer Frage (z.B. “Hmm.”, “Einen Moment.”)
  • neutral: Füller für neutrale Bestätigungen (z.B. “Ok.”, “Verstanden.”)
"filler_config": {
  "positive": ["Super!", "Perfekt!", "Sehr gut!"],
  "negative": ["Hmm.", "Verstehe.", "Okay."],
  "question": ["Gute Frage.", "Einen Moment.", "Lass mich nachschauen."],
  "neutral": ["Ok.", "Verstanden.", "Notiert."]
}
record
boolean
Standard:"false"
Ob der Anruf aufgezeichnet werden soll
enable_noise_cancellation
boolean
Standard:"true"
Ob Noise-Cancellation aktiviert werden soll
wait_for_customer
boolean
Standard:"false"
Wenn true, wartet der Assistent, bis der Kunde zuerst spricht

Timing-Einstellungen

max_duration
integer
Standard:"600"
Maximale Anrufdauer in Sekunden (20-1200)
max_silence_duration
integer
Standard:"40"
Maximale Stille-Dauer bis zur Re-Engagement in Sekunden (1-360)
max_initial_silence_duration
integer
Maximale Stille direkt beim Anrufstart, bevor beendet wird (1-120 Sekunden). Optional.
ringing_time
integer
Standard:"30"
Maximale Klingelzeit, bevor abgebrochen wird (1-60 Sekunden)

Re-Engagement-Einstellungen

reengagement_interval
integer
Standard:"30"
Re-Engagement Intervall in Sekunden (7-600)
reengagement_prompt
string
Custom Prompt für Re-Engagement-Nachrichten (max. 1000 Zeichen)Beispiel: "Sind Sie noch dran? Haben Sie noch weitere Fragen?"

Voicemail-Einstellungen

end_call_on_voicemail
boolean
Standard:"true"
Ob der Anruf beendet werden soll, wenn Voicemail erkannt wird
voice_mail_message
string
Nachricht, die auf der Voicemail hinterlassen wird (max. 1000 Zeichen)

Endpoint-Detection

endpoint_type
string
Standard:"vad"
Voice-Activity-Detection-Typ. Optionen: vad, ai
endpoint_sensitivity
number
Standard:"0.5"
Endpoint-Sensitivity (0-5)
interrupt_sensitivity
number
Standard:"0.5"
Interrupt-Sensitivity (0-5)
min_interrupt_words
integer
Mindestanzahl an Wörtern, bevor eine Unterbrechung erlaubt wird (0-10). Zum Aktivieren setzen.

Ambient Sound

ambient_sound
string
Hintergrund-Ambient-Sound. Optionen: off, office, city, forest, crowded_room, cafe, nature
ambient_sound_volume
number
Standard:"0.5"
Ambient-Sound-Lautstärke (0-1)

Webhook-Konfiguration

is_webhook_active
boolean
Standard:"false"
Ob Webhook-Benachrichtigungen aktiviert sind
webhook_url
string
Die Webhook-URL für Post-Call Benachrichtigungen. Erforderlich, wenn is_webhook_active true ist.
send_webhook_only_on_completed
boolean
Standard:"true"
Ob Webhooks nur bei abgeschlossenen Anrufen gesendet werden sollen (nicht bei failed/no-answer)
include_recording_in_webhook
boolean
Standard:"true"
Ob Recording-URL in der Webhook-Payload enthalten sein soll

Post-Call Evaluation

post_call_evaluation
boolean
Standard:"true"
Ob AI Post-Call Evaluation aktiviert ist
post_call_schema
array
Schema-Definition für Post-Call Datenextraktion
"post_call_schema": [
  {"name": "status", "type": "bool", "description": "Wurde das Anrufziel erreicht"},
  {"name": "summary", "type": "string", "description": "Kurze Zusammenfassung des Anrufs"}
]

Variablen

variables
object
Key-Value Paare von Custom Variablen, die in Prompts via {{variable_name}} genutzt werden können
"variables": {
  "company_name": "Acme GmbH",
  "product": "Premium Widget",
  "support_email": "support@acme.com"
}

Conversation-Ended-Einstellungen

conversation_inactivity_timeout
integer
Standard:"30"
Minuten Chat-Inaktivität, bis die Konversation als beendet gilt (1–1440)
conversation_ended_retrigger
boolean
Standard:"false"
Ob die Konversation nach Inaktivitäts-Ende erneut gestartet werden kann
conversation_ended_webhook_url
string
Webhook-URL, die beim Ende einer Chat-Konversation wegen Inaktivität aufgerufen wird. Getrennt vom Anruf-Webhook.

Beispiel-Requests

pipeline Modus Assistent

{
  "name": "Sales Assistant",
  "voice_id": 1,
  "language_id": 1,
  "type": "outbound",
  "mode": "pipeline",
  "timezone": "Europe/Berlin",
  "initial_message": "Hallo! Wie kann ich Ihnen heute helfen?",
  "system_prompt": "Du bist ein professioneller Sales Assistant...",
  "llm_model_id": 2,
  "secondary_language_ids": [2, 3],
  "knowledgebase_id": 1,
  "knowledgebase_mode": "prompt",
  "fillers": true,
  "filler_config": {
    "positive": ["Super!", "Perfekt!", "Sehr gut!"],
    "negative": ["Hmm.", "Verstehe."],
    "question": ["Gute Frage.", "Einen Moment."],
    "neutral": ["Ok.", "Notiert.", "Verstanden."]
  },
  "tool_ids": [1, 5],
  "tools": [
    {"type": "end_call", "description": "Anruf beenden, wenn der Kunde zufrieden ist"},
    {"type": "call_transfer", "phone_number": "+1234567890", "description": "Weiterleiten an Support"},
    {
      "type": "warm_call_transfer",
      "supervisor_phone": "+1234567891",
      "outbound_phone_id": 7,
      "description": "An einen menschlichen Ansprechpartner weiterleiten, wenn der Kunde mit einer echten Person sprechen möchte.",
      "custom_sip": false,
      "caller_id_mode": "outbound_number",
      "hold_music": "hold_music",
      "hold_music_volume": 80,
      "hold_message": "Bitte warten Sie, während ich Sie mit einem Ansprechpartner verbinde.",
      "summary_instructions": "Kurz aus Ihrer Sicht: Wer ruft an, warum, warum wird ein Mensch benötigt. 2–3 Sätze.",
      "briefing_initial_message": "Hallo! Ich habe einen Anrufer, der Unterstützung braucht. Darf ich die Situation kurz schildern?",
      "connected_message": "Sie sind jetzt mit einem Ansprechpartner verbunden."
    },
    {"type": "collect_keypad", "timeout": 5, "stop_key": "#"}
  ],
  "reengagement_interval": 20,
  "reengagement_prompt": "Sind Sie noch dran?"
}

multimodal Modus Assistent

{
  "name": "Support Bot",
  "voice_id": 41,
  "language_id": 1,
  "type": "inbound",
  "mode": "multimodal",
  "timezone": "America/New_York",
  "initial_message": "Hi! Willkommen beim Support.",
  "system_prompt": "Du bist ein hilfreicher Support-Agent...",
  "multimodal_model_id": 1,
  "chat_llm_fallback_id": 2,
  "turn_detection_threshold": 0.7,
  "knowledgebase_id": 1,
  "knowledgebase_mode": "function_call",
  "tts_emotion_enabled": false
}

dualplex Modus Assistent

{
  "name": "Premium Agent",
  "voice_id": 1,
  "language_id": 2,
  "type": "outbound",
  "mode": "dualplex",
  "timezone": "Europe/Berlin",
  "initial_message": "Guten Tag!",
  "system_prompt": "Du bist ein professioneller Assistent...",
  "multimodal_model_id": 4,
  "chat_llm_fallback_id": 2,
  "secondary_language_ids": [1, 3],
  "knowledgebase_id": 1,
  "knowledgebase_mode": "function_call",
  "ambient_sound": "office",
  "ambient_sound_volume": 0.3
}

Response

message
string
Erfolgsmeldung, die die Erstellung des Assistenten bestätigt
data
object
{
  "message": "Assistant created successfully",
  "data": {
    "id": 789,
    "name": "Sales Assistant",
    "status": "inactive",
    "type": "outbound",
    "mode": "pipeline"
  }
}

Hinweise

  • Alle erforderlichen Felder müssen für eine erfolgreiche Erstellung angegeben werden
  • Verwenden Sie den Endpunkt Stimmen abrufen mit dem Query-Parameter mode, um kompatible Stimmen zu erhalten
  • Für multimodal/dualplex muss knowledgebase_mode auf function_call gesetzt sein
  • Für multimodal/dualplex ist allow_interruptions immer aktiv
  • fillers ist nur im Modus pipeline verfügbar
  • Neue Assistenten werden standardmäßig mit Status inactive erstellt