POST
/
v1
/
calls
/
create-web-call
{
  "_id": "<string>",
  "ai_agent_id": "<string>",
  "call_status": "registered",
  "override_ai_agent_id": "<string>",
  "metadata": {},
  "pia_llm_dynamic_data": {},
  "call_start_time": "2023-11-07T05:31:56Z",
  "call_end_time": "2023-11-07T05:31:56Z",
  "messages": [
    {
      "role": "agent",
      "content": "<string>"
    }
  ],
  "recorded_call_audio_url": "<string>",
  "access_token": "<string>",
  "call_duration_seconds": 123,
  "call_type": "web_call",
  "call_finish_reason": "user_ended_call"
}

Body

application/json
​
ai_agent_id
string
required

Identifier of the AI agent that will handle this web call

​
override_ai_agent_id
string | null

Optional alternative AI agent identifier for special handling scenarios

​
metadata
object | null

Custom key-value pairs for storing call-specific information

​
pia_llm_dynamic_data
object | null

Dynamic data to be used by the AI agent during this call

Response

201
application/json
Successful Response
​
call_status
enum<string>
required

Current status of the call: 'registered' for initialized calls, 'ongoing' for active calls, 'ended' for completed calls, 'error' for failed calls

Available options:
registered,
ongoing,
ended,
error
​
_id
string

Unique identifier for the call session, automatically generated as a MongoDB ObjectId

​
ai_agent_id
string | null

Identifier of the AI agent handling this call

​
override_ai_agent_id
string | null

Optional identifier for an alternative AI agent handling this call

​
metadata
object | null

Custom key-value pairs storing additional information about the call

​
pia_llm_dynamic_data
object | null

Dynamic data used by the AI agent during the call

​
call_start_time
string | null

Timestamp when the call was initiated, in UTC

​
call_end_time
string | null

Timestamp when the call was terminated, in UTC

​
messages
object[] | null

Chronological list of messages exchanged during the call

​
recorded_call_audio_url
string | null

URL to access the recorded audio file of the call

​
access_token
string | null

Security token for accessing call-related resources

​
call_duration_seconds
integer | null

Duration of the call in seconds

​
call_type
enum<string>
default:
web_call

Indicates this response is for a web-based call

Available options:
web_call
​
call_finish_reason
enum<string> | null

Detailed reason why the web call ended, if applicable

Available options:
user_ended_call,
agent_ended_call,
call_transferred,
inactivity_timeout,
maximum_duration_exceeded,
concurrent_call_limit_reached,
invalid_payment,
potential_scam_detected,
inbound_webhook_error,
line_busy,
call_failed,
no_answer,
llm_websocket_initialization_error,
llm_websocket_connection_lost,
llm_websocket_runtime_error,
llm_websocket_payload_corruption,
twilio_error,
no_audio_input,
speech_recognition_error,
pia_platform_internal_error,
unknown_error,
user_connection_failure
Delete custom toolCreate Web Call (Public Shared)