Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.oneinbox.ai/llms.txt

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

​
Overview

In about 15 minutes you will create a working voice agent and start a web call. You do not need a phone number, telephony carrier, or third-party API keys. You will:
  1. Create an LLM model
  2. Create an agent
  3. Create a web call with POST /v1/calls/web
Time: ~15 minutes Every API request uses: 
Authorization: Bearer <api_key>

​
Prerequisites

ItemWhere
OneInbox API keyDashboard → API Keys → Create API key
Terminalcurl (Mac Terminal, Windows PowerShell, or WSL)
Copy your API key and use Authorization: Bearer <api_key> in every curl below. More detail → Authentication How to run each step: open Terminal (Mac), PowerShell, or WSL. Copy the curl command, replace every placeholder (e.g. <api_key> → your real key), paste into the terminal, and press Enter. If the response is JSON with an "id" field, the step worked. You do not need a phone number or vendor integrations. Integrations are optional when you want your own provider billing (BYOK) or a telephony carrier.

​
1) Create an LLM

Define how your agent thinks — default LLM and system prompt. The agent in step 2 references this model via llm_id. You can reuse one LLM across many agents.
FieldMeaningThis guide
nameLabel in your dashboard"My First Model"
providerLLM settingsDefault LLM
modelLLM settingsDefault LLM
system_promptInstructions the agent followsPersonality and rules
temperatureCreativity (0 = strict, 1 = creative)0.7
tool_idsAttached tools[] for now
knowledge_base_idsAttached knowledge bases[] for now
curl -X POST https://api.oneinbox.ai/v1/models \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My First Model",
    "provider": "openai",
    "model": "gpt-4.1-mini",
    "system_prompt": "You are a friendly assistant. Keep every response under two sentences. Be warm and direct.",
    "temperature": 0.7,
    "max_tokens": 4000,
    "tool_ids": [],
    "knowledge_base_ids": []
  }'

{
  "id": "model_abc123",
  "name": "My First Model",
  "system_prompt": "You are a friendly assistant...",
  "temperature": 0.7,
  "created_at": "2026-01-15T10:02:00Z"
}
ErrorMeaningFix
401Bad API keyCopy the full key from the dashboard
400Invalid model configMatch the JSON above
Copy the "id" value from the response (e.g. model_abc123). You will paste it as <llm_id> in step 2.

​
2) Create an agent

Assemble the full voice agent — STT, LLM, TTS, and call behavior. Link the LLM from step 1 with llm_id. Replace <llm_id> in the curl below with the "id" you copied from step 1.
PartFieldThis guide
Brainllm_idFrom step 1
Ears (STT)transcriberDefault STT
Voice (TTS)ttsDefault voice
Behaviorfirst_message, timeoutsGreeting and hang-up rules
FieldWhat it does
first_messageFirst thing said when the call connects
end_call_phrasesUser says these → call ends
silence_timeout_secondsHang up after N seconds of silence
max_duration_secondsHard cap on call length
interruption_sensitivityHow easily the user can interrupt (0.0–1.0)
enable_recordingRecord the call when true
curl -X POST https://api.oneinbox.ai/v1/agents \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent",
    "llm_id": "<llm_id>",
    "transcriber": {
      "provider": "deepgram",
      "model": "nova-3",
      "language": "en"
    },
    "tts": {
      "provider": "deepgram",
      "voice_id": "asteria",
      "speed": 1.0,
      "stability": 0.5
    },
    "first_message": "Hi! How can I help you today?",
    "end_call_phrases": ["goodbye", "bye", "that is all"],
    "silence_timeout_seconds": 10,
    "max_duration_seconds": 600,
    "interruption_sensitivity": 0.6,
    "enable_recording": false
  }'

{
  "id": "agent_abc123",
  "name": "Support Agent",
  "llm_id": "model_abc123",
  "first_message": "Hi! How can I help you today?",
  "created_at": "2026-01-15T10:03:00Z"
}
ErrorMeaningFix
404 on llm_idWrong LLM IDRe-copy from step 1
400Invalid transcriber/ttsUse the JSON above
Copy the "id" value from the response (e.g. agent_abc123). You will paste it as <agent_id> in step 3.

​
3) Create a web call

Create a web call — a voice session on OneInbox’s servers. This step uses the API only (POST /v1/calls/web). It returns a call_id you can poll for status and transcript. Replace <agent_id> with the "id" you copied from step 2. 
curl -X POST https://api.oneinbox.ai/v1/calls/web \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "<agent_id>",
    "variables": { "customer_name": "Guest" }
  }'

{
  "id": "call_abc123",
  "server_url": "wss://voice.oneinbox.ai",
  "participant_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
FieldMeaning
idCall ID — poll with GET /v1/calls/<call_id>
server_urlWebSocket URL (for browser voice via Web SDK)
participant_tokenClient token for Web SDK — not your API key
ErrorMeaningFix
404 on agent_idWrong agent IDRe-copy from step 2
Are you done? If the response includes "id", "server_url", and "participant_token", the web call session was created successfully. This step does not open your microphone yet — it only creates the session on OneInbox. To hear and speak with your agent in a browser, continue to the Web SDK. To check call status later: 
curl https://api.oneinbox.ai/v1/calls/<call_id> \
  -H "Authorization: Bearer <api_key>"
Wait for "status": "completed" to read the transcript.

​
Next steps

Add a phone number and call real lines — Phone calls.

Phone calls

Add a telephony carrier, register a number, outbound and inbound

Integrations

Store your carrier credentials in OneInbox

Web SDK

Browser voice for web calls

Tools

API actions, transfer, hang up