Agents

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.

Component	Default	Change it when…
LLM (AI brain)	Auto-created with a general system prompt	You want a specific persona, script, or temperature
Voice	Default voice pre-configured	You want a specific voice from ElevenLabs or Cartesia
System prompt	General-purpose assistant	You want the agent to follow specific instructions or scripts
Language	`en`	You need the agent to transcribe a different language
Tools	None	You want the agent to take actions (SMS, transfer, capture data)

A single agent handles browser calls (via the Web SDK) and direct phone calls — both outbound and inbound — 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-tokyo.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-tokyo.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 quick browser call — no phone number needed, runs entirely over the internet (same mechanism the Web SDK uses):

curl -X POST https://api-tokyo.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-tokyo.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. To use a self-hosted or third-party LLM, set provider to "custom" and supply custom_websocket_url. The URL can be wss://, ws://, https://, or http:// — the server must expose an OpenAI-compatible streaming chat completions interface.

curl -X POST https://api-tokyo.oneinbox.ai/v1/models \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My self-hosted LLM",
    "provider": "custom",
    "custom_websocket_url": "wss://your-llm-server.example.com/v1/chat/completions",
    "system_prompt": "You are a helpful voice assistant.",
    "temperature": 0.7
  }'

Browse available models

The catalogue lists accepted model IDs for LLM, STT, and TTS providers — useful before setting a custom model on your agent or LLM.

# LLM providers — openai, anthropic, groq, shisa, openrouter
curl "https://api-tokyo.oneinbox.ai/v1/models/catalogue?provider=openai" \
  -H "Authorization: Bearer <api_key>"

# STT providers — deepgram, soniox, shisa, assembly_ai, whisper, azure
curl "https://api-tokyo.oneinbox.ai/v1/models/catalogue?provider=deepgram" \
  -H "Authorization: Bearer <api_key>"

# TTS providers — cartesia, elevenlabs, openai, deepgram, soniox, shisa, minimax
curl "https://api-tokyo.oneinbox.ai/v1/models/catalogue?provider=cartesia" \
  -H "Authorization: Bearer <api_key>"

The source field on each item is live (fetched directly from the provider), seed (a static list shown without a credential), or unverified.

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-tokyo.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-tokyo.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

Speech-to-text (STT)

STT converts the caller’s voice into text that the LLM can understand. Set the transcriber object on the agent to choose the provider and model. All STT providers below are platform-provided — no credential needed.

Provider	Models	Best for
Deepgram	`nova-3` (default), `flux-en`, `flux-multi`	Low latency, high accuracy. `nova-3` recommended for most use cases
Soniox	`stt-rt-v5`, `stt-rt-v4`, `stt-rt-v3`	High-accuracy real-time streaming
Shisa	`shisa-asr-realtime`	Japanese language specialisation
Whisper	`whisper-1`	Broad language coverage
AssemblyAI	`best`, `nano`, `slam-1`	High accuracy for complex audio
Azure	e.g. `en-US-JennyNeural`	Enterprise Azure deployments

curl -X PATCH https://api-tokyo.oneinbox.ai/v1/agents/<agent_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "transcriber": {
      "provider": "deepgram",
      "model": "nova-3",
      "language": "en"
    }
  }'

Set language to match the caller’s language — e.g. "hi" for Hindi, "ja" for Japanese. Use flux-multi for multilingual calls where the language is unknown.

Text-to-speech (TTS)

TTS converts the agent’s text replies into spoken audio. Set the tts object on the agent to choose the provider, voice, and speed. All TTS providers below are platform-provided — no credential needed.

Provider	Notable voices	Best for
Cartesia	Sarah, Liam, Barbershop Man	Ultra-low latency, natural prosody
Deepgram	Thalia, Asteria, Zeus	Fast, conversational
ElevenLabs	Roger, Laura, Alice	High expressiveness, emotional range
OpenAI	Alloy, Echo, Nova, Shimmer	Consistent quality, stable under load
Soniox	—	Low-latency streaming TTS
Minimax	Female Phone, Male Phone	Optimised for phone-quality audio
Shisa	JA Female	Japanese language specialisation

curl -X PATCH https://api-tokyo.oneinbox.ai/v1/agents/<agent_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "tts": {
      "provider": "cartesia",
      "voice_id": "<vc_...>",
      "speed": 1.0,
      "stability": 0.5
    }
  }'

voice_id must be the vc_... ID from the /v1/voices endpoint — not the raw provider voice ID. See Voices for the full list of available voice IDs.

Field	Range	What it does
`voice_id`	—	The OneInbox voice ID (`vc_...`) from `/v1/voices`
`speed`	0.5–2.0	Playback rate. `1.0` is normal speech speed
`stability`	0.0–1.0	Voice consistency. Higher = more consistent tone, lower = more expressive

Key agent fields

