Skip to main content

​
What is a web call?

A web call is a voice session that runs entirely over the internet. Your backend creates the session via API and gets back a server_url and participant_token — your frontend uses these to connect to the live session. Use web calls for:
  • Testing your agent during development
  • Embedded voice widgets in a web app
  • Demo environments where you don’t need a real phone number

​
Create a web call

Your backend calls this endpoint and receives connection tokens. Pass these to your frontend — never your API key. 
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": "Sama" }
  }'

{
  "id": "call_abc123",
  "server_url": "wss://voice.oneinbox.ai",
  "participant_token": "eyJhbGci..."
}
FieldWhat it isWhat to do with it
idUnique call IDPoll with GET /v1/calls/<id> to check status and read transcript after the call
server_urlWebSocket server address (wss://voice.oneinbox.ai)Your frontend connects here to join the audio session
participant_tokenShort-lived client tokenPass to your browser SDK — never expose your API key to the frontend

​
Passing context with variables

Use variables to inject per-call context into the agent’s system prompt and first message. Reference them with {{variable_name}} in your system prompt or first_message. System prompt example: 
You are speaking with {{customer_name}}. Their order ID is {{order_id}}.
Start by confirming their order status.
Web call request: 
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": "Sama",
      "order_id": "ORD-001"
    }
  }'
The agent greets Sama personally and knows their order ID — no agent reconfiguration needed between calls.

​
Monitoring a call

Poll the call status while it’s active: 
curl https://api.oneinbox.ai/v1/calls/<call_id> \
  -H "Authorization: Bearer <api_key>"
statusMeaning
initiatedSession created, agent not yet connected
in_progressCall is live
completedCall ended normally
failedCall failed to connect

​
Reading results after the call

1

Stop the call

Send a stop request to end the session and trigger processing. If the agent already ended the call (via an end_call tool), this is a no-op.
curl -X POST https://api.oneinbox.ai/v1/calls/<call_id>/stop \
  -H "Authorization: Bearer <api_key>"
2

Wait 2–3 seconds

Transcript and analysis are written asynchronously after the session closes. A short wait ensures the data is ready before you fetch it.
3

Fetch the full record

Retrieve the complete call record including the transcript, AI-generated summary, and outcome.
curl https://api.oneinbox.ai/v1/calls/<call_id> \
  -H "Authorization: Bearer <api_key>"

{
  "status": "completed",
  "duration_seconds": 62,
  "messages": [...],
  "analysis": {
    "outcome": "Interested",
    "summary": "Caller asked about pricing and expressed interest in a demo."
  }
}

​
API reference

Start web call · Get call · Stop call