Create assistant

Create a new AI assistant with specified configuration

POST /user/assistant

Create assistant

cURL

curl --request POST \
  --url https://app.autocalls.ai/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>"
}
'

201 Success Response

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

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 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 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 endpoint to get available models.

multimodal_model_id · integer

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

Use the Get Models 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.

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

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

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

Show Tool types

call_transfer - Transfer the call to another phone number

• phone_number (required): Phone number to transfer to (e.g., “[phone]”)
• 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., “[phone]”). 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 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

• 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_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
• description: When to offer scheduling

"tools": [
  {
    "type": "call_transfer",
    "phone_number": "[phone]",
    "description": "Transfer when customer requests human support"
  },
  {
    "type": "warm_call_transfer",
    "supervisor_phone": "[phone]",
    "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": "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 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 endpoint to discover available providers.

Call Behavior Settings

allow_interruptions · boolean · default: "true"

Whether to allow caller interruptions.

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

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

"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

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

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

"variables": {
  "company_name": "Acme Corp",
  "product": "Premium Widget",
  "support_email": "[e-mail]"
}

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

{
  "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": "[phone]",
      "description": "Transfer to support"
    },
    {
      "type": "warm_call_transfer",
      "supervisor_phone": "[phone]",
      "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

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

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

201 Success Response

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