---
title: "Create a voice AI agent"
method: POST
path: "/v1/agents"
tags: ["Agents", "Agents"]
---

# Create a voice AI agent

`POST /v1/agents`

## Request

- Base URL: `https://api.call2me.app`
- URL: `https://api.call2me.app/v1/agents`
- Auth: HTTP bearer

Create a new voice AI agent. Required: `agent_name`, `response_engine` (which LLM and how to invoke it), and a `voice_id` from `/v1/voices`. Optional: `system_prompt`, `first_message`, `language`, `interruption_sensitivity`, `knowledge_base_ids` and `function_definitions`.

Agent creation no longer requires email verification.

## Request body

- CreateAgentRequest: Request to create a new voice agent.
  - `agent_name` string, required: Human-readable name for the agent
  - `voice_id` string, required: Voice identifier (e.g., 'openai-nova', 'azure-tr-emel')
  - `response_engine` union, required: LLM configuration (built-in or custom)
    - BuiltinLLMEngine: Built-in LLM configuration using platform's LLM service.
      - `type` 'call2me-llm'
      - `system_prompt` string, required: System prompt that defines agent behavior
      - `llm_provider` 'openai' | 'gemini' | 'anthropic' | 'openrouter': LLM provider to use
      - `llm_model` string: Model identifier
      - `temperature` number: Sampling temperature
      - `engine` 'cascade' | 'realtime': Voice engine: cascade (STT→LLM→TTS) or realtime (GPT Realtime speech-to-speech).
      - `max_tokens` integer: Maximum tokens in response
      - `builtin_functions` string[], nullable: Enabled built-in functions: end_call, transfer_call, hold_call, dtmf_input
      - `functions` object[], nullable: Function definitions for tool calling
    - CustomLLMEngine: Custom LLM configuration via WebSocket.
      - `type` 'custom-llm'
      - `llm_websocket_url` string, required: WebSocket URL for custom LLM server
  - `language` string: BCP-47 language code
  - `voice_speed` number: Voice playback speed
  - `responsiveness` number: How quickly agent responds (0=slow, 1=immediate)
  - `interruption_sensitivity` number: How easily user can interrupt (0=hard, 1=easy)
  - `enable_backchannel` boolean: Enable 'uh-huh', 'hmm' responses
  - `backchannel_frequency` number: How often to backchannel (0=never, 1=always)
  - `backchannel_words` string[]: Custom backchannel words (empty = use defaults for language)
  - `begin_message` string, nullable: First message when call starts (used when begin_message_mode='static')
  - `begin_message_mode` string: 'static': use begin_message as-is, 'dynamic': LLM generates greeting based on system prompt and call context
  - `reminder_message_frequency_ms` integer: Send reminder after this much silence (ms)
  - `reminder_max_count` integer: Max reminder messages before ending call (0=disabled)
  - `end_call_after_silence_ms` integer: End call after this much silence (ms)
  - `max_call_duration_ms` integer: Maximum call duration (ms)
  - `enable_recording` boolean: Enable call recording
  - `enable_vcon_export` boolean: Allow exporting this agent's calls as vCon containers
  - `webhook_url` string, nullable: URL for webhook events
  - `transfer_targets` object[], nullable: Transfer targets: [{'name': 'Support', 'type': 'phone|sip|agent|external|queue', 'value': '...'}]
  - `post_call_extraction` object[], nullable: Fields to extract from call (e.g., [{'name': 'customer_name', 'type': 'string', 'description': 'Customer name'}])
  - `post_call_extraction_model` string, nullable: LLM model for post-call extraction
  - `post_call_actions` object[], nullable: Actions triggered after call analysis. Format: [{'type': 'schedule_call', 'condition': 'callback_requested == true', 'config': {'delay_minutes': 60}}, {'type': 'webhook', 'condition': 'sale_completed == true', 'config': {'url': 'https://...'}}, {'type': 'schedule_call', 'condition': 'appointment_time != null', 'config': {'use_field': 'appointment_time'}}] Types: schedule_call, webhook, tag_contact
  - `knowledge_base_ids` string[], nullable: Knowledge base IDs linked to this agent for RAG
  - `kb_chunks_count` integer: Number of chunks to retrieve from knowledge base (1-10)
  - `kb_similarity_threshold` number: Minimum similarity score for KB results (0.0-1.0)
  - `background_sound` 'none' | 'office' | 'keyboard': Background ambient sound during calls
  - `end_call_mode` 'static' | 'dynamic': End call message mode: 'static' for fixed message, 'dynamic' for AI-generated based on conversation
  - `end_call_message` string, nullable: Static goodbye message (used when end_call_mode='static'). If empty, uses default localized message.
  - `end_call_prompt` string, nullable: Prompt for generating dynamic goodbye message (used when end_call_mode='dynamic'). Example: 'Konuşmayı özetle ve nazik bir veda mesajı söyle.'
  - `voicemail_detection_enabled` boolean: Enable voicemail/answering machine detection
  - `voicemail_detection_timeout_ms` integer: Time to wait for human response after greeting (ms). If no speech detected, assume voicemail.
  - `voicemail_action` 'hangup' | 'leave_message': Action when voicemail detected: 'hangup' = end call, 'leave_message' = play message and hang up
  - `voicemail_message` string, nullable: Message to leave on voicemail (used when voicemail_action='leave_message')
  - `metadata` object, nullable: Custom metadata for the agent

