Skip to main content
POST
/
agent
Create an agent
curl --request POST \
  --url https://api.vocobase.com/api/v2/agent \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent_name": "Sales Assistant",
  "prompt": "<string>",
  "voice_id": "b49e0d0f-2219-4425-a765-1efd32beb509",
  "intro_message": "<string>",
  "voicemail_detection_enabled": true,
  "voicemail_message": "<string>",
  "project_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "enable_recording": false,
  "kb_threshold": "medium",
  "kb_include_summaries": false,
  "kb_result_format": "<string>",
  "kb_enable_llm_processing": false,
  "kb_llm_system_prompt": "<string>",
  "end_call_enabled": true,
  "end_call_message": "<string>",
  "end_call_instructions": "<string>",
  "transfer_enabled": false,
  "transfer_number": "<string>",
  "transfer_message": "<string>",
  "transfer_instructions": "<string>",
  "max_call_duration_secs": 600,
  "background_audio_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "background_audio_volume": 0.5
}
'
{
  "success": true,
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "agent_name": "<string>",
    "prompt": "<string>",
    "voice_id": "<string>",
    "language": "<string>",
    "intro_message": "<string>",
    "voicemail_detection_enabled": true,
    "voicemail_message": "<string>",
    "enable_recording": true,
    "kb_include_summaries": true,
    "kb_result_format": "<string>",
    "kb_enable_llm_processing": true,
    "kb_llm_system_prompt": "<string>",
    "variables": [
      "<string>"
    ],
    "extraction_config": {
      "prompt": "<string>",
      "keys": [
        {
          "name": "<string>",
          "description": "<string>"
        }
      ],
      "includeToolLogs": false
    },
    "project_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "transferEnabled": true,
    "transferNumber": "<string>",
    "transferMessage": "<string>",
    "transfer_instructions": "<string>",
    "endCallEnabled": true,
    "endCallMessage": "<string>",
    "end_call_instructions": "<string>",
    "max_call_duration_secs": 600,
    "background_audio_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "background_audio_volume": 0.5,
    "document_count": 123,
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z"
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.vocobase.com/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

API key in format: rg_live_xxxx. Pass as a Bearer token in the Authorization header.

Body

application/json
​
agent_name
string
required

Unique agent name.

Maximum string length: 50
Example:

"Sales Assistant"

​
prompt
string
required

System prompt defining the agent's personality and behavior.

Maximum string length: 120000
​
voice_id
string<uuid>
required

Voice ID from the catalog returned by GET /agent/voices. The language and gender are taken from the selected voice.

Example:

"b49e0d0f-2219-4425-a765-1efd32beb509"

​
agent_type
enum<string>
required

Whether the agent handles inbound or outbound calls.

Available options:
inbound,
outbound
​
intro_message
string | null

Optional greeting spoken when a call connects.

Maximum string length: 500
​
voicemail_detection_enabled
boolean
default:true

Per-agent toggle for carrier-side voicemail detection on supported outbound providers. Account-level provider support must also be enabled.

​
voicemail_message
string | null

Optional message used after a supported carrier detects voicemail. Pass null or an empty string to clear.

Maximum string length: 500
​
project_id
string<uuid> | null

Assign the agent to a specific project. Defaults to the default project if omitted.

​
enable_recording
boolean
default:false

Whether to record calls made with this agent.

​
kb_threshold
enum<string> | null
default:medium

Knowledge base search relevance threshold.

Available options:
low,
medium,
high,
null
​
kb_include_summaries
boolean
default:false

Include document summaries in KB search results.

​
kb_result_format
string | null

Custom format template for KB search results.

Maximum string length: 2000
​
kb_enable_llm_processing
boolean
default:false

Enable LLM post-processing of KB search results.

​
kb_llm_system_prompt
string | null

System prompt for LLM KB processing.

Maximum string length: 120000
​
end_call_enabled
boolean
default:true

Master toggle for the end-call tool. When false, the agent cannot end calls on its own regardless of end_call_instructions.

​
end_call_message
string | null

Farewell line spoken before the bot hangs up. When null/empty, a platform default is used.

Maximum string length: 500
​
end_call_instructions
string | null

Free-text natural-language instructions spliced into the system prompt under "When to end the call." Write your own conditions in plain English, e.g. "End the call when the caller says goodbye, has not spoken for an extended period, or asks to be removed from the list." When null/empty, the section is skipped entirely. Replaces the prior end_call_triggers enum array.

Maximum string length: 2000
​
transfer_enabled
boolean
default:false

Master toggle for cold-transfer-to-human. transfer_number is required when true. When the agent transfers a call, Vocobase connects the caller to transfer_number. The session.completed webhook includes transfer metadata — see data.call.transferred.

​
transfer_number
string | null

E.164 number to transfer the call to. Required when transfer_enabled is true.

​
transfer_message
string | null

Announcement spoken before the transfer. When null/empty, a platform default is used.

Maximum string length: 500
​
transfer_instructions
string | null

Free-text natural-language instructions spliced into the system prompt under "When to transfer." Write your own conditions in plain English. When null/empty, the section is skipped. Replaces the prior transfer_triggers enum array.

Maximum string length: 2000
​
max_call_duration_secs
integer | null
default:600

Hard cap on call duration in seconds. New agents default to 600 (10 minutes); pass null to disable the cap. Range 60-3600. At (cap - 30s) the bot speaks a soft "wrapping up" warning; at the cap it speaks the agent's farewell and gracefully ends the session through the standard end-of-call path.

Required range: 60 <= x <= 3600
​
background_audio_id
string<uuid> | null

Reference to a BackgroundAudio asset (see GET /agent/background-audio) the bot will mix under its TTS for the duration of the call.

​
background_audio_volume
number | null

Mixing volume for background_audio_id. Range 0.0-1.0. When null, the bot applies a default of 0.3.

Required range: 0 <= x <= 1

Response

Agent created successfully.

​
success
boolean
​
data
object