Assistants are AI-powered voice entities that handle phone conversations. Each assistant has its own personality, knowledge, and capabilities defined through configuration.The /api/v1/agents endpoint is deprecated but still works as an alias for /api/v1/assistants. Similarly, agent_id works as an alias for assistant_id in API requests.
Assistant Components#
An assistant consists of three main AI components:Speech-to-Text (STT)#
Converts the caller's speech to text. Currently powered by Deepgram.{
"stt_config": {
"provider": "deepgram",
"model": "nova-3-general",
"language": "en",
"keyterms": ["yes", "no", "okay"]
}
}
| Field | Description |
|---|
provider | STT provider (deepgram) |
model | Model name (e.g., nova-3-general) |
language | Language code (e.g., nl, en) |
keyterms | Optional array of words to boost recognition accuracy |
Language Model (LLM)#
The brain of your assistant. Processes the conversation and generates responses.{
"llm_config": {
"provider": "openai",
"model": "gpt-4o-mini",
"temperature": 0.7,
"messages": [
{
"role": "system",
"content": "You are a friendly customer service agent..."
}
],
"tools": []
}
}
| Field | Description |
|---|
provider | LLM provider (openai, mistral, xai, xai_realtime) |
model | Model name (e.g., gpt-4o-mini, claude-3-sonnet) |
temperature | Response randomness (0-2, default 0.7) |
messages | System prompts defining assistant behavior |
tools | Custom tools the assistant can use (see Custom Tools) |
xAI Text Models: The xai provider gives you access to Grok text models (e.g. grok-4-1-fast-non-reasoning) and uses the same API key as xai_realtime. Unlike xai_realtime, it operates as a standard text LLM and requires separate STT and TTS configuration.
Text-to-Speech (TTS)#
Converts the assistant's text responses to speech.{
"tts_config": {
"provider": "elevenlabs",
"model": "eleven_flash_v2_5",
"voice_id": "21m00Tcm4TlvDq8ikWAM",
"language": "nl",
"stability": 0.5,
"similarity_boost": 0.75,
"use_speaker_boost": true
}
}
| Provider | Description | Access |
|---|
elevenlabs | High-quality voice cloning and natural speech | All users |
inworld | EU-based TTS with natural Dutch voices (Katrien, Erik) | All users |
| Model | Description |
|---|
eleven_flash_v2_5 | Fastest, low-latency (default) |
eleven_v3 | Expressive dialogue with audio tag support |
eleven_multilingual_v2 | Best quality, multilingual |
eleven_turbo_v2_5 | Balanced speed and quality |
eleven_monolingual_v1 | English only |
Eleven v3 Audio Tags: When using eleven_v3, the LLM can insert audio tags in square brackets to control the emotional delivery of speech. For example, [sad], [laughing], [whispering], [cheerfully], or [cautiously]. Structure your system prompt to instruct the LLM to insert these tags before or within sentences. Example: [cheerfully] Welcome back! How can I help you today?
| Field | Description |
|---|
provider | TTS provider |
voice_id | Voice identifier (snake_case) |
language | Language code (e.g., nl, en) |
model | Model name (provider-specific) |
| Field | Description |
|---|
stability | Voice consistency (0-1, default 0.5) |
similarity_boost | Voice similarity to original (0-1, default 0.75) |
use_speaker_boost | Enhance speaker clarity (boolean) |
speed | Speech speed multiplier |
style | Speaking style intensity (0-1) |
Assistant Properties#
| Property | Type | Description |
|---|
id | UUID | Unique identifier (auto-generated) |
name | string | Display name for the assistant |
business_name | string | Business the assistant represents |
notification_email | email | Email for call notifications |
first_message | string | Initial greeting when call starts |
is_active | boolean | Whether assistant can handle calls |
voicemail_detection | boolean | Automatically detect voicemail |
voicemail_message | string | Message to leave on voicemail |
max_duration_seconds | number | Maximum call duration (null = unlimited) |
autonomous_silence_handling | boolean | Auto-detect silence and prompt caller |
webhook_url | URL | Endpoint for webhook events |
webhook_secret | string | Secret for signature verification |
webhook_events | array | Events to send to webhook |
analysis_plan | object | Post-call analysis configuration |
Creating an Assistant#
Only the name is required. All other fields have sensible defaults.Updating an Assistant#
Use PATCH to update specific fields. Only provided fields are updated.Deleting an Assistant#
When you delete an assistant, any phone numbers assigned to it will have their assistant_id set to null.Webhooks - Configure event notifications 
