Create Agent
Create a new voice agent with specified configuration, voice settings, and behavior parameters. The agent will be created in draft status and can be published later.
Endpoint
Path parameters
None
Bearer token for authentication. Format: Bearer talq_your_environment_token_here
Must be set to application/json
Request body
Agent label (max 255 characters)
Agent name (max 255 characters)
Agent language code. Supported values: pt-BR, pt-PT, en-US, en-CA, es-ES, fr-FR, de-DE, it-IT, nl-NL, ja-JP, ko-KR, zh-TW.
Initial message the agent will say. Optional.
How easily the agent allows the caller to interrupt. Options: low, medium, high.
How aggressively the agent detects end-of-utterance. Max 255 characters.
IVR navigation behavior for outbound calls that hit interactive menus. Max 255 characters.
Conversation playback speed multiplier. Range: 0.1–3.0.
Delay in seconds before the agent says the initial message. Range: 0–60.
ask_if_human_present_on_idle
When true, the agent asks “Are you still there?” after the idle timeout instead of ending the call.
Seconds of caller silence before triggering the idle behavior. Range: 1–60.
Maximum number of idle re-prompts before ending the call. Range: 1–10. Optional.
max_call_duration_seconds
Hard limit on call duration in seconds. Range: 1–3600. Optional.
say_goodbye_on_max_duration
When true, the agent says a closing message before terminating a call that hits max_call_duration_seconds. Optional.
user_inactivity_timeout_seconds
Seconds of total inactivity before the agent gives up entirely. Range: 5–120. Optional.
initial_idle_time_seconds
Idle threshold to use before the agent has said its initial message (handles cases where the line opens but the caller doesn’t speak). Range: 1–60. Optional.
initial_max_idle_check_count
Maximum number of initial idle prompts before terminating. Range: 0–10. Optional.
Sampling temperature for the language model. Range: 0–2. Lower values make responses more deterministic.
Whether to record calls handled by this agent.
Call direction. Options: inbound, outbound.
Who speaks first. Options: agent, user.
Example requests
# Request 1: Create a basic inbound support agent
curl -X POST "https://app.talkover.ai/api/v1/agents" \
-H "Authorization: Bearer talq_your_environment_token_here" \
-H "Content-Type: application/json" \
-d '{
"label": "Customer Support Agent",
"description": "Handles customer inquiries and support requests",
"name": "SupportBot",
"language": "en-US",
"initial_message": "Hello, how can I help you today?",
"interrupt_sensitivity": "medium",
"endpointing_sensitivity": "auto",
"ivr_navigation_mode": "off",
"conversation_speed": 1.0,
"initial_message_delay": 0,
"ask_if_human_present_on_idle": false,
"idle_time_seconds": 5,
"llm_temperature": 0.7,
"enable_recording": true,
"direction": "inbound",
"who_speaks_first": "agent"
}'
# Request 2: Create an outbound sales agent
curl -X POST "https://app.talkover.ai/api/v1/agents" \
-H "Authorization: Bearer talq_your_environment_token_here" \
-H "Content-Type: application/json" \
-d '{
"label": "Sales Agent",
"description": "Outbound sales calls for product demos",
"name": "SalesBot",
"language": "en-US",
"initial_message": "Hi, this is SalesBot calling about our new product. Do you have a moment?",
"interrupt_sensitivity": "high",
"endpointing_sensitivity": "auto",
"ivr_navigation_mode": "off",
"conversation_speed": 1.2,
"initial_message_delay": 2,
"ask_if_human_present_on_idle": true,
"idle_time_seconds": 10,
"llm_temperature": 0.8,
"enable_recording": true,
"direction": "outbound",
"who_speaks_first": "agent"
}'
Response
Success Response (201 Created)
{
"success": true,
"message": "Agent created successfully",
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "SupportBot",
"label": "Customer Support Agent",
"description": "Handles customer inquiries and support requests",
"language": "en-US",
"voice": null,
"initial_message": "Hello, how can I help you today?",
"interrupt_sensitivity": "medium",
"conversation_speed": 1.0,
"initial_message_delay": 0,
"ask_if_human_present_on_idle": false,
"direction": "inbound",
"who_speaks_first": "agent",
"current_status": "draft",
"is_sandbox": false,
"is_ready_to_publish": false,
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z",
"trainings": [],
"actions": [],
"phone_numbers": []
}
}
Error responses
Validation Error (422)
{
"success": false,
"message": "The given data was invalid.",
"errors": {
"name": [
"The name field is required."
],
"label": [
"The label field is required."
],
"language": [
"The selected language is invalid."
],
"interrupt_sensitivity": [
"The selected interrupt sensitivity is invalid."
],
"direction": [
"The selected direction is invalid."
],
"conversation_speed": [
"The conversation speed must be between 0.1 and 3.0."
],
"initial_message_delay": [
"The initial message delay must be between 0 and 60."
],
"llm_temperature": [
"The llm temperature must be between 0 and 2."
],
"idle_time_seconds": [
"The idle time seconds must be between 1 and 300."
]
}
}
Unauthorized Error (401)
{
"success": false,
"message": "Unauthenticated."
}
Too Many Requests (429)
{
"success": false,
"message": "Too many requests. Please try again later."
}
