# 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 1: Create a basic inbound support agent
const response = await fetch('https://app.talkover.ai/api/v1/agents', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer talq_your_environment_token_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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"
  })
});

const result = await response.json();
console.log(result);

{
  "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": []
  }
}

POST

api

agents

# 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 1: Create a basic inbound support agent
const response = await fetch('https://app.talkover.ai/api/v1/agents', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer talq_your_environment_token_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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"
  })
});

const result = await response.json();
console.log(result);

{
  "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": []
  }
}

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

POST /api/v1/agents

Path parameters

None

Request headers

string

required

Bearer token for authentication. Format: Bearer talq_your_environment_token_here

string

required

Must be set to application/json

Request body

string

required

Agent label (max 255 characters)

string

Agent description

string

required

Agent name (max 255 characters)

string

required

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.

string

Initial message the agent will say. Optional.

string

required

How easily the agent allows the caller to interrupt. Options: low, medium, high.

string

required

How aggressively the agent detects end-of-utterance. Max 255 characters.

IVR navigation behavior for outbound calls that hit interactive menus. Max 255 characters.

number

required

Conversation playback speed multiplier. Range: 0.1–3.0.

integer

required

Delay in seconds before the agent says the initial message. Range: 0–60.

boolean

required

When true, the agent asks “Are you still there?” after the idle timeout instead of ending the call.

integer

required

Seconds of caller silence before triggering the idle behavior. Range: 1–60.

integer

Maximum number of idle re-prompts before ending the call. Range: 1–10. Optional.

integer

Hard limit on call duration in seconds. Range: 1–3600. Optional.

boolean

When true, the agent says a closing message before terminating a call that hits max_call_duration_seconds. Optional.

integer

Seconds of total inactivity before the agent gives up entirely. Range: 5–120. Optional.

integer

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.

integer

Maximum number of initial idle prompts before terminating. Range: 0–10. Optional.

number

required

Sampling temperature for the language model. Range: 0–2. Lower values make responses more deterministic.

boolean

required

Whether to record calls handled by this agent.

string

required

Call direction. Options: inbound, outbound.

string

required

Who speaks first. Options: agent, user.

array

Array of phone number UUIDs to assign to this agent at creation. Use List Phone Numbers to retrieve available IDs. Can also be set later via Update Agent Calling.

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 1: Create a basic inbound support agent
const response = await fetch('https://app.talkover.ai/api/v1/agents', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer talq_your_environment_token_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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"
  })
});

const result = await response.json();
console.log(result);

# 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"
  }'

// Request 2: Create an outbound sales agent
const response = await fetch('https://app.talkover.ai/api/v1/agents', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer talq_your_environment_token_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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"
  })
});

const result = await response.json();
console.log(result);

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."
}

Get Started

Concepts

API Reference

Guides

Create Agent

Create Agent

Endpoint

Path parameters

Request headers

Request body

Example requests

Response

Success Response (201 Created)

Error responses

Validation Error (422)

Unauthorized Error (401)

Too Many Requests (429)

​Create Agent

​Endpoint

​Path parameters

​Request headers

​Request body

​Example requests

​Response

​Success Response (201 Created)

​Error responses

​Validation Error (422)

​Unauthorized Error (401)

​Too Many Requests (429)

Create Agent

Endpoint

Path parameters

Request headers

Request body

Example requests

Response

Success Response (201 Created)

Error responses

Validation Error (422)

Unauthorized Error (401)

Too Many Requests (429)