Skip to main content

​
Overview

In about 5 minutes you will have a working voice agent and an active call session. Customise the personality, voice, and language after — no rebuilding needed. You will:
  1. Create an agent (defaults handle everything else)
  2. Start a web call with POST /v1/calls/web
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)

​
Step 1 — Create an agent

One API call. Give it a name — OneInbox automatically configures a default LLM, a default voice, and a default system prompt. The agent is ready to take calls immediately. You can also pass your own config (voice, language, first message, etc.) directly in this call — all fields except name are optional. See the Agents guide for the full config options. 
curl -X POST https://api.oneinbox.ai/v1/agents \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "My First Agent" }'

{
  "id": "agt_abc123",
  "name": "My First Agent",
  "llm_id": "llm_xyz789",
  "first_message": null,
  "created_at": "2026-06-01T10:00:00Z"
}
Save both IDs from the response:
  • id — the agent (voice, language, call behavior)
  • llm_id — the AI brain (what it knows and can do). They’re separate so multiple agents can share one brain.

​
Step 2 — Start a web call

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

{
  "id": "call_abc123",
  "server_url": "wss://voice.oneinbox.ai",
  "participant_token": "eyJhbGci..."
}
Your frontend uses server_url and participant_token to connect to the live session — never your API key. The token is short-lived and scoped to this call session.

​
Step 3 — Customise your agent

Your agent works immediately with defaults. When you’re ready to give it a personality, update the LLM model it was created with: 
# Set a system prompt and greeting
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 support agent for Acme Corp. Keep replies under two sentences.",
    "temperature": 0.7
  }'

# Set a first message and configure call behaviour
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! Thanks for reaching out to Acme. How can I help?",
    "silence_timeout_seconds": 10,
    "enable_recording": true
  }'
Changes apply immediately — no need to recreate anything.

​
Reading call results

After the call ends, stop it and fetch the record: 
# 1. Stop the call
curl -X POST https://api.oneinbox.ai/v1/calls/<call_id>/stop \
  -H "Authorization: Bearer <api_key>"

# 2. Wait 2–3 seconds, then fetch
curl https://api.oneinbox.ai/v1/calls/<call_id> \
  -H "Authorization: Bearer <api_key>"

{
  "id": "call_abc123",
  "status": "completed",
  "duration_seconds": 45,
  "messages": [
    { "role": "agent", "content": "Hi! How can I help?" },
    { "role": "user", "content": "I have a question about my order" }
  ],
  "analysis": {
    "outcome": "Interested",
    "summary": "Caller asked about order status. Agent provided tracking info."
  }
}
messages and analysis are only available after the call ends — both are empty while the call is active.

​
Next steps

Agents

Voice, language, recording, and behaviour settings

Tools

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

Phone calls

Make real outbound calls with your telephony provider

Web SDK

Embed voice in your browser app