Field	Default	What it controls
`first_message`	—	First thing the agent says when a call connects. Keep it under 2 sentences
`language`	`en`	Transcription language. Set at the agent level — `{ "language": "ar" }`
`silence_timeout_seconds`	`10`	Seconds of silence before the call ends
`max_duration_seconds`	`600`	Hard cap on call length. Range: 30–7200
`interruption_sensitivity`	`0.5`	How easily the caller can interrupt (0.0 = hard, 1.0 = very easy)
`responsiveness`	`0.5`	How quickly the agent responds after the caller stops speaking (0 = patient, 1 = snappy)
`enable_recording`	`false`	Set `true` to get `recording_url` in the call record after the call ends
`voicemail_detection`	`false`	Detect voicemail greetings on outbound calls
`voicemail_message`	—	What the agent says if voicemail is detected
`end_call_phrases`	`[]`	Phrases that trigger call end automatically — e.g. `["goodbye", "talk later"]`
`job_description`	—	Prepended to the system prompt as a `# Role` block at call time. Use this to set the agent’s role without editing the full system prompt on the LLM
`speed`	`1.0`	Top-level speech rate multiplier (0.5–2.0). Overrides `tts.speed` when set
`background_sound`	—	Ambient audio behind the agent’s voice — e.g. `"office"`, `"cafe"`
`emotions`	`false`	Enable emotion-aware voice expression (provider-dependent)

Dynamic variables

Dynamic variables let you personalise an agent’s first_message, voicemail_message, and system_prompt per call — without creating a separate agent per lead. Write placeholders with single braces ({variable_name}) in any of those fields, then pass the actual values when you start the call.

# 1. Agent with placeholders
curl -X POST https://api-tokyo.oneinbox.ai/v1/agents \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Bot",
    "first_message": "Hi {lead_name}, this is Aria calling about {product_name}.",
    "dynamic_variables": {
      "product_name": "Acme Outreach"
    }
  }'

# 2. Call with per-call values
curl -X POST https://api-tokyo.oneinbox.ai/v1/calls \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "<agent_id>",
    "to_number": "+919876543210",
    "from_number": "+15739693824",
    "variables": {
      "lead_name": "Priya"
    }
  }'

The agent opens with: “Hi Priya, this is Aria calling about Acme Outreach.” Two layers — how they combine:

Layer	Where set	Priority
`dynamic_variables` on the agent	Agent config — same for every call	Lower (default fallback)
`variables` on the call	Call request — per-call	Higher (overrides agent defaults)

At call start, OneInbox builds the final variable map by merging both layers (call values win on collision), then substitutes every {placeholder} in the templates before the agent says a word. The LLM and TTS only ever see the resolved strings — never the raw placeholders.

Use single braces — {lead_name}, not {{lead_name}}. Double braces are not interpolated and appear as literal text.

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-tokyo.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-tokyo.oneinbox.ai/v1/agents?limit=20" \
  -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-tokyo.oneinbox.ai/v1/agents/<agent_id> \
  -H "Authorization: Bearer <api_key>"

The single-agent GET includes a read-only effective_system_prompt field — the exact system prompt the agent is given at call time: the LLM’s system_prompt with job_description prepended as a # Role block. This is what the LLM actually receives, assembled the same way the worker does at runtime.

{
  "id": "agt_abc123",
  "llm_id": "llm_xyz789",
  "job_description": "You are a friendly sales rep at Acme.",
  "effective_system_prompt": "# Role\nYou are a friendly sales rep at Acme.\n\nYou are a helpful voice assistant.",
  "..."
}

effective_system_prompt is only populated on GET /v1/agents/{id}. It is null on the list endpoint to avoid an LLM lookup per row. Per-call variable interpolation and knowledge base chunks are resolved at runtime and are not reflected here.

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-tokyo.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-tokyo.oneinbox.ai/v1/agents/<agent_id> \
  -H "Authorization: Bearer <api_key>"

List LLM models

curl "https://api-tokyo.oneinbox.ai/v1/models?limit=20" \
  -H "Authorization: Bearer <api_key>"

Get an LLM model

Fetch the full config of a specific model — system prompt, tools, knowledge bases, and custom URL.

curl https://api-tokyo.oneinbox.ai/v1/models/<model_id> \
  -H "Authorization: Bearer <api_key>"

Delete an LLM model

Permanently removes the model. Agents currently using this model will lose their LLM config — reassign them first with { "llm_id": "<replacement_model_id>" }.

curl -X DELETE https://api-tokyo.oneinbox.ai/v1/models/<model_id> \
  -H "Authorization: Bearer <api_key>"

Next steps

Tools

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

Phone numbers

Make real outbound calls with a registered phone number

Calls

How calls are classified and how to read results

Voices

Browse available voices and configure TTS

Get started

Make calls

Configure your agent

Monitor & integrate

Core concepts

What is an agent?

Create an agent

Option A — Create with defaults

Option B — Create with your own config

Customise the defaults

Browse available models

Give your agent tools

Speech-to-text (STT)

Text-to-speech (TTS)

Key agent fields

Dynamic variables

Updating an agent

Manage agents

List all agents

Get a specific agent

Delete an agent

List LLM models

Get an LLM model

Delete an LLM model

Next steps

Tools

Phone numbers

Calls

Voices

​What is an agent?

​Create an agent

​Option A — Create with defaults

​Option B — Create with your own config

​Customise the defaults

​Browse available models

​Give your agent tools

​Speech-to-text (STT)

​Text-to-speech (TTS)

​Key agent fields

​Dynamic variables

​Updating an agent

​Manage agents

​List all agents

​Get a specific agent

​Delete an agent

​List LLM models

​Get an LLM model

​Delete an LLM model

​Next steps

Tools

Phone numbers

Calls

Voices

What is an agent?

Create an agent

Option A — Create with defaults

Option B — Create with your own config

Customise the defaults

Browse available models

Give your agent tools

Speech-to-text (STT)

Text-to-speech (TTS)

Key agent fields

Dynamic variables

Updating an agent

Manage agents

List all agents

Get a specific agent

Delete an agent

List LLM models

Get an LLM model

Delete an LLM model

Next steps