## Response `201`

Agent created.

- Agent: Complete agent record with metadata.
  - `agent_name` string, required: Human-readable name for the agent
  - `voice_id` string, required: Voice identifier (e.g., 'openai-nova', 'azure-tr-emel')
  - `response_engine` union, required: LLM configuration (built-in or custom)
    - BuiltinLLMEngine: Built-in LLM configuration using platform's LLM service.
      - `type` 'call2me-llm'
      - `system_prompt` string, required: System prompt that defines agent behavior
      - `llm_provider` 'openai' | 'gemini' | 'anthropic' | 'openrouter': LLM provider to use
      - `llm_model` string: Model identifier
      - `temperature` number: Sampling temperature
      - `engine` 'cascade' | 'realtime': Voice engine: cascade (STT→LLM→TTS) or realtime (GPT Realtime speech-to-speech).
      - `max_tokens` integer: Maximum tokens in response
      - `builtin_functions` string[], nullable: Enabled built-in functions: end_call, transfer_call, hold_call, dtmf_input
      - `functions` object[], nullable: Function definitions for tool calling
    - CustomLLMEngine: Custom LLM configuration via WebSocket.
      - `type` 'custom-llm'
      - `llm_websocket_url` string, required: WebSocket URL for custom LLM server
  - `language` string: BCP-47 language code
  - `voice_speed` number: Voice playback speed
  - `responsiveness` number: How quickly agent responds (0=slow, 1=immediate)
  - `interruption_sensitivity` number: How easily user can interrupt (0=hard, 1=easy)
  - `enable_backchannel` boolean: Enable 'uh-huh', 'hmm' responses
  - `backchannel_frequency` number: How often to backchannel (0=never, 1=always)
  - `backchannel_words` string[]: Custom backchannel words (empty = use defaults for language)
  - `begin_message` string, nullable: First message when call starts (used when begin_message_mode='static')
  - `begin_message_mode` string: 'static': use begin_message as-is, 'dynamic': LLM generates greeting based on system prompt and call context
  - `reminder_message_frequency_ms` integer: Send reminder after this much silence (ms)
  - `reminder_max_count` integer: Max reminder messages before ending call (0=disabled)
  - `end_call_after_silence_ms` integer: End call after this much silence (ms)
  - `max_call_duration_ms` integer: Maximum call duration (ms)
  - `enable_recording` boolean: Enable call recording
  - `enable_vcon_export` boolean: Allow exporting this agent's calls as vCon containers
  - `webhook_url` string, nullable: URL for webhook events
  - `transfer_targets` object[], nullable: Transfer targets: [{'name': 'Support', 'type': 'phone|sip|agent|external|queue', 'value': '...'}]
  - `post_call_extraction` object[], nullable: Fields to extract from call (e.g., [{'name': 'customer_name', 'type': 'string', 'description': 'Customer name'}])
  - `post_call_extraction_model` string, nullable: LLM model for post-call extraction
  - `post_call_actions` object[], nullable: Actions triggered after call analysis. Format: [{'type': 'schedule_call', 'condition': 'callback_requested == true', 'config': {'delay_minutes': 60}}, {'type': 'webhook', 'condition': 'sale_completed == true', 'config': {'url': 'https://...'}}, {'type': 'schedule_call', 'condition': 'appointment_time != null', 'config': {'use_field': 'appointment_time'}}] Types: schedule_call, webhook, tag_contact
  - `knowledge_base_ids` string[], nullable: Knowledge base IDs linked to this agent for RAG
  - `kb_chunks_count` integer: Number of chunks to retrieve from knowledge base (1-10)
  - `kb_similarity_threshold` number: Minimum similarity score for KB results (0.0-1.0)
  - `background_sound` 'none' | 'office' | 'keyboard': Background ambient sound during calls
  - `end_call_mode` 'static' | 'dynamic': End call message mode: 'static' for fixed message, 'dynamic' for AI-generated based on conversation
  - `end_call_message` string, nullable: Static goodbye message (used when end_call_mode='static'). If empty, uses default localized message.
  - `end_call_prompt` string, nullable: Prompt for generating dynamic goodbye message (used when end_call_mode='dynamic'). Example: 'Konuşmayı özetle ve nazik bir veda mesajı söyle.'
  - `voicemail_detection_enabled` boolean: Enable voicemail/answering machine detection
  - `voicemail_detection_timeout_ms` integer: Time to wait for human response after greeting (ms). If no speech detected, assume voicemail.
  - `voicemail_action` 'hangup' | 'leave_message': Action when voicemail detected: 'hangup' = end call, 'leave_message' = play message and hang up
  - `voicemail_message` string, nullable: Message to leave on voicemail (used when voicemail_action='leave_message')
  - `metadata` object, nullable: Custom metadata for the agent
  - `agent_id` string, required: Unique agent identifier
  - `user_id` string, nullable: Owner user ID
  - `status` string: Agent status: active or inactive
  - `created_at` string, date-time, required: Creation timestamp
  - `updated_at` string, date-time, required: Last update timestamp
  - `public_metadata` object, nullable: Public-facing card metadata (emoji, title, order, visible) for end-user agent pickers.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/call2me/apis/call2me-api.md) · [All operations](https://skmtc.dev/call2me/apis/call2me-api/llms.txt) · [OpenAPI document](https://skmtc.dev/call2me/apis/call2me-api/revisions/3951f9b7e47d?raw)