Skip to main content
POST
/
api
/
v1
/
assistants
{
  "name": "<string>",
  "description": "<string>",
  "llm_provider": "<string>",
  "llm_provider_config": {
    "api_key": "<string>",
    "base_url": "<string>",
    "model": "gpt-4o-mini",
    "custom_config": {}
  },
  "twilio_config": {
    "account_sid": "<string>",
    "auth_token": "<string>"
  },
  "llm_settings": {
    "temperature": 0.5,
    "max_tokens": 1000,
    "system_prompt": "You are a helpful assistant that can answer questions and help with tasks.",
    "welcome_message": "<string>",
    "top_p": 1,
    "frequency_penalty": 0,
    "presence_penalty": 0,
    "stop_sequences": [
      "<string>"
    ]
  },
  "webhook_url": "<string>",
  "interruption_settings": {
    "interruption_threshold": 3,
    "min_speaking_time": 0.5,
    "interruption_cooldown": 2
  },
  "tts_settings": {
    "provider": "elevenlabs",
    "voice_id": "rachel",
    "model_id": "<string>",
    "latency": 1,
    "stability": 0.5,
    "similarity_boost": 0.75,
    "style": 0,
    "use_speaker_boost": true,
    "provider_config": {}
  },
  "stt_settings": {
    "model": "nova-2",
    "language": "en-US",
    "punctuate": true,
    "interim_results": true,
    "endpointing": {
      "silence_threshold": 500,
      "min_silence_duration": 500
    },
    "utterance_end_ms": 1000,
    "vad_turnoff": 500,
    "smart_format": true,
    "keywords": [
      {
        "keyword": "<string>",
        "intensifier": 1
      }
    ],
    "keyterms": [
      "<string>"
    ],
    "audio_denoising": false
  },
  "end_call_message": "<string>",
  "transfer_call_message": "<string>",
  "idle_message": "<string>",
  "max_idle_messages": 123,
  "idle_timeout": 123,
  "tools_settings": {
    "enabled_tools": [
      "<string>"
    ],
    "end_call": {
      "enabled": false,
      "scenarios": [
        "<string>"
      ],
      "custom_message": "<string>"
    },
    "transfer_call": {
      "enabled": false,
      "scenarios": [
        "<string>"
      ],
      "transfer_numbers": [
        "<string>"
      ],
      "custom_message": "<string>"
    },
    "custom_tools": [
      {}
    ]
  },
  "rag_settings": {
    "enabled": false,
    "search_limit": 3,
    "similarity_threshold": 0.7,
    "embedding_model": "text-embedding-3-small",
    "chunking_strategy": "recursive",
    "chunk_size": 1000,
    "chunk_overlap": 200,
    "auto_process": true,
    "include_metadata": true,
    "context_window_tokens": 4000
  },
  "llm_fallback_providers": {
    "enabled": false,
    "fallbacks": [
      {
        "provider": "<string>",
        "api_key": "<string>",
        "base_url": "<string>",
        "model": "<string>"
      }
    ]
  },
  "custom_settings": {},
  "is_active": true,
  "id": 123,
  "organization_id": 123,
  "user_id": 123,
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}
This endpoint allows you to create a new, fully configured voice AI assistant. The parameters available via the API directly correspond to the settings you can configure in the assistant creation form in the web UI. A successful request will create the assistant within your organization and return the full assistant object, including its unique ID.

​
Request Body

The request body is a JSON object containing the assistant’s configuration. The parameters are organized into logical groups that mirror the sections in the UI. Many parameters are conditional based on the provider or options you select.
  • name (string, required): A unique name for your assistant.
  • description (string, optional): A brief description of the assistant’s purpose.
  • is_active (boolean, optional): Set to true to allow the assistant to handle calls. Defaults to true.
This section covers the core AI models for language, speech-to-text, and text-to-speech.LLM (Language Model)
  • llm_provider (string): The language model provider.
    • Enum: "openai", "anthropic", "gemini", "groq", "xai", "custom". Defaults to openai.
  • llm_provider_config (object): Provider-specific configuration.
    • api_key (string, required): The API key for the selected provider.
    • model (string, optional): The specific model to use (e.g., gpt-4o-mini).
    • base_url (string, optional): A custom API base URL. Required if llm_provider is custom.
  • llm_settings (object): General parameters for the language model.
    • temperature (number): Controls creativity. Defaults to 0.7.
    • max_tokens (integer): Max length of the AI’s response in tokens. Defaults to 1000.
    • system_prompt (string): The AI’s personality and instructions.
    • welcome_message (string): The first thing the assistant says to the caller.
  • llm_fallback_providers (object, optional): Configure backup LLM providers.
    • enabled (boolean): Set to true to enable fallbacks.
    • fallbacks (array of objects): An ordered list of fallback providers. Each object contains provider, model, api_key, and base_url.
