Create Assistant

Create a new assistant.

Creates a new voice assistant with the specified configuration. The assistant will be associated with the authenticated user’s organization.

POST /api/v1/assistants

Create Assistant

cURL

curl --request POST \
  --url https://api.example.com/api/v1/assistants \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "name": "<string>",
  "description": "<string>",
  "llm_provider": "openai",
  "llm_provider_config": {
    "api_key": "<string>",
    "base_url": "<string>",
    "model": "gpt-4o-mini",
    "custom_config": {}
  },
  "openai_api_key": "<string>",
  "custom_llm_url": "<string>",
  "deepgram_api_key": "<string>",
  "elevenlabs_api_key": "<string>",
  "twilio_config": {
    "account_sid": "<string>",
    "auth_token": "<string>"
  },
  "twilio_account_sid": "<string>",
  "twilio_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": "turbo",
    "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": "Are you still there? I'm here to help if you need anything.",
  "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
}
EOF

201

{
  "name": "<string>",
  "id": 123,
  "organization_id": 123,
  "user_id": 123,
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "description": "<string>",
  "llm_provider": "openai",
  "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": "turbo",
    "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": "Are you still there? I'm here to help if you need anything.",
  "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
}

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.

Basic Information

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

AI Configuration

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.

Call & Interruption Management

• 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

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

Advanced & Integration

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

Telephony Provider Selection:

• If multiple provider configs are provided, the system will use the one associated with assigned phone numbers.
• If no provider config is provided, the system uses your organization’s default telephony credentials.
• 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": [
        "[phone]"
      ]
    }
  },
  "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 · LLMProviderConfig · object

Configuration for the selected LLM provider.

Show child attributes

openai_api_key · string | null

custom_llm_url · string | null

deepgram_api_key · string | null

elevenlabs_api_key · string | null

twilio_config · TwilioConfig · object

Twilio account configuration.

Show child attributes

twilio_account_sid · string | null

twilio_auth_token · string | null

llm_settings · LLMSettings · object

Settings for the Large Language Model.

Show child attributes

webhook_url · string | null

interruption_settings · InterruptionSettings · object

Settings for call interruption behavior.

Show child attributes

tts_settings · TTSSettings · object

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

Show child attributes

stt_settings · STTSettings · object

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

Show child attributes

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 · ToolsSettings · object

Settings for integrated tools.

Show child attributes

rag_settings · RAGSettings · object

Settings for Retrieval-Augmented Generation (RAG).

Show child attributes

llm_fallback_providers · LLMFallbackSettings · object

Settings for LLM fallback providers.

Show child attributes

custom_settings · Custom Settings · object

is_active · boolean | null · default: true

Response

201

application/json

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 · LLMProviderConfig · object

Configuration for the selected LLM provider.

Show child attributes

twilio_config · TwilioConfig · object

Twilio account configuration.

Show child attributes

llm_settings · LLMSettings · object

Settings for the Large Language Model.

Show child attributes

webhook_url · string | null

interruption_settings · InterruptionSettings · object

Settings for call interruption behavior.

Show child attributes

tts_settings · TTSSettings · object

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

Show child attributes

stt_settings · STTSettings · object

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

Show child attributes

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 · ToolsSettings · object

Settings for integrated tools.

Show child attributes

rag_settings · RAGSettings · object

Settings for Retrieval-Augmented Generation (RAG).

Show child attributes

llm_fallback_providers · LLMFallbackSettings · object

Settings for LLM fallback providers.

Show child attributes

custom_settings · Custom Settings · object

is_active · boolean | null · default: true