Skip to main content

Calls — client.call

Place phone calls, browser (web) calls, and test calls; retrieve transcripts, recordings, and analytics.

create_phone_call(**params) → CallResponse​

POST /v1/calls/phone — place an outbound PSTN call immediately.

ParamTypeRequiredDescription
agent_idstryesA published agent.
from_numberstryesCaller ID in E.164 (+14155550123); a number you own.
to_numberstryesDestination in E.164.
metadatadictnoArbitrary metadata stored on the call.
dynamic_variablesdict[str,str]noValues injected into the system prompt.
batch_call_idstrnoLink this call to a batch campaign.
call = client.call.create_phone_call(
    agent_id="ag_abc123",
    from_number="+14155550123",
    to_number="+14155550199",
    dynamic_variables={"customer_name": "Jordan"},
)

create_web_call(agent_id, metadata=None, dynamic_variables=None) → CallResponse​

POST /v1/calls/web — browser-to-agent call over WebRTC. The response includes access_token, room_name, and room_url for the LiveKit client SDK to connect.

create_test_call(agent_id, temp_config=None, dynamic_variables=None) → CallResponse​

POST /v1/calls/test — like a web call but accepts draft agents and a temp_config dict of non-persisted overrides. Great for development.

CallResponse fields: call_id, call_type (inbound/outbound/web), status (waiting→ringing→connected→ended/failed), agent_id, from_number, to_number, access_token, room_name, room_url, start_time, end_time, duration_seconds, transcript, recording_url, call_analysis, call_summary, call_sentiment, call_cost, latency_metrics, processing_status, workflow_executions, created_at.

retrieve(call_id) → CallResponse​

GET /v1/calls/{call_id} — full call details (poll this after a call ends for the transcript, recording URL, and analytics).

list(skip=0, limit=20, agent_id=None, status=None, call_type=None, batch_call_id=None, from_date=None, to_date=None) → list[CallListItem]​

GET /v1/calls — list calls with optional filters. batch_call_id accepts a UUID, "none" (single calls only), or "any" (batch calls only).

end(call_id) → dict​

POST /v1/calls/{call_id}/end — end an active call and trigger post-call processing.

delete(call_id) → None​

DELETE /v1/calls/{call_id} — delete a call record.

get_recording(call_id) → bytes​

GET /v1/calls/{call_id}/recording — raw audio bytes (typically OGG). Check retrieve(...).recording_url first.