Create Assistants

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 with different capabilities:

Mode	Description	Required Fields
`pipeline`	Classic 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

Required Core Fields

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

Mode-Specific Fields

llm_model_id

integer

The LLM model ID. Required for mode pipeline.Use the endpoint Retrieve Models to get available models.

multimodal_model_id

integer

The multimodal model ID. Required for modes multimodal and dualplex.Use the endpoint Retrieve 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 Languages

secondary_language_ids

integer[]

Array of additional language IDs that the assistant can speak. The assistant automatically recognizes the language and switches accordingly.

"secondary_language_ids": [2, 3, 4]

Knowledgebase Settings

knowledgebase_id

integer

The knowledgebase ID to attach to this assistant

knowledgebase_mode

string

How the knowledgebase is used. Options:

function_call - The AI calls a function to search (required for multimodal/dualplex)
prompt - Knowledge is injected into the prompt (only pipeline)

Phone Number

phone_number_id

integer

The ID of a phone number to assign to the assistant. Must belong to your account.

For inbound assistants, the phone number must not be a caller ID type and must not already be assigned to another inbound assistant.

Custom Mid-Call Tools

tool_ids

integer[]

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

"tool_ids": [1, 5, 12]

Built-in Tools

tools

array

Array of activated built-in tools. Each tool has a type field and tool-specific fields.

Show Tool Types

call_transfer - Transfer the call to another phone number

phone_number (required): Destination number (e.g., “+1234567890”)
description: When to transfer
custom: If true, the AI can dynamically determine the transfer number
timezone: Time zone for availabilities
warm_transfer: Message to the customer before transfer (default: false)
warm_transfer_message: Prompt for what the AI should say before the transfer (e.g., “Inform the customer the call is being transferred.”)

warm_call_transfer - Warm transfer with supervisor briefing

supervisor_phone (required): Phone number for the warm transfer (e.g., “+14155552001”). For custom_sip instead SIP address or internal extension.
outbound_phone_id (required): ID of the phone number used to call the supervisor. See Retrieve Phone Numbers.
description (required): When to transfer – when the AI should trigger the warm transfer (e.g., “Transfer to a human agent if the customer wants to speak to a real person.”)
custom_sip: Custom SIP address or internal extension instead of phone number (default: false)
caller_id_mode: Which number the supervisor sees. Options: outbound_number (default), customer_number, custom
custom_caller_id: Custom number for the supervisor, only with caller_id_mode: custom.
hold_music: Hold music. Options: hold_music (default), none
hold_music_volume: Hold music volume 0–100 (default: 80)
hold_message: Announcement to the caller before hold (default: “Please wait while I connect you to an agent.”)
summary_instructions: Instruction on how the AI should brief the supervisor (default: who is calling, why, why a human is needed – 2–3 sentences.)
briefing_initial_message: AI’s initial message to the supervisor (default: “Hello! I have a caller who needs assistance. May I briefly explain the situation?”)
connected_message: Message to the caller after connection with the supervisor (default: “You are now connected to an agent.”)

end_call - Programmatically end the call

description: When the AI should end the call

dtmf_input - Send DTMF tones (keypad input)

description: When to use DTMF (e.g., IVR navigation)

collect_keypad - Collect keypad input from the caller

timeout: Wait time in seconds, 1–30 (default: 5)
stop_key: Key to end input. Options: # (default), *

calendar_integration - Schedule appointments via Cal.com

calcom_api_key (required): Your Cal.com API key
calcom_event_slug (required): Event type slug from Cal.com
calcom_team_slug: Team slug if the event belongs to a Cal.com team
calcom_endpoint: 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 URL. Only for calcom_endpoint: custom (e.g., https://my-calcom-instance.com).
calcom_booking_fields: Array of custom booking fields. Each field: slug, type, label, optionally required, options for select.
description: When to offer appointment booking

"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 to a human agent if the customer wants to speak to a real person.",
    "custom_sip": false,
    "caller_id_mode": "outbound_number",
    "hold_music": "hold_music",
    "hold_music_volume": 80,
    "hold_message": "Please wait while I connect you to an agent.",
    "summary_instructions": "Briefly from your perspective: Who is calling, why, why a human is needed. 2–3 sentences.",
    "briefing_initial_message": "Hello! I have a caller who needs assistance. May I briefly explain the situation?",
    "connected_message": "You are now connected to an agent."
  },
  {
    "type": "collect_keypad",
    "timeout": 5,
    "stop_key": "#"
  },
  {
    "type": "end_call",
    "description": "End call when customer confirms satisfaction"
  }
]

Voice and TTS Settings

tts_emotion_enabled

boolean

default:"true"

Whether emotional text-to-speech synthesis is enabled

voice_stability

number

default:"0.70"

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

voice_similarity

number

default:"0.50"

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

speech_speed

number

default:"1.00"

Speech speed multiplier (0.7-1.2)

llm_temperature

number

default:"0.10"

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.

transcriber_provider_id

integer

Custom STT provider ID. If not set, selected automatically based on language. Only for pipeline. See Retrieve Transcriber Providers.

Call Behavior Settings

allow_interruptions

boolean

default:"true"

Whether interruptions from the caller are allowed.

Cannot be disabled for multimodal and dualplex.

fillers

boolean

default:"false"

Whether filler audio should be used during processing (e.g., “uh”, “just a moment”).

Only available in pipeline mode.

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.”)

"filler_config": {
  "positive": ["Great!", "Perfect!", "Very good!"],
  "negative": ["Hmm.", "Understood.", "Okay."],
  "question": ["Good question.", "One moment.", "Let me check."],
  "neutral": ["Okay.", "Understood.", "Noted."]
}

