Skip to main content
POST
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:

Request Body

Required Core Fields

string
required
The name of the assistant (max. 255 characters)
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.
integer
required
The language ID for the assistant. Use the endpoint Retrieve Languages to get available languages.
string
required
The assistant type. Options: inbound, outbound
string
required
The engine mode. Options: pipeline, multimodal, dualplex
string
required
The time zone of the assistant (e.g., “Europe/Berlin”, “America/New_York”)
string
required
The first message the assistant speaks at the start of the call (max. 200 characters)
string
required
The system prompt that defines the assistant’s behavior and personality

Mode-Specific Fields

integer
The LLM model ID. Required for mode pipeline.Use the endpoint Retrieve Models to get available models.
integer
The multimodal model ID. Required for modes multimodal and dualplex.Use the endpoint Retrieve Models to get available multimodal models.
integer
Fallback LLM model ID for tool calls in multimodal/dualplex. Optional.
number
Sensitivity of turn detection in multimodal/dualplex (0-1). Default: auto

Secondary Languages

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

Knowledgebase Settings

integer
The knowledgebase ID to attach to this assistant
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

integer
ID of a folder to place this assistant in. Must belong to your account. Send null to leave the assistant uncategorized.
integer[]
Array of label IDs to apply to this assistant. Each label must belong to your account.

Phone Number

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

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

Built-in Tools

array
Array of built-in tools. Each tool has a type field and tool-specific fields. On Update Assistant, this replaces all existing built-in tools — pass an empty array [] to remove all tools.
When you list assistants, each configured tool is returned as { "type": "...", "data": { ... } } with the same field names nested under data (not top-level).

Voice and TTS Settings

boolean
default:"true"
Whether emotional text-to-speech synthesis is enabled
number
default:"0.70"
Voice stability (0-1). Higher = more consistent
number
default:"0.50"
Voice similarity (0-1). Higher = closer to the original
number
default:"1.00"
Speech speed multiplier (0.7-1.2)
number
default:"0.10"
LLM temperature (0-1). Lower = more deterministic
integer
Custom TTS provider ID. If not set, selected automatically based on language. See Retrieve Synthesizer Providers.
integer
Custom STT provider ID. If not set, selected automatically based on language. Only for pipeline. See Retrieve Transcriber Providers.

Call Behavior Settings

boolean
default:"true"
Whether interruptions from the caller are allowed.
Cannot be disabled for multimodal and dualplex.
boolean
default:"false"
Whether filler audio should be used during processing (e.g., “uh”, “just a moment”).
Only available in pipeline mode.
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.”)
boolean
default:"false"
Whether the call should be recorded
boolean
default:"true"
Whether noise cancellation should be enabled
boolean
default:"false"
If true, the assistant waits for the customer to speak first

Timing Settings

integer
default:"600"
Maximum call duration in seconds (20-1200)
integer
default:"40"
Maximum silence duration until re-engagement in seconds (1-360)
integer
Maximum silence directly after call start before termination (1-120 seconds). Optional.
integer
default:"30"
Maximum ringing time before canceling (1-60 seconds)

Re-Engagement Settings

integer
default:"30"
Re-engagement interval in seconds (7-600)
string
Custom prompt for re-engagement messages (max. 1000 characters)Example: "Are you still there? Do you have any other questions?"

Voicemail Settings

boolean
default:"true"
Whether to end the call if voicemail is detected
string
Message to leave on voicemail (max. 1000 characters)

Endpoint Detection

string
default:"vad"
Voice activity detection type. Options: vad, ai
number
default:"0.5"
Endpoint sensitivity (0-5)
number
default:"0.5"
Interrupt sensitivity (0-5)
integer
Minimum number of words before interruption is allowed (0-10). Set to enable.

Ambient Sound

string
Background ambient sound. Options: off, office, city, forest, crowded_room, cafe, nature
number
default:"0.5"
Ambient sound volume (0-1)

Webhook Configuration

boolean
default:"false"
Whether webhook notifications are enabled
string
The webhook URL for post-call notifications. Required if is_webhook_active is true.
boolean
default:"true"
Whether to send webhooks only for completed calls (not for failed/no-answer)
boolean
default:"true"
Whether to include the recording URL in the webhook payload

Post-Call Evaluation

boolean
default:"true"
Whether AI post-call evaluation is enabled
array
Schema definition for post-call data extraction

Variables

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

Conversation-Ended Settings

integer
default:"30"
Minutes of chat inactivity before the conversation is considered ended (1–1440)
boolean
default:"false"
Whether the conversation can be restarted after inactivity end
string
Webhook URL invoked when a chat conversation ends due to inactivity. Separate from the call webhook.

Example Requests

pipeline Mode Assistant

multimodal Mode Assistant

dualplex Mode Assistant


Response

string
Success message confirming the creation of the assistant
object

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