> ## Documentation Index
> Fetch the complete documentation index at: https://docs.receptonic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create assistant

> Create a new AI assistant with specified configuration

This endpoint allows you to create a new AI assistant with comprehensive configuration options.

## Engine Modes

The API supports three engine modes, each with different capabilities:

| Mode | Description | Required Fields |
| - | - | - |
| `pipeline` | Traditional STT → LLM → TTS pipeline | `llm_model_id` |
| `multimodal` | Real-time multimodal AI | `multimodal_model_id` |
| `dualplex` | Multimodal brain + custom TTS voice | `multimodal_model_id` |

### Request Body

#### Core Required Fields

**name** `string` *required*

The name of the assistant (max 255 characters)

**voice\_id** `integer` *required*

The voice ID to use for the assistant. Use the [Get Voices](https://docs.receptonic.com/api-reference/assistants/get-voices.md) endpoint with the `mode` parameter to get compatible voices for your engine mode.

**language\_id** `integer` *required*

The language ID for the assistant. Use the [Get Languages](https://docs.receptonic.com/api-reference/assistants/get-languages.md) endpoint to get available languages.

**type** `string` *required*

The assistant type. Options: `inbound`, `outbound`

**mode** `string` *required*

The engine mode. Options: `pipeline`, `multimodal`, `dualplex`

**timezone** `string` *required*

The timezone for the assistant (e.g., "Europe/Bucharest", "America/New\_York")

**initial\_message** `string` *required*

The initial message the assistant will speak when the call starts (max 200 characters)

**system\_prompt** `string` *required*

The system prompt that defines the assistant's behavior and personality

#### Mode-Specific Fields

**llm\_model\_id** `integer`

The LLM model ID to use. **Required for `pipeline` mode.**

Use the [Get Models](https://docs.receptonic.com/api-reference/assistants/get-models.md) endpoint to get available models.

**multimodal\_model\_id** `integer`

The multimodal model ID. **Required for `multimodal` and `dualplex` modes.**

Use the [Get Models](https://docs.receptonic.com/api-reference/assistants/get-models.md) endpoint to get available multimodal models.

**chat\_llm\_fallback\_id** `integer`

Fallback LLM model ID for tool calls in multimodal/dualplex modes. Optional.

**turn\_detection\_threshold** `number`

Turn detection sensitivity for multimodal/dualplex modes (0-1). Default: auto

#### Secondary Languages

**secondary\_language\_ids** `integer[]`

Array of additional language IDs the assistant can speak. The assistant will auto-detect and switch languages.

```json theme={null}
"secondary_language_ids": [2, 3, 4]
```

#### Knowledgebase Settings

**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)

#### Organization

**folder\_id** `integer`

ID of a [folder](https://docs.receptonic.com/api-reference/folders/create-folder.md) to place this assistant in. Must belong to your account. Send `null` to leave the assistant uncategorized.

**label\_ids** `integer[]`

Array of [label](https://docs.receptonic.com/api-reference/labels/create-label.md) IDs to apply to this assistant. Each label must belong to your account.

```json theme={null}
"label_ids": [3, 5]
```

#### Phone Number

**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 cannot be a Caller ID type and cannot be already assigned to another inbound assistant.

#### Custom Mid-Call Tools

**tool\_ids** `integer[]`

Array of custom mid-call tool IDs to attach. Each tool must belong to your account.

```json theme={null}
"tool_ids": [1, 5, 12]
```

#### Built-in Tools

**tools** `array`

Array of built-in tools to enable. Each tool has a `type` and tool-specific fields.

**Tool types**

**call\_transfer** - Transfer the call to another phone number

* `phone_number` (required): Phone number to transfer to (e.g., "+1234567890")
* `description`: When to transfer the call
* `custom`: If true, AI can determine transfer number dynamically
* `timezone`: Timezone for transfer availability
* `warm_transfer`: Send a message to the customer before transferring (default: `false`)
* `warm_transfer_message`: Prompt telling the AI what to say before transferring (e.g., "Tell the customer that the call is being transferred.")

**warm\_call\_transfer** - Warm transfer with supervisor briefing

* `supervisor_phone` (required): Phone number to dial for the warm transfer (e.g., "+14155552001"). If `custom_sip` is enabled, this is a SIP address or internal extension instead.
* `outbound_phone_id` (required): ID of the phone number used to dial the supervisor. Use [Get Phone Numbers](https://docs.receptonic.com/api-reference/assistants/get-phone-numbers.md) to find available numbers.
* `description` (required): **When to transfer** — describes when the AI should initiate the warm transfer (e.g., "Transfer the call to a human supervisor when the customer requests to speak with a real person.")
* `custom_sip`: Enable to enter a custom SIP address or internal extension instead of a phone number (default: `false`)
* `caller_id_mode`: What phone number the supervisor sees when receiving the call. Options: `outbound_number` (default — shows the outbound phone number), `customer_number` (shows the caller's number), `custom` (shows a custom number)
* `custom_caller_id`: Custom phone number shown to supervisor. Only used when `caller_id_mode` is `custom`.
* `hold_music`: Audio played to the caller while on hold. Options: `hold_music` (default — plays default hold music), `none` (silence, no music)
* `hold_music_volume`: Volume level for hold music, 0-100 (default: `80`)
* `hold_message`: Message spoken to caller before placing them on hold (default: "Please hold while I connect you with a supervisor.")
* `summary_instructions`: Instructions for how the AI should brief the supervisor about the call (default: "Introduce the conversation from your perspective:\n- WHO is calling (name, company if mentioned)\n- WHY they called (their goal or problem)\n- WHY a human is needed at this point\n\nKeep it brief (2-3 sentences).")
* `briefing_initial_message`: The first message the AI says to the supervisor when they answer (default: "Hello! I have a caller on the line who needs your assistance. May I brief you on the situation?")
* `connected_message`: Message spoken to caller after supervisor is connected (default: "You are now connected with a supervisor. I'll leave you to it.")

**end\_call** - End the call programmatically

* `description`: When the AI should end the call

**dtmf\_input** - Send DTMF tones (keypad input)

* `description`: When to use DTMF input (for IVR navigation)

**collect\_keypad** - Collect keypad input from the caller

* `timeout`: Seconds to wait for input, 1-30 (default: 5)
* `stop_key`: Key that ends input. Options: `#` (default), `*`

**calendar\_integration** - Schedule appointments via Cal.com or Calendly

* `calendar_type`: Calendar provider. Options: `calcom` (default), `calendly`
* `description`: When to offer scheduling

Cal.com fields (`calendar_type: "calcom"`):

* `calcom_api_key` (required): Your Cal.com API key
* `calcom_event_slug` (required): The event type slug from Cal.com
* `calcom_team_slug`: Team slug if the event belongs to a Cal.com team
* `calcom_endpoint`: Cal.com API region. Options: `us` (default — `https://api.cal.com`), `eu` (`https://api.cal.eu`), `custom` (uses `calcom_custom_endpoint`)
* `calcom_custom_endpoint`: Custom Cal.com API base URL. Only used when `calcom_endpoint` is `custom` (e.g., `https://my-calcom-instance.com`).
* `calcom_event_id`: Cal.com event type ID. When provided, the event name is resolved from Cal.com automatically.
* `calcom_event_name`: Human-readable event name (e.g., `"30 Minute Meeting (30 min)"`). Resolved from Cal.com when `calcom_event_id` is provided, or set explicitly.
* `calcom_booking_fields`: Array of custom booking fields for the event. Each field has:
  * `slug` (required): Field identifier
  * `type` (required): Field type (e.g., "text", "email", "phone", "select")
  * `label` (required): Display label
  * `required`: Whether the field is required (default: `false`)
  * `options`: Array of options for select fields

Calendly fields (`calendar_type: "calendly"`):

* `calendly_api_key` (required): Your Calendly Personal Access Token (PAT). Generate one from your Calendly account: **Integrations & apps → API & webhooks → Generate new token**.
* `calendly_event_type_uri` (required): Full Calendly event type URI (e.g., `"https://api.calendly.com/event_types/{uuid}"`). Must belong to the authenticated PAT's account.

**assistant\_transfer** - Hand off the conversation to a different AI assistant mid-call (swaps voice, LLM, and STT to the target assistant)

* `assistant_id` (required): ID of the target assistant. Must belong to your account.
* `description`: When to transfer (max 500 chars, default: "Transfer the conversation to this assistant when appropriate.")
* `message_before_transfer`: Optional message the AI speaks before switching to the target assistant (max 500 chars).
* `speak_transfer_greeting`: If `true`, the target assistant speaks its configured initial message after the transfer completes (default: `true`).

```json theme={null}
"tools": [
  {
    "type": "call_transfer",
    "phone_number": "+1234567890",
    "description": "Transfer when customer requests human support"
  },
  {
    "type": "warm_call_transfer",
    "supervisor_phone": "+1234567891",
    "outbound_phone_id": 7,
    "description": "Transfer the call to a human supervisor when the customer requests to speak with a real person.",
    "custom_sip": false,
    "caller_id_mode": "outbound_number",
    "hold_music": "hold_music",
    "hold_music_volume": 80,
    "hold_message": "Please hold while I connect you with a supervisor.",
    "summary_instructions": "Introduce the conversation from your perspective:\n- WHO is calling (name, company if mentioned)\n- WHY they called (their goal or problem)\n- WHY a human is needed at this point\n\nKeep it brief (2-3 sentences).",
    "briefing_initial_message": "Hello! I have a caller on the line who needs your assistance. May I brief you on the situation?",
    "connected_message": "You are now connected with a supervisor. I'll leave you to it."
  },
  {
    "type": "collect_keypad",
    "timeout": 5,
    "stop_key": "#"
  },
  {
    "type": "assistant_transfer",
    "assistant_id": 14765,
    "description": "Transfer to the Support Assistant when the customer needs technical help.",
    "message_before_transfer": "Sure — let me transfer you to our support specialist.",
    "speak_transfer_greeting": true
  },
  {
    "type": "end_call",
    "description": "End call when customer confirms satisfaction"
  }
]
```

#### Voice and TTS Settings

**tts\_emotion\_enabled** `boolean` (default: true)

Whether to enable emotional text-to-speech synthesis

**voice\_stability** `number` (default: 0.70)

Voice stability setting (0-1). Higher = more consistent voice

**voice\_similarity** `number` (default: 0.50)

Voice similarity setting (0-1). Higher = closer to original voice

**speech\_speed** `number` (default: 1.00)

Speech speed multiplier (0.7-1.2)

**llm\_temperature** `number` (default: 0.10)

LLM temperature setting (0-1). Lower = more deterministic

**synthesizer\_provider\_id** `integer`

Custom TTS provider ID. Auto-selected based on language if not provided. Use the [Get Synthesizer Providers](https://docs.receptonic.com/api-reference/assistants/get-synthesizer-providers.md) endpoint to discover available providers.

**transcriber\_provider\_id** `integer`

Custom STT provider ID. Auto-selected based on language if not provided. Pipeline mode only. Use the [Get Transcriber Providers](https://docs.receptonic.com/api-reference/assistants/get-transcriber-providers.md) endpoint to discover available providers.

#### Call Behavior Settings

**allow\_interruptions** `boolean` (default: true)

Whether to allow caller interruptions.

> [!WARNING]
>
> Cannot be disabled for `multimodal` and `dualplex` modes.

**fillers** `boolean` (default: false)

Whether to use filler audio during processing (e.g., "um", "let me check").

> [!WARNING]
>
> Only available for `pipeline` mode.

**filler\_config** `object`

Custom filler word profiles per category. If not provided, defaults are set based on the assistant's language. Each category is an array of short phrases.

* `positive`: Filler words for positive/affirmative responses (e.g., "Great!", "Perfect!")
* `negative`: Filler words for negative/neutral responses (e.g., "Hmm.", "Mhm.")
* `question`: Filler words when processing a question (e.g., "Hmm.", "Let me think.")
* `neutral`: Filler words for neutral acknowledgments (e.g., "Ok.", "I understand.")

```json theme={null}
"filler_config": {
  "positive": ["Super!", "Great!", "Perfect!"],
  "negative": ["Hmm.", "Mhm.", "I see."],
  "question": ["Hmm.", "Let me check.", "Good question."],
  "neutral": ["Ok.", "I understand.", "Noted."]
}
```

**record** `boolean` (default: false)

Whether to record the call

**enable\_noise\_cancellation** `boolean` (default: true)

Whether to enable noise cancellation

**wait\_for\_customer** `boolean` (default: false)

If true, the assistant waits for the customer to speak first

#### Timing Settings

**max\_duration** `integer` (default: 600)

Maximum call duration in seconds (20-1200)

**max\_silence\_duration** `integer` (default: 40)

Maximum silence duration before re-engagement in seconds (1-360)

**max\_initial\_silence\_duration** `integer`

Maximum silence at call start before ending (1-120 seconds). Optional.

**ringing\_time** `integer` (default: 30)

Maximum ringing time before giving up (1-60 seconds)

#### Re-engagement Settings

**reengagement\_interval** `integer` (default: 30)

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?"`

#### Voicemail Settings

**end\_call\_on\_voicemail** `boolean` (default: true)

Whether to end call when voicemail is detected

**voice\_mail\_message** `string`

Message to leave on voicemail before hanging up (max 1000 characters)

#### Endpoint Detection

**endpoint\_type** `string` (default: vad)

Voice activity detection type. Options: `vad`, `ai`

**endpoint\_sensitivity** `number` (default: 0.5)

Endpoint sensitivity level (0-5)

**interrupt\_sensitivity** `number` (default: 0.5)

Interrupt sensitivity level (0-5)

**min\_interrupt\_words** `integer`

Minimum words before interruption is allowed (0-10). Set to enable.

#### Ambient Sound

**ambient\_sound** `string`

Background ambient sound. Options: `off`, `office`, `city`, `forest`, `crowded_room`, `cafe`, `nature`

**ambient\_sound\_volume** `number` (default: 0.5)

Ambient sound volume level (0-1)

#### Webhook Configuration

**is\_webhook\_active** `boolean` (default: false)

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` (default: true)

Whether to send webhooks only on completed calls (not failed/no-answer)

**include\_recording\_in\_webhook** `boolean` (default: true)

Whether to include recording URL in webhook payload

#### Post-Call Evaluation

**post\_call\_evaluation** `boolean` (default: true)

Whether to enable AI post-call evaluation

**post\_call\_schema** `array`

Schema definition for post-call data extraction

**post\_call\_schema properties**

**name** `string` *required*

Field name (3-16 chars, lowercase, alphanumeric and underscores only)

**type** `string` *required*

Data type. Options: `string`, `number`, `bool`

**description** `string` *required*

Description of what this field represents (3-255 characters)

```json theme={null}
"post_call_schema": [
  {"name": "status", "type": "bool", "description": "Was the call objective achieved"},
  {"name": "summary", "type": "string", "description": "Brief summary of the call"}
]
```

#### Variables

**variables** `object`

Key-value pairs of custom variables accessible in prompts via `{{variable_name}}`

```json theme={null}
"variables": {
  "company_name": "Acme Corp",
  "product": "Premium Widget",
  "support_email": "support@acme.com"
}
```

#### Conversation Ended Settings

**conversation\_inactivity\_timeout** `integer` (default: 30)

Minutes of chat inactivity before the conversation is considered ended (1-1440)

**conversation\_ended\_retrigger** `boolean` (default: false)

Whether to allow re-triggering the conversation after it ends due to inactivity

**conversation\_ended\_webhook\_url** `string`

Webhook URL called when a chat conversation ends due to inactivity. Separate from the main call webhook.

***

## Example Requests

### Pipeline Mode Assistant

```json theme={null}
{
  "name": "Sales Assistant",
  "voice_id": 1,
  "language_id": 1,
  "type": "outbound",
  "mode": "pipeline",
  "timezone": "Europe/Bucharest",
  "initial_message": "Hello! How can I help you today?",
  "system_prompt": "You are a professional sales assistant...",
  "llm_model_id": 2,
  "secondary_language_ids": [2, 3],
  "knowledgebase_id": 1,
  "knowledgebase_mode": "prompt",
  "fillers": true,
  "filler_config": {
    "positive": ["Great!", "Perfect!", "Awesome!"],
    "negative": ["Hmm.", "I see."],
    "question": ["Good question.", "Let me check."],
    "neutral": ["Ok.", "Noted.", "I understand."]
  },
  "tool_ids": [1, 5],
  "tools": [
    {
      "type": "end_call",
      "description": "End call when customer is satisfied"
    },
    {
      "type": "call_transfer",
      "phone_number": "+1234567890",
      "description": "Transfer to support"
    },
    {
      "type": "warm_call_transfer",
      "supervisor_phone": "+1234567891",
      "outbound_phone_id": 7,
      "description": "Transfer the call to a human supervisor when the customer requests to speak with a real person.",
      "custom_sip": false,
      "caller_id_mode": "outbound_number",
      "hold_music": "hold_music",
      "hold_music_volume": 80,
      "hold_message": "Please hold while I connect you with a supervisor.",
      "summary_instructions": "Introduce the conversation from your perspective:\n- WHO is calling (name, company if mentioned)\n- WHY they called (their goal or problem)\n- WHY a human is needed at this point\n\nKeep it brief (2-3 sentences).",
      "briefing_initial_message": "Hello! I have a caller on the line who needs your assistance. May I brief you on the situation?",
      "connected_message": "You are now connected with a supervisor. I'll leave you to it."
    },
    {
      "type": "collect_keypad",
      "timeout": 5,
      "stop_key": "#"
    }
  ],
  "reengagement_interval": 20,
  "reengagement_prompt": "Are you still there?"
}
```

### Multimodal Mode Assistant

```json theme={null}
{
  "name": "Support Bot",
  "voice_id": 41,
  "language_id": 1,
  "type": "inbound",
  "mode": "multimodal",
  "timezone": "America/New_York",
  "initial_message": "Hi! Welcome to support.",
  "system_prompt": "You are a helpful 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 Mode Assistant

```json theme={null}
{
  "name": "Premium Agent",
  "voice_id": 1,
  "language_id": 2,
  "type": "outbound",
  "mode": "dualplex",
  "timezone": "Europe/Bucharest",
  "initial_message": "Buna ziua!",
  "system_prompt": "Esti un asistent profesionist...",
  "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`

Success message confirming assistant creation

**data** `object`

**properties**

**id** `integer`

The unique identifier of the created assistant

**name** `string`

The name of the assistant

**status** `string`

The current status (`inactive` for new assistants)

**type** `string`

The type (`inbound` or `outbound`)

**mode** `string`

The engine mode (`pipeline`, `multimodal`, or `dualplex`)

```json 201 Success Response theme={null}
{
  "message": "Assistant created successfully",
  "data": {
    "id": 789,
    "name": "Sales Assistant",
    "status": "inactive",
    "type": "outbound",
    "mode": "pipeline"
  }
}
```

```json 422 Validation Error theme={null}
{
  "message": "Validation failed",
  "errors": {
    "name": ["The name field is required."],
    "voice_id": ["The selected voice is not compatible with the chosen engine type."],
    "knowledgebase_mode": ["Only function_call mode is available for multimodal assistants."]
  }
}
```

***

## Notes

* All required fields must be provided for successful assistant creation
* Use the Get Voices endpoint with `mode` parameter to get compatible voices
* For multimodal/dualplex modes, `knowledgebase_mode` must be `function_call`
* For multimodal/dualplex modes, `allow_interruptions` is always enabled
* Fillers are only available in pipeline mode
* The assistant is created with `inactive` status by default


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.