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

A web call is a call session you create with the OneInbox API. It powers browser-based voice on your backend. OneInbox returns call_id, server_url, and participant_token when you create a web call. Prerequisites: a working agent_id from Quickstart.

​
What you get back

FieldPurpose
call_idIdentify the session — poll with GET /v1/calls/<call_id>
server_urlWebSocket URL (e.g. wss://voice.oneinbox.ai) — pass to your frontend
participant_tokenShort-lived client token — pass to your frontend, not your API key
1

1. Create 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>",
    "variables": { "customer_name": "Guest" }
  }'

{
  "id": "call_abc123",
  "server_url": "wss://voice.oneinbox.ai",
  "participant_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
2

2. Pass per-call context (optional)

Use variables to inject context into the agent prompt:
{
  "agent_id": "<agent_id>",
  "variables": {
    "customer_name": "Sam",
    "order_id": "ORD-001"
  }
}
Reference in your system prompt: The customer name is {{customer_name}}.
3

3. Override voice or model per call (optional)

Change TTS or LLM for a single call without updating the agent:
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>",
    "overrides": {
      "tts": {
        "provider": "cartesia",
        "voice_id": "a0e99841-438c-4a64-b679-ae501e7d6091"
      },
      "first_message": "Hi! How can I help you today?"
    }
  }'
See Start web call and Voices for all override fields.
4

4. Verify the call

curl https://api.oneinbox.ai/v1/calls/<call_id> \
  -H "Authorization: Bearer <api_key>"
Look for "status": "completed" and a transcript array when the conversation ends.

​
Security

Return only server_url and participant_token to your frontend — never your API key.

​
Web call vs phone call

Web callPhone call
ChannelBrowser / web appPSTN via telephony carrier
Phone numberNot requiredRequired
Telephony integrationNot requiredRequired
GuideThis pagePhone calls

​
Troubleshooting

ProblemFix
401Check Authorization: Bearer <api_key>
404 on agent_idRe-copy agent_id from Quickstart step 2
Tokens not working in browserCreate a fresh web call — tokens are short-lived

​
Next steps