Place a call
Rings to and runs agent_id on the call. This rings a real phone and uses wallet credit. It answers 202 once the call is accepted. The phone hasn’t rung yet, so poll Get call or take the webhooks sent to webhook_url.
Before your company goes live, every call runs and is billed at t5 (₹5 a minute, in 10-second blocks), whatever tier you send. The wallet must cover one minute before anything is dialled, or you get a 402 and nothing is charged.
Idempotency-Key keeps a retry to one phone call. The same key within 24 hours replays the first 202 (with Idempotent-Replay: true) and dials nothing. In your own code, build the key from your own record, like order-8842-reminder-1.
Everything but agent_id and to is optional:
variablesfill the placeholders in the agent’s prompt and first message (up to 32, 512 characters each). Tools read them asvars.*.metadatais your own ids. They come back on the call and on every webhook, and the agent never sees them.webhook_url,max_duration_secs(30–1800),first_message,timing,recording_enabledandfinal_resultswork as the docs describe.phone_number_idcalls from one of your own numbers (see Phone numbers) instead of the default route.
A browser call instead: see Start a browser call: the same request with "channel": "web" and no to. "channel": "realtime" opens an OpenAI Realtime-compatible session the same way. Both are billed per minute like a phone call.
Authorizations
Your workspace secret key, sk_live_ followed by 32 hex characters. Create one in the console under Developers.
Headers
Up to 255 characters. The same key within 24 hours replays the first answer and creates nothing new. Build it from your own record, such as order-8842-reminder-1.
255Body
The agent that runs the call. Required for channel phone and web. Optional for channel realtime: without it the session starts with an empty prompt, no tools, no greeting, the default voice and automatic language, and the Realtime client's session.update configures it. A realtime session never plays the agent's first_message; the client's first response.create starts the conversation.
1x >= 1phone dials to. web is a browser session: no to, no route; the answer adds ws_url and events_url. realtime is an OpenAI Realtime-compatible session with the same rules, answer and per-minute price as web, except that it is refused (429 concurrency_limit) rather than queued when no voice slot is free; first_message, system_prompt, timing, test and flow agents are not accepted on it.
phone, web, realtime Send one consolidated call.processed after the call ends, once its transcript, any analysis or post-call tools and a flow agent's outcome settle, carrying data.transcript (and data.call.flow for a flow agent). Requires webhook_url.
Replaces the agent's opening line for this call only. {{var}} placeholders are substituted and validated like the agent's first_message. Not accepted for channel realtime.
1 - 500Your own correlation ids (for example session_id, user_id). Frozen with the call and echoed unchanged in the call object and every webhook's data.call. Never given to the agent. Serialized size at most 4096 bytes. Do not put secrets here.
Store the call's audio. Default true; a workspace whose policy disables recording defaults to false and answers true with 403 recording_disabled.
Replaces the agent's system prompt for this call only; the agent, its revision and every other setting stay the agent's. {{var}} placeholders are filled from this call's variables and validated like the agent's system_prompt (with an input_schema, each must be a declared input, a system variable or a pre-call tool output). Stored with the call but never returned on the call object or in webhooks. Not accepted for channel realtime (400 invalid_request) or for a flow agent (409 flow_system_prompt_unsupported).
1 - 12000Web and phone calls only (not realtime). Seconds count from live media start; max_duration_secs stays the hard cap. The *_before_end values must be at most the call's effective max_duration_secs minus 10, and close_secs_before_end less than wrap_up_secs_before_end when both are set.
Response
Accepted, not dialled yet
202 response of POST /v2/calls. Web calls and realtime sessions add the session credentials: paths the public edge makes absolute. transport names the channel.
queued Live events (Server-Sent Events) path with a reusable read-only token, valid for the call's maximum duration plus one hour.
web, realtime Browser audio socket path with a single-use token. Expires at ws_url_expires_at (300 seconds). An idempotent replay repeats it only while the token is unused.