Agent Telephony

Transfer an active agent telephony call

POST /agents/{agent_name}/telephony/calls/{call_id}:transfer

Transfers an active inbound call to a configured target for the voice agent named in the path.

Header parameters

Foundry-Features enum

A feature flag opt-in required when using preview operations or modifying persisted preview resources.

VoiceAgents=V1Preview

Path parameters

agent_name string required

The name of the voice agent that owns the active call.

call_id string required

The service-generated call identifier.

Query parameters

api-version string required

The API version to use for this operation.

Request Body

Content-Type: application/json

target string required

The unique name of a telephony transfer target.

Responses

The request has succeeded.

Body

Content-Type: application/json

id string required

A service-generated telephony call identifier.

provider string | enum required

A telephony provider supported by an agent binding. Known values are stable; additional values may be added over time.

Any of the following:

string

enum

teams_phone_extensiontwilio

provider_call_id string

The provider-assigned call identifier, when available.

caller_number string

The caller's phone number, when supplied by the provider.

provider_number string

The Teams Phone Extension or Twilio number that received the call.

status string | enum required

The lifecycle status of an inbound telephony call.

Any of the following:

string

enum

in_progresssuccessfailed

phase string | enum required

The provider-neutral phase reached by an inbound telephony call.

Any of the following:

string

enum

receivedvalidatedadmittedansweringansweredmedia_connectedagent_session_readybridgingmanagingcompletedrejectedfailed

started_at integer required

answered_at integer

media_connected_at integer

agent_session_ready_at integer

ended_at integer

duration_ms integer

A duration encoded as an integer number of milliseconds.

end_reason string | enum

Known service-generated reasons that one telephony call ended, rather than reasons for an overall outbound call job. Additional string codes may be returned.

Any of the following:

string

enum

invalid_webhook_payloadwebhook_validation_failedbinding_not_foundbinding_suspendedadmission_rejectedadmission_check_failedroute_agent_mismatchinvalid_binding_configurationcredential_resolution_failedprovider_resource_mismatchendpoint_resolution_failedingress_setup_failedlive_call_conflictlive_call_persistence_failedanswer_failedprovider_disconnectedprovider_busyprovider_no_answerprovider_cancelledprovider_failedprovider_stream_errorprovider_stream_stoppedagent_session_connect_failedmedia_stream_endedbridge_cancelledbridge_failedmanaged_hangupmanaged_transfermanage_hangup_failedmanage_transfer_failed

provider_status_code integer

The provider status code associated with the terminal result.

provider_sub_code integer

The provider subcode associated with the terminal result.

provider_message string

The provider message associated with the terminal result.

timing TelephonyCallTiming required

Detailed provider-neutral timing for an inbound telephony call.

received_at integer

validated_at integer

admitted_at integer

answer_requested_at integer

answered_at integer

media_connected_at integer

agent_session_ready_at integer

first_caller_audio_at integer

first_agent_audio_at integer

ended_at integer

duration_basis string | enum

The timestamp used as the basis for call duration.

Any of the following:

string

enum

answeredreceived

timestamp_source string | enum required

The source of a telephony lifecycle timestamp.

Any of the following:

string

enum

providergatewayderived

trace TelephonyCallTrace

Correlation from a durable telephony call record to its customer-facing Foundry trace.

status string | enum required

The availability status of a customer-facing telephony call trace.

Any of the following:

string

enum

pendingemittingavailablenot_recordednot_applicablefailed

trace_id string

The W3C trace identifier, when a trace was recorded.

root_span_id string

The root span identifier, when a trace was recorded.

conversation_id string

The voice-agent conversation identifier, when a conversation was created.

mode string | enum

The mode used to expose a telephony call as a customer-facing Foundry trace.

Any of the following:

string

enum

livepost_call

events TelephonyCallLifecycleEvent[] required

The lifecycle timeline.

events_truncated boolean required

Whether older lifecycle events were omitted from the timeline.