---
title: "Create Assistants"
method: POST
path: "/user/assistant"
tags: ["Assistants"]
---

# Create Assistants

`POST /user/assistant`

## Request

- Base URL: `https://app.famulor.de/api`
- URL: `https://app.famulor.de/api/user/assistant`
- Auth: HTTP bearer

Create a new AI assistant with specified configuration

[Docs](https://docs.famulor.io/api-v1/assistants/create)

## Request body

- object
  - `name` string, required: The name of the assistant (max. 255 characters)
  - `voice_id` integer, required: The voice ID for the assistant. Use the endpoint [Retrieve Voices](/en/api-reference/assistants/voices) with the query parameter `mode` to get compatible voices for your engine mode.
  - `language_id` integer, required: The language ID for the assistant. Use the endpoint [Retrieve Languages](/en/api-reference/assistants/languages) to get available languages.
  - `type` 'inbound' | 'outbound', required: The assistant type. Options: `inbound`, `outbound`
  - `mode` 'pipeline' | 'multimodal' | 'dualplex', required: The engine mode. Options: `pipeline`, `multimodal`, `dualplex`
  - `timezone` string, required: The time zone of the assistant (e.g., "Europe/Berlin", "America/New_York")
  - `initial_message` string, required: The first message the assistant speaks at the start of the call (max. 200 characters)
  - `system_prompt` string, required: The system prompt that defines the assistant’s behavior and personality
  - `llm_model_id` integer: The LLM model ID. **Required for mode `pipeline`.** Use the endpoint [Retrieve Models](/en/api-reference/assistants/models) to get available models.
  - `multimodal_model_id` integer: The multimodal model ID. **Required for modes `multimodal` and `dualplex`.** Use the endpoint [Retrieve Models](/en/api-reference/assistants/models) to get available multimodal models.
  - `chat_llm_fallback_id` integer: Fallback LLM model ID for tool calls in `multimodal`/`dualplex`. Optional.
  - `turn_detection_threshold` number: Sensitivity of turn detection in `multimodal`/`dualplex` (0-1). Default: auto
  - `secondary_language_ids` integer[]: Array of additional language IDs that the assistant can speak. The assistant automatically recognizes the language and switches accordingly.
  - `knowledgebase_id` integer: The knowledgebase ID to attach to this assistant
  - `knowledgebase_mode` string: How to use the knowledgebase. Options: * `function_call` - AI calls a function to search (required for multimodal/dualplex) * `prompt` - Knowledge is injected into prompt (pipeline only)
  - `folder_id` integer: ID of a [folder](/en/api-reference/folders/create) to place this assistant in. Must belong to your account. Send `null` to leave the assistant uncategorized.
  - `label_ids` integer[]: Array of [label](/en/api-reference/labels/create) IDs to apply to this assistant. Each label must belong to your account.
  - `phone_number_id` integer: The ID of a phone number to assign to the assistant. Must belong to your account. <Warning> For `inbound` assistants, the phone number must not be a caller ID type and must not already be assigned to another `inbound` assistant. </Warning>
  - `tool_ids` integer[]: Array of IDs for custom mid-call tools to attach. Each tool must belong to your account.
  - `tools` unknown[]: Array of built-in tools. Each tool has a `type` field and tool-specific fields. On [Update Assistant](/en/api-reference/assistants/update), this **replaces all existing built-in tools** — pass an empty array `[]` to remove all tools. <Note> When you [list assistants](/en/api-reference/assistants/list), each configured tool is returned as `{ "type": "...", "data": { ... } }` with the same field names nested under `data` (not top-level). </Note>
    - unknown
  - `tts_emotion_enabled` boolean: Whether emotional text-to-speech synthesis is enabled
  - `voice_stability` number: Voice stability (0-1). Higher = more consistent
  - `voice_similarity` number: Voice similarity (0-1). Higher = closer to the original
  - `speech_speed` number: Speech speed multiplier (0.7-1.2)
  - `llm_temperature` number: LLM temperature (0-1). Lower = more deterministic
  - `synthesizer_provider_id` integer: Custom TTS provider ID. If not set, selected automatically based on language. See [Retrieve Synthesizer Providers](/en/api-reference/assistants/synthesizer-providers).
  - `transcriber_provider_id` integer: Custom STT provider ID. If not set, selected automatically based on language. Only for `pipeline`. See [Retrieve Transcriber Providers](/en/api-reference/assistants/transcriber-providers).
  - `allow_interruptions` boolean: Whether interruptions from the caller are allowed. <Warning>Cannot be disabled for `multimodal` and `dualplex`.</Warning>
  - `fillers` boolean: Whether filler audio should be used during processing (e.g., "uh", "just a moment"). <Warning>Only available in `pipeline` mode.</Warning>
  - `filler_config` object: Custom filler profiles per category. If not specified, language-dependent defaults are used. Each category is an array of short phrases. * `positive`: Fillers for affirmative responses (e.g., "Great!", "Perfect!") * `negative`: Fillers for negative/neutral responses (e.g., "Hmm.", "Mhm.") * `question`: Fillers while processing a question (e.g., "Good question.", "One moment.") * `neutral`: Fillers for neutral acknowledgments (e.g., "Okay.", "Understood.")
  - `record` boolean: Whether the call should be recorded
  - `enable_noise_cancellation` boolean: Whether noise cancellation should be enabled
  - `wait_for_customer` boolean: If true, the assistant waits for the customer to speak first
  - `max_duration` integer: Maximum call duration in seconds (20-1200)
  - `max_silence_duration` integer: Maximum silence duration until re-engagement in seconds (1-360)
  - `max_initial_silence_duration` integer: Maximum silence directly after call start before termination (1-120 seconds). Optional.
  - `ringing_time` integer: Maximum ringing time before canceling (1-60 seconds)
  - `reengagement_interval` integer: Re-engagement interval in seconds (7-600)
  - `reengagement_prompt` string: Custom prompt for re-engagement messages (max. 1000 characters) Example: `"Are you still there? Do you have any other questions?"`
  - `end_call_on_voicemail` boolean: Whether to end the call if voicemail is detected
  - `voice_mail_message` string: Message to leave on voicemail (max. 1000 characters)
  - `endpoint_type` 'vad' | 'ai': Voice activity detection type. Options: `vad`, `ai`
  - `endpoint_sensitivity` number: Endpoint sensitivity (0-5)
  - `interrupt_sensitivity` number: Interrupt sensitivity (0-5)
  - `min_interrupt_words` integer: Minimum number of words before interruption is allowed (0-10). Set to enable.
  - `ambient_sound` 'off' | 'office' | 'city' | 'forest' | 'crowded_room' | 'cafe' | 'nature': Background ambient sound. Options: `off`, `office`, `city`, `forest`, `crowded_room`, `cafe`, `nature`
  - `ambient_sound_volume` number: Ambient sound volume (0-1)
  - `is_webhook_active` boolean: Whether webhook notifications are enabled
  - `webhook_url` string: The webhook URL for post-call notifications. **Required if `is_webhook_active` is true.**
  - `send_webhook_only_on_completed` boolean: Whether to send webhooks only for completed calls (not for failed/no-answer)
  - `include_recording_in_webhook` boolean: Whether to include the recording URL in the webhook payload
  - `post_call_evaluation` boolean: Whether AI post-call evaluation is enabled
  - `post_call_schema` object[]: Schema definition for post-call data extraction
    - `name` string, required: Field name (3-16 characters, lowercase, alphanumeric and underscores only)
    - `type` 'string' | 'number' | 'bool', required: Data type. Options: `string`, `number`, `bool`
    - `description` string, required: Description of what this field represents (3-255 characters)
  - `variables` object: Key-value pairs of custom variables that can be used in prompts via `{{variable_name}}`
  - `conversation_inactivity_timeout` integer: Minutes of chat inactivity before the conversation is considered ended (1–1440)
  - `conversation_ended_retrigger` boolean: Whether the conversation can be restarted after inactivity end
  - `conversation_ended_webhook_url` string: Webhook URL invoked when a chat conversation ends due to inactivity. Separate from the call webhook.

## Response `201`

Success Response

- object
  - `message` string: Success message confirming the creation of the assistant
  - `data` object
    - `id` integer: The unique ID of the created assistant
    - `name` string: The name of the assistant
    - `status` string: The current status (`inactive` for newly created assistants)
    - `type` string: The type (`inbound` or `outbound`)
    - `mode` string: The engine mode (`pipeline`, `multimodal`, or `dualplex`)

## Other responses

- `401`: Fehlender oder ungültiger API-Key.
- `422`: Validation Error

---

[API](https://skmtc.dev/famulor/apis/famulor-api.md) · [All operations](https://skmtc.dev/famulor/apis/famulor-api/llms.txt) · [OpenAPI document](https://skmtc.dev/famulor/apis/famulor-api/revisions/3b938c370721?raw)