Dial Outbound Phone Call
Initiate an outbound phone call from an AI agent to a specified phone number.
This endpoint triggers the AI agent to place a phone call to the provided number. Use this for scenarios where the AI needs to proactively contact users via phone.
Body
Specifies whether this is an incoming or outgoing call
inbound, outbound The phone number initiating the call (E.164 format)
The phone number receiving the call (E.164 format)
Optional custom identifier for the call, if not provided, one will be generated
Custom key-value pairs for storing call-specific information
Optional alternative AI agent identifier for special handling scenarios
Dynamic data to be used by the AI agent during this call
Response
Current status of the call: 'registered' for initialized calls, 'ongoing' for active calls, 'ended' for completed calls, 'error' for failed calls
registered, ongoing, ended, error Indicates whether the call was received by or initiated from the Pia Platform
inbound, outbound The phone number that initiated the call (E.164 format)
The phone number that received the call (E.164 format)
Unique identifier for the call session, automatically generated as a MongoDB ObjectId
Security token for accessing call-related resources
Identifier of the AI agent handling this call
Duration of the call in seconds
Timestamp when the call was terminated, in UTC
Detailed reason why the phone call ended, if applicable
user_ended_call, agent_ended_call, call_transferred, voicemail_detected, inactivity_timeout, answering_machine_detected, 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, frontend_payload_corruption, twilio_service_error, no_audio_input, speech_recognition_error, retell_service_error, unknown_error, user_connection_failure, registered_call_timed_out Timestamp when the call was initiated, in UTC
Indicates this response is for a telephone call
phone_call Chronological list of messages exchanged during the call
Custom key-value pairs storing additional information about the call
Optional identifier for an alternative AI agent handling this call
Dynamic data used by the AI agent during the call
URL to access the recorded audio file of the call