record

boolean

default:"false"

Whether the call should be recorded

enable_noise_cancellation

boolean

default:"true"

Whether noise cancellation should be enabled

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

default:"30"

Maximum ringing time before canceling (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 the call if voicemail is detected

voice_mail_message

string

Message to leave on voicemail (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 (0-5)

interrupt_sensitivity

number

default:"0.5"

Interrupt sensitivity (0-5)

min_interrupt_words

integer

Minimum number of 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 (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 for completed calls (not for failed/no-answer)

include_recording_in_webhook

boolean

default:"true"

Whether to include the recording URL in the webhook payload

Post-Call Evaluation

post_call_evaluation

boolean

default:"true"

Whether AI post-call evaluation is enabled

post_call_schema

array

Schema definition for post-call data extraction

Show post_call_schema Properties

name

string

required

Field name (3-16 characters, 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)

"post_call_schema": [
  {"name": "status", "type": "bool", "description": "Whether the call objective was met"},
  {"name": "summary", "type": "string", "description": "Brief summary of the call"}
]

Variables

variables

object

Key-value pairs of custom variables that can be used in prompts via {{variable_name}}

"variables": {
  "company_name": "Acme GmbH",
  "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 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.

Example Requests

`pipeline` Mode Assistant

{
  "name": "Sales Assistant",
  "voice_id": 1,
  "language_id": 1,
  "type": "outbound",
  "mode": "pipeline",
  "timezone": "Europe/Berlin",
  "initial_message": "Hello! How can I assist 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!", "Very good!"],
    "negative": ["Hmm.", "Understood."],
    "question": ["Good question.", "One moment."],
    "neutral": ["Okay.", "Noted.", "Understood."]
  },
  "tool_ids": [1, 5],
  "tools": [
    {"type": "end_call", "description": "End call when the 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 to a human agent if the customer wants to speak to a real person.",
      "custom_sip": false,
      "caller_id_mode": "outbound_number",
      "hold_music": "hold_music",
      "hold_music_volume": 80,
      "hold_message": "Please wait while I connect you to an agent.",
      "summary_instructions": "Briefly from your perspective: Who is calling, why, why a human is needed. 2–3 sentences.",
      "briefing_initial_message": "Hello! I have a caller who needs assistance. May I briefly explain the situation?",
      "connected_message": "You are now connected to an agent."
    },
    {"type": "collect_keypad", "timeout": 5, "stop_key": "#"}
  ],
  "reengagement_interval": 20,
  "reengagement_prompt": "Are you still there?"
}

`multimodal` Mode Assistant

{
  "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

{
  "name": "Premium Agent",
  "voice_id": 1,
  "language_id": 2,
  "type": "outbound",
  "mode": "dualplex",
  "timezone": "Europe/Berlin",
  "initial_message": "Good day!",
  "system_prompt": "You are a professional assistant...",
  "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 the creation of the assistant

data

object

Show properties

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)

{
  "message": "Assistant created successfully",
  "data": {
    "id": 789,
    "name": "Sales Assistant",
    "status": "inactive",
    "type": "outbound",
    "mode": "pipeline"
  }
}

Notes

All required fields must be provided for successful creation
Use the endpoint Retrieve Voices with the query parameter mode to obtain compatible voices
For multimodal/dualplex, knowledgebase_mode must be set to function_call
For multimodal/dualplex, allow_interruptions is always enabled
fillers is only available in pipeline mode
New assistants are created with status inactive by default

API Reference

AI Assistants

Leads

Campaigns

Mid Call Tools

AI Chatbot

AI Replies

Knowledgebases

SMS

WhatsApp

Phone Numbers

Calls

Webhooks

Create Assistants

Engine Modes

Request Body

Required Core Fields

Mode-Specific Fields

Secondary Languages

Knowledgebase Settings

Phone Number

Custom Mid-Call Tools

Built-in Tools

Voice and TTS Settings

Call Behavior Settings

Timing Settings

Re-Engagement Settings

Voicemail Settings

Endpoint Detection

Ambient Sound

Webhook Configuration

Post-Call Evaluation

Variables

Conversation-Ended Settings

Example Requests

`pipeline` Mode Assistant

`multimodal` Mode Assistant

`dualplex` Mode Assistant

Response

Notes

API Reference

AI Assistants

Leads

Campaigns

Mid Call Tools

AI Chatbot

AI Replies

Knowledgebases

SMS

WhatsApp

Phone Numbers

Calls

Webhooks

​Engine Modes

​Request Body

​Required Core Fields

​Mode-Specific Fields

​Secondary Languages

​Knowledgebase Settings

​Phone Number

​Custom Mid-Call Tools

​Built-in Tools

​Voice and TTS Settings

​Call Behavior Settings

​Timing Settings

​Re-Engagement Settings

​Voicemail Settings

​Endpoint Detection

​Ambient Sound

​Webhook Configuration

​Post-Call Evaluation

​Variables

​Conversation-Ended Settings

​Example Requests

​pipeline Mode Assistant

​multimodal Mode Assistant

​dualplex Mode Assistant

​Response

​Notes

Engine Modes

Request Body

Required Core Fields

Mode-Specific Fields

Secondary Languages

Knowledgebase Settings

Phone Number

Custom Mid-Call Tools

Built-in Tools

Voice and TTS Settings

Call Behavior Settings

Timing Settings

Re-Engagement Settings

Voicemail Settings

Endpoint Detection

Ambient Sound

Webhook Configuration

Post-Call Evaluation

Variables

Conversation-Ended Settings

Example Requests

`pipeline` Mode Assistant

`multimodal` Mode Assistant

`dualplex` Mode Assistant

Response

Notes