Skip to main content

​
What is an agent?

An agent is a complete voice persona. When you create one with just a name, it is immediately usable — OneInbox automatically sets up a default LLM, a default voice, and a default system prompt. You only need to change these if you want to customise them.
ComponentDefaultChange it when…
LLM (AI brain)Auto-created with a general system promptYou want a specific persona, script, or temperature
VoiceDefault voice pre-configuredYou want a specific voice from ElevenLabs or Cartesia
System promptGeneral-purpose assistantYou want the agent to follow specific instructions or scripts
LanguageenYou need the agent to transcribe a different language
ToolsNoneYou want the agent to take actions (SMS, transfer, capture data)
A single agent handles web calls (browser), outbound phone calls, and inbound calls — you don’t need a separate agent per call type.

​
Create an agent

You have two options — create with defaults and customise later, or provide your own config upfront. Both produce a fully working agent.

​
Option A — Create with defaults

Just a name. OneInbox automatically creates a default LLM, voice, and system prompt. Customise later using the llm_id and agent_id from the response. 
curl -X POST https://api.oneinbox.ai/v1/agents \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Support Agent" }'

{
  "id": "agt_abc123",
  "name": "Acme Support Agent",
  "llm_id": "llm_xyz789",
  "created_at": "2026-06-01T10:00:00Z"
}

​
Option B — Create with your own config

Pass any fields you want configured from the start. All fields except name are optional. 
curl -X POST https://api.oneinbox.ai/v1/agents \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Support Agent",
    "language": "en",
    "first_message": "Hi! Thanks for reaching out to Acme. How can I help you today?",
    "tts": {
      "provider": "elevenlabs",
      "voice_id": "<imported_voice_id>"
    },
    "silence_timeout_seconds": 10,
    "max_duration_seconds": 600,
    "interruption_sensitivity": 0.6,
    "enable_recording": true,
    "voicemail_detection": true,
    "voicemail_message": "Hi, please leave a message and we'll call you back."
  }'
The llm_id in the response is the auto-created AI model. Use it to set the system prompt, attach tools, or link knowledge bases — regardless of which option you used. Your agent is ready immediately. Test it with a web call — no phone number needed: 
curl -X POST https://api.oneinbox.ai/v1/calls/web \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "agt_abc123" }'

​
Customise the defaults

Out of the box the agent works with a general-purpose system prompt, a default voice, and a default LLM. To give your agent a specific personality or script, update the LLM model using the llm_id from the create response: 
curl -X PATCH https://api.oneinbox.ai/v1/models/<llm_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "system_prompt": "You are a helpful sales rep for Acme Corp. Your goal is to qualify leads and book product demos. Keep all replies under two sentences. Be warm and direct.",
    "temperature": 0.7
  }'
Changes apply to new calls immediately. One LLM model can power multiple agents — to share a brain across agents, PATCH the agent with { "llm_id": "llm_xyz789" }. Update the model once and all agents using it pick up the change.

​
Give your agent tools

Tools (send SMS, capture caller data, transfer calls, book meetings, etc.) are attached to the LLM model, not the agent directly. Why: the LLM model is what decides what to do during a conversation. Tools are the actions it can take — so they live there. Any agent using that model inherits all its tools automatically. To add a tool, first create it, then attach it to the llm_id from your agent: 
# 1. Create a tool (example: capture caller info)
curl -X POST https://api.oneinbox.ai/v1/tools \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "capture_lead_info",
    "type": "extract_information",
    "description": "Extract the caller name, budget, and timeline from the conversation.",
    "extraction_schema": {
      "fields": [
        { "name": "caller_name", "type": "string", "description": "Full name of the caller" },
        { "name": "budget", "type": "string", "description": "Budget the caller mentioned" },
        { "name": "timeline", "type": "string", "description": "Their decision timeline" }
      ]
    }
  }'
# Save the returned tool "id"

# 2. Attach it to the agent's LLM model
curl -X PATCH https://api.oneinbox.ai/v1/models/<llm_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "tool_ids": ["<tool_id>"] }'
→ Tools guide — all 7 tool types with full examples

​
Key agent fields

FieldDefaultWhat it controls
first_message—First thing the agent says when a call connects. Keep it under 2 sentences
languageenTranscription language. Set at the agent level — { "language": "ar" }
silence_timeout_seconds10Seconds of silence before the call ends
max_duration_seconds600Hard cap on call length
interruption_sensitivity0.6How easily the caller can interrupt (0.0 = hard, 1.0 = very easy)
enable_recordingfalseSet true to get recording_url in the call record after the call ends
voicemail_detectionfalseDetect voicemail greetings on outbound calls
voicemail_message—What the agent says if voicemail is detected

​
Updating an agent

Update any field on an agent at any time. Changes take effect on the next call — active calls in progress are not affected. 
curl -X PATCH https://api.oneinbox.ai/v1/agents/<agent_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "first_message": "Hi! How can I help you today?",
    "silence_timeout_seconds": 15
  }'

​
Manage agents

​
List all agents

Retrieve all agents in your account. Use this to find an agent_id or llm_id you need for other operations. 
curl https://api.oneinbox.ai/v1/agents \
  -H "Authorization: Bearer <api_key>"

​
Get a specific agent

Fetch a single agent’s full config — including llm_id, language, voice settings, and all behaviour fields. 
curl https://api.oneinbox.ai/v1/agents/<agent_id> \
  -H "Authorization: Bearer <api_key>"

​
Delete an agent

Permanently removes the agent. If the agent is assigned to a phone number, reassign the number to a different agent first, then delete. 
# 1. Reassign the phone number first (if applicable)
curl -X PATCH https://api.oneinbox.ai/v1/phone-numbers/<phone_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "<different_agent_id>" }'

# 2. Then delete the agent
curl -X DELETE https://api.oneinbox.ai/v1/agents/<agent_id> \
  -H "Authorization: Bearer <api_key>"

​
Next steps

Tools

Give your agent actions — SMS, email, data capture, transfer

Phone calls

Make real outbound calls with a registered phone number

Call outcomes

How calls are classified and how to read results

Voices

Browse available voices and configure TTS