Skip to main content
POST
/
v1
/
agents
Create agent
curl --request POST \
  --url https://api.vatel.ai/v1/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "phone_number_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "llm": "<string>",
  "fallback_llm": "<string>",
  "status": "active",
  "prompt": "<string>",
  "first_message": "<string>",
  "first_message_interruption_time": 123,
  "default_language": "<string>",
  "summarize_calls": true,
  "noise_cancel_settings": {
    "enabled": true,
    "level": 123
  },
  "vad_settings": {
    "start_secs": 123,
    "stop_secs": 123,
    "silence_timeout_secs": 123
  },
  "enable_first_message_outbound": true,
  "timeout_settings": {
    "default_timeout": 123,
    "timeout_action": "end_call",
    "transfer_number": "<string>",
    "transfer_message": "<string>",
    "silence_counter": 123,
    "silence_timeout_action": "end_call",
    "silence_transfer_number": "<string>"
  },
  "keyterms": [
    "<string>"
  ],
  "voice_settings": {
    "id": "<string>",
    "provider": "elevenlabs",
    "speed": 123,
    "stability": 123,
    "similarity_boost": 123,
    "volume": 123
  }
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "phone_number_id": "<string>",
  "name": "<string>",
  "llm": "<string>",
  "fallback_llm": "<string>",
  "status": "active",
  "prompt": "<string>",
  "first_message": "<string>",
  "first_message_interruption_time": 123,
  "default_language": "<string>",
  "summarize_calls": true,
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "noise_cancel_settings": {
    "enabled": true,
    "level": 123
  },
  "vad_settings": {
    "start_secs": 123,
    "stop_secs": 123,
    "silence_timeout_secs": 123
  },
  "enable_first_message_outbound": true,
  "voice_settings": {
    "id": "<string>",
    "provider": "elevenlabs",
    "speed": 123,
    "stability": 123,
    "similarity_boost": 123,
    "volume": 123
  },
  "timeout_settings": {
    "default_timeout": 123,
    "timeout_action": "end_call",
    "transfer_number": "<string>",
    "transfer_message": "<string>",
    "silence_counter": 123,
    "silence_timeout_action": "end_call",
    "silence_transfer_number": "<string>"
  },
  "keyterms": [
    "<string>"
  ]
}

Authorizations

​
Authorization
string
header
required

Send your organization API key as Authorization: Bearer <key>.

Body

application/json

Fields accepted when creating an agent; server defaults apply to omitted values.

​
name
string
required

Display name (required).

​
phone_number_id
string<uuid> | null

Twilio number id belonging to this org, or null to leave unassigned.

​
llm
string

Language model id in provider/model form. Use GET /v1/llms for values accepted on create and update.

​
fallback_llm
string

Language model id in provider/model form. Use GET /v1/llms for values accepted on create and update.

​
status
enum<string>

Whether the agent accepts traffic.

Available options:
active,
inactive
​
prompt
string
​
first_message
string
​
first_message_interruption_time
number
​
default_language
string

One of: multi, en, es, fr, de, it, pt, ru, zh, ja, ko, ar, hi (see Agent.default_language).

​
summarize_calls
boolean
​
noise_cancel_settings
object

Inbound noise suppression profile.

​
vad_settings
object

Voice-activity detection timing for turn-taking. On PATCH, send only the fields to change; omitted properties keep their stored values.

​
enable_first_message_outbound
boolean
​
timeout_settings
object

Limits and escalation rules for user silence and overall call duration.

​
keyterms
string[]

Optional list; empty omitted uses server default.

​
voice_settings
object

Voice and TTS provider for the agent. On create or update, include id and provider; optional tuning fields (when sent and non-zero) must be between 0 and 2.

Response

Created agent

Voice agent configuration for your organization. llm is the primary model; fallback_llm is used when the primary cannot serve.

​
id
string<uuid>

Stable agent id.

​
phone_number_id
string

Assigned Twilio number id for this agent, if any. Empty when unassigned.

​
name
string

Display name.

​
llm
string

Language model id in provider/model form. Use GET /v1/llms for values accepted on create and update.

​
fallback_llm
string

Language model id in provider/model form. Use GET /v1/llms for values accepted on create and update.

​
status
enum<string>

Whether the agent accepts traffic.

Available options:
active,
inactive
​
prompt
string

System or base instructions for the model.

​
first_message
string

Opening line the agent speaks when a call starts.

​
first_message_interruption_time
number

Window (seconds) where the first message can be interrupted.

​
default_language
string

Primary speech language: multi, en, es, fr, de, it, pt, ru, zh, ja, ko, ar, or hi (same set as the builder UI). multi is only appropriate for multilingual STT (e.g. Deepgram Nova).

​
summarize_calls
boolean

Whether to generate summaries after calls.

​
created_at
string<date-time>
​
updated_at
string<date-time>
​
noise_cancel_settings
object

Inbound noise suppression profile.

​
vad_settings
object

Voice-activity detection timing for turn-taking. On PATCH, send only the fields to change; omitted properties keep their stored values.

​
enable_first_message_outbound
boolean

Play first_message on outbound calls when true.

​
voice_settings
object

Voice and TTS provider for the agent. On create or update, include id and provider; optional tuning fields (when sent and non-zero) must be between 0 and 2.

​
timeout_settings
object

Limits and escalation rules for user silence and overall call duration.

​
keyterms
string[]

Hints for transcription or keyword boosting, up to server limits.