TTS (Text-to-Speech)
  • tts_settings (object):
    • provider (string): The TTS provider. Enum: "elevenlabs", "deepgram", "inworld", "resemble".
    • voice_id (string): The specific voice character to use (e.g., rachel).
    • model_id (string, optional): The voice model (e.g., eleven_flash_v2_5).
    • Conditional Fields:
      • If provider is elevenlabs:
        • stability (number): Voice consistency.
        • similarity_boost (number): Voice accuracy.
        • style (number): Speaking style variation.
        • use_speaker_boost (boolean): Enhances audio quality.
      • If provider is resemble:
        • provider_config.project_uuid (string): Your Resemble AI project UUID.
      • If provider is inworld:
        • provider_config.language (string): Language code (e.g., en).
STT (Speech-to-Text)
  • stt_settings (object):
    • model (string): The STT model (e.g., nova-2, nova-3).
    • language (string): Language code (e.g., en-US).
    • keywords (array of objects, optional): An array of keywords to boost. Each object should have a keyword (string) and an optional intensifier (float). For nova-2 and older models.
    • keyterms (array of strings, optional): An array of key terms to boost. For nova-3 model only.
  • interruption_settings (object):
    • interruption_threshold (integer): Number of words a user must speak to interrupt.
    • min_speaking_time (number): How long the assistant must speak before being interruptible (in seconds).
    • interruption_cooldown (number): Cooldown period after an interruption (in seconds).
  • idle_message (string, optional): Message sent when the caller is silent.
  • max_idle_messages (integer, optional): How many idle messages to send before ending the call.
  • idle_timeout (integer, optional): Seconds of silence before sending an idle message.
  • tools_settings (object): Configure built-in tools.
    • end_call (object, optional):
      • enabled (boolean): Enable/disable the tool.
      • scenarios (array of strings): Phrases that will trigger ending the call.
    • transfer_call (object, optional):
      • enabled (boolean): Enable/disable the tool.
      • scenarios (array of strings): Phrases that will trigger a transfer.
      • transfer_numbers (array of strings): Phone numbers where calls can be transferred.
  • custom_settings (object, optional): For advanced data extraction.
    • structured_data_prompt (string): Custom instructions for the AI on how to extract data.
    • structured_data_schema (object): A JSON schema defining the data to be extracted.
  • twilio_config (object, optional): Bring your own Twilio credentials.
    • account_sid (string): Your Twilio Account SID.
    • auth_token (string): Your Twilio Auth Token.
  • telnyx_config (object, optional): Bring your own Telnyx credentials.
    • api_key (string): Your Telnyx API Key.
    • connection_id (string): Your Telnyx Connection ID for Call Control Application.
  • webhook_url (string, optional): A URL to send call event webhooks to.
  • sms_webhook_url (string, optional): A URL to send SMS event webhooks to.
  • messaging_service_sid (string, optional): Twilio Messaging Service SID for SMS handling. If not provided, uses the default from environment variables.
Telephony Provider Selection:
  • If both twilio_config and telnyx_config are provided, Telnyx takes priority.
  • If neither is provided, the system uses environment variables (TWILIO_* or TELNYX_*).
  • Each assistant can use a different telephony provider.

​
Example Request

Here is an example payload that mirrors the fields available in the UI to create a sophisticated customer service assistant. Note that fields like scenarios and transfer_numbers expect a JSON array of strings.

​
Example: Twilio Assistant

{
  "name": "ServiceBot 5000",
  "description": "Handles initial customer service questions and escalations.",
  "is_active": true,
  "llm_provider": "openai",
  "llm_provider_config": {
    "model": "gpt-4o-mini",
    "api_key": "sk-your-openai-api-key"
  },
  "llm_settings": {
    "temperature": 0.7,
    "max_tokens": 1000,
    "system_prompt": "You are a friendly and efficient customer support agent. Your goal is to help with common questions and transfer to a human when requested.",
    "welcome_message": "Hello! Thanks for calling support. How can I assist you today?"
  },
  "tts_settings": {
    "provider": "elevenlabs",
    "voice_id": "rachel",
    "model_id": "eleven_flash_v2_5",
    "stability": 0.5,
    "similarity_boost": 0.75,
    "style": 0.0,
    "use_speaker_boost": true
  },
  "stt_settings": {
    "model": "nova-2",
    "language": "en-US",
    "keywords": [
        {"keyword": "agent", "intensifier": 1.5},
        {"keyword": "human"},
        {"keyword": "representative"}
    ]
  },
  "interruption_settings": {
    "interruption_threshold": 3,
    "min_speaking_time": 0.5,
    "interruption_cooldown": 2.0
  },
  "idle_message": "Are you still there? I'm here to help if you need anything.",
  "max_idle_messages": 2,
  "idle_timeout": 20,
  "tools_settings": {
    "transfer_call": {
      "enabled": true,
      "scenarios": [
        "speak to an agent",
        "talk to a human",
        "transfer me to a representative"
      ],
      "transfer_numbers": [
        "+18005551212"
      ]
    }
  },
  "twilio_config": {
    "account_sid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "auth_token": "your_twilio_auth_token"
  },
  "webhook_url": "https://yourapi.com/webhooks/call-events"
}

​
Example: Telnyx Assistant

{
  "name": "SalesBot Pro",
  "description": "Modern sales assistant using Telnyx for competitive call rates.",
  "is_active": true,
  "llm_provider": "openai",
  "llm_provider_config": {
    "model": "gpt-4o-mini",
    "api_key": "sk-your-openai-api-key"
  },
  "llm_settings": {
    "temperature": 0.8,
    "max_tokens": 1000,
    "system_prompt": "You are an enthusiastic sales representative. Help qualify leads and schedule demos.",
    "welcome_message": "Hi there! Thanks for your interest in our product. How can I help you today?"
  },
  "tts_settings": {
    "provider": "elevenlabs",
    "voice_id": "charlie",
    "model_id": "eleven_flash_v2_5",
    "stability": 0.6,
    "similarity_boost": 0.8,
    "use_speaker_boost": true
  },
  "stt_settings": {
    "model": "nova-3",
    "language": "en-US",
    "keyterms": ["demo", "pricing", "features", "schedule"]
  },
  "telnyx_config": {
    "api_key": "KEYxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "connection_id": "1234567890"
  },
  "webhook_url": "https://yourapi.com/webhooks/telnyx-events"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Schema for creating a new assistant.

​
name
string
required
​
description
string | null
​
llm_provider
string | null
default:openai

LLM provider: openai, anthropic, gemini, xai, groq, custom

​
llm_provider_config
object

Configuration for the selected LLM provider.

​
openai_api_key
string | null
​
custom_llm_url
string | null
​
deepgram_api_key
string | null
​
elevenlabs_api_key
string | null
​
twilio_config
object

Twilio account configuration.

​
twilio_account_sid
string | null
​
twilio_auth_token
string | null
​
llm_settings
object

Settings for the Large Language Model.

​
webhook_url
string | null
​
interruption_settings
object

Settings for call interruption behavior.

​
tts_settings
object

Settings for Text-to-Speech (TTS) service.

​
stt_settings
object

Settings for Speech-to-Text (STT) service.

​
end_call_message
string | null
​
transfer_call_message
string | null
​
idle_message
string | null
default:Are you still there? I'm here to help if you need anything.
​
max_idle_messages
integer | null
​
idle_timeout
integer | null
​
tools_settings
object

Settings for integrated tools.

​
rag_settings
object

Settings for Retrieval-Augmented Generation (RAG).

​
llm_fallback_providers
object

Settings for LLM fallback providers.

​
custom_settings
object | null
​
is_active
boolean | null
default:true

Response

Successful Response

Schema for assistant response.

​
name
string
required
​
id
integer
required
​
organization_id
integer
required
​
user_id
integer
required
​
created_at
string<date-time>
required
​
updated_at
string<date-time>
required
​
description
string | null
​
llm_provider
string | null
default:openai

LLM provider: openai, anthropic, gemini, xai, groq, custom

​
llm_provider_config
object

Configuration for the selected LLM provider.

​
twilio_config
object

Twilio account configuration.

​
llm_settings
object

Settings for the Large Language Model.

​
webhook_url
string | null
​
interruption_settings
object

Settings for call interruption behavior.

​
tts_settings
object

Settings for Text-to-Speech (TTS) service.

​
stt_settings
object

Settings for Speech-to-Text (STT) service.

​
end_call_message
string | null
​
transfer_call_message
string | null
​
idle_message
string | null
default:Are you still there? I'm here to help if you need anything.
​
max_idle_messages
integer | null
​
idle_timeout
integer | null
​
tools_settings
object

Settings for integrated tools.

​
rag_settings
object

Settings for Retrieval-Augmented Generation (RAG).

​
llm_fallback_providers
object

Settings for LLM fallback providers.

​
custom_settings
object | null
​
is_active
boolean | null
default:true