Create assistant

Create a new AI assistant with specified configuration

POST https://app.voiz.mx/api//user/assistant

Create assistant

cURL

curl --request POST \
  --url https://app.voiz.mx/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,
  "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": {}
}
'

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

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)

calendar_integration - Schedule appointments via Cal.com

• calcom_api_key (required): Your Cal.com API key
• calcom_event_slug (required): The event type slug
• description: When to offer scheduling

"tools": [
  {
    "type": "call_transfer",
    "phone_number": "[phone]",
    "description": "Transfer when customer requests human support"
  },
  {
    "type": "dtmf_input",
    "description": "Navigate IVR menus when needed"
  },
  {
    "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.

transcriber_provider_id · integer

Custom STT provider ID. Auto-selected based on language if not provided. Pipeline mode only.

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.

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

---

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