AI

Create a new ai.

Changed on

Creates a new ai and returns the created ai's details.

post/ais

Request

  • Base URL
    https://api.voipbin.net/v1.0
  • URL
    https://api.voipbin.net/v1.0/ais
  • Auth
    none declared

Request body

namestring required
detailstring required
type'normal' | 'insight'

AI type. normal (default) is a general-purpose AI. insight limits the AI's built-in tools to the Insight tool set, adds the tools of the MCP servers in its own mcp_server_ids, and uses a dedicated system prompt.

engine_modelstring required

Model of the AI engine. Uses target.model format (e.g., openai.gpt-5). The target prefix identifies the provider, and the model name follows after the dot. The list of selectable models is returned by GET /ai_models. A value in the form openrouter.<author>/<slug> is also accepted (custom OpenRouter model, see model_id_prefix in GET /ai_models); in that case engine_key is required. A value in the form customendpoint.<model-id> selects an OpenAI-compatible server that you host; in that case engine_base_url is required and engine_base_key is optional. The customendpoint. model is not listed in GET /ai_models.

parameterobject required

Data associated with the ai's engine, can be dynamic and vary based on the engine type.

engine_keystring required

API key or credential for the AI engine. Required when engine_model starts with openrouter. (400 ENGINE_KEY_REQUIRED if empty).

engine_base_urlstring

Base URL of the customer-hosted OpenAI-compatible server. Required when engine_model starts with customendpoint. (400 ENGINE_BASE_URL_REQUIRED if empty); not allowed for any other model (400 ENGINE_BASE_URL_NOT_ALLOWED). Only https is accepted. Do not put credentials, tokens or other secrets in the URL; the URL is not secret and is returned in responses, events and webhooks. Send the key in engine_base_key instead.

engine_base_keystring nullable

API key for the server at engine_base_url. Write-only; never returned. Optional. Allowed only with a customendpoint. model. A key is 1 to 512 printable ASCII characters.

rag_idstring

The knowledge base ID (UUID) for the search_knowledge tool. Returned from the id field of the GET /rags response. Send empty string or omit to clear.

init_promptstring required
tts_typestring required

Text-to-speech engine type.

tts_voice_idstring required

Voice ID for the text-to-speech engine.

stt_typestring required

Speech-to-text engine type.

stt_languagestring

STT language in BCP-47 format (e.g., ko-KR, en-US).

tool_namesAIManagerToolName[]

List of tool names to enable for this AI. Use ["all"] to enable all available tools. For type=insight AIs, only Insight tool names are permitted (currently: get_contact_interactions, get_conversation_content, get_related_cases, get_case_notes, get_contact_profile, get_call_transcript, and notify_agent -- the one write tool, usable only while the assistant is monitoring a live call); type=normal AIs may use any Normal tool name or ["all"]. Mismatched combinations are rejected with a 400.

mcp_server_idsstring[]

List of customer-registered MCP server IDs whitelisted for this AI. Each ID must reference an MCP server owned by the same customer. Returned from the id field of the POST /mcpservers response.

auto_aicall_audit_enabledboolean

When true, any finished AICall involving this AI is audited automatically.

Example request

{
  "type": "normal",
  "engine_model": "openai.gpt-5",
  "engine_base_url": "https://llm.example.com/v1",
  "stt_language": "en-US",
  "vad_config": {
    "confidence": 0.7,
    "start_secs": 0.2,
    "stop_secs": 0.5,
    "min_volume": 0.6
  },
  "tool_names": [
    "connect_call"
  ],
  "mcp_server_ids": []
}

Response

Details of the created ai.

idstring uuid

The unique identifier of the AI.

customer_idstring uuid

The unique identifier of the associated customer. Returned from the GET /customers response.

namestring

Name of the AI.

detailstring

Detailed information about the AI.

type'normal' | 'insight'

AI type. normal (default) is a general-purpose AI. insight limits the AI's built-in tools to the Insight tool set, adds the tools of the MCP servers in its own mcp_server_ids, and uses a dedicated system prompt for analyzing existing contact/conversation data.

is_insight_activeboolean required

Whether this is the customer's active Insight AI, i.e. the one the Case Insight Assistant panel auto-attaches to a case. Only meaningful when type is insight. A customer may hold any number of Insight AIs but at most one may be active. Newly created AIs are always inactive; use POST /ais/{id}/activate_insight to activate one. When no Insight AI is active, the most recently created one is used.

engine_modelstring

Model of the AI engine. Uses target.model format (e.g., openai.gpt-5). The target prefix identifies the provider, and the model name follows after the dot. The list of selectable models is returned by GET /ai_models. A value in the form openrouter.<author>/<slug> is also accepted (custom OpenRouter model, see model_id_prefix in GET /ai_models); in that case engine_key is required. A value in the form customendpoint.<model-id> selects an OpenAI-compatible server that you host; in that case engine_base_url is required and engine_base_key is optional. The customendpoint. model is not listed in GET /ai_models.

parameterobject

Custom key-value configuration data specific to the AI engine type.

has_engine_keyboolean

Whether the AI holds an engine key (engine_key). A key kept on a platform model counts, although it is not used. The key itself is write-only and is never returned in responses.

engine_base_urlstring

Base URL of the customer-hosted OpenAI-compatible server. Set only when engine_model starts with customendpoint.. The key for that server (engine_base_key) is write-only and is never returned.

rag_idstring uuid

The knowledge base ID for the search_knowledge tool. Returned from the id field of the GET /rags response. When set, the AI assistant can search this knowledge base during voice calls.

init_promptstring

Initial prompt to configure the AI's behavior.

current_prompt_history_idstring uuid

UUID of the most-recent prompt history entry. Zero UUID means no versioned history has been recorded yet.

tts_type'' | 'async' | 'aws' | 'azure' | 'cartesia' | 'deepgram' | 'elevenlabs' | 'fish' | 'google' | 'groq' | 'hume' | 'inworld' | 'lmnt' | 'minimax' | 'neuphonic' | 'nvidia-riva' | 'openai' | 'piper' | 'playht' | 'rime' | 'sarvam' | 'xtts'

Text-to-speech provider type.

tts_voice_idstring

Text-to-speech voice identifier.

stt_type'' | 'cartesia' | 'deepgram' | 'elevenlabs'

Speech-to-text provider type.

stt_languagestring

STT language in BCP-47 format (e.g., ko-KR, en-US). Empty for auto-detect.

smart_turn_enabledboolean

Enable smart turn detection using Pipecat's LocalSmartTurnAnalyzerV3. When enabled, forces VAD stop_secs to 0.2 for optimal turn-taking.

auto_aicall_audit_enabledboolean

When true, any finished AICall involving this AI is audited automatically.

tool_namesAIManagerToolName[]

List of tool names enabled for this AI. Use ["all"] to enable all tools. See the Tool Functions documentation for detailed descriptions of each tool.

mcp_server_idsstring[]

List of customer-registered MCP server IDs whitelisted for this AI. Each ID must reference an MCP server owned by the same customer, returned from the id field of the POST /mcpservers or GET /mcpservers response. Tool use scope: a whitelisted server's tools are presented to this AI's single-AI sessions, including those of type=insight AIs; team-typed AI calls never receive MCP tools regardless of this list. Sessions that do discover and advertise include chat, voice calls, ai_task flow actions and API-created single-AI sessions, so expect tools/list (and, on a tool call, tools/call) requests authenticated per the server's auth_type in its logs. Of what is discovered, the tool names are stored on the AI session record and outlive the request, while the input schemas and descriptions are not stored. A usable server's tools are namespaced mcp_<server_id_prefix>_<tool_name> when presented to the model, up to 256 tools per session across this AI's whitelisted servers.

direct_hashstring

The direct hash for direct access via SIP URI sip:<direct_hash>@sip.voipbin.net (the "direct." prefix is already included in the value, e.g. "direct.a1b2c3d4e5f6"). Returned from the resource's direct_hash field.

tm_createstring date-time

Timestamp when the AI was created.

tm_updatestring date-time

Timestamp when the AI was last updated.

tm_deletestring date-time

Timestamp when the AI was deleted.

Example response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "customer_id": "7c4d2f3a-1b8e-4f5c-9a6d-3e2f1a0b4c5d",
  "name": "Customer Support Bot",
  "detail": "AI assistant for handling customer inquiries",
  "type": "normal",
  "engine_model": "openai.gpt-5",
  "has_engine_key": true,
  "engine_base_url": "https://llm.example.com/v1",
  "rag_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "init_prompt": "You are a helpful customer support assistant.",
  "current_prompt_history_id": "00000000-0000-0000-0000-000000000000",
  "tts_type": "elevenlabs",
  "tts_voice_id": "en-US-Neural2-F",
  "stt_type": "deepgram",
  "stt_language": "en-US",
  "vad_config": {
    "confidence": 0.7,
    "start_secs": 0.2,
    "stop_secs": 0.5,
    "min_volume": 0.6
  },
  "tool_names": [
    "all"
  ],
  "mcp_server_ids": [],
  "direct_hash": "direct.a1b2c3d4e5f6",
  "tm_create": "2026-01-15T09:30:00.000000Z",
  "tm_update": "2026-01-15T09:30:00.000000Z",
  "tm_delete": "2026-01-15T09:30:00.000000Z"
}

Changes