Call Connection - Transfer To Participant

Service:
Communication
API Version:
2026-03-12

Transfer the call to a participant.

POST {endpoint}/calling/callConnections/{callConnectionId}:transferToParticipant?api-version=2026-03-12

URI Parameters

Name In Required Type Description
callConnectionId
 path True

string

The call connection id.
endpoint
 path True

string (url)

The endpoint of the Azure Communication Service resource.
api-version
 query True

string

Version of the API to invoke.

Request Header

Name Required Type Description
Authorization True

string

An Azure Communication Services user access token.
Repeatability-Request-ID

string (uuid)

If specified, the client directs that the request is repeatable; that is, that the client can make the request multiple times with the same Repeatability-Request-Id and get back an appropriate response without the server executing the request multiple times. The value of the Repeatability-Request-Id is an opaque string representing a client-generated unique identifier for the request. It is a version 4 (random) UUID.
Repeatability-First-Sent

string (date-time-rfc1123)

If Repeatability-Request-ID header is specified, then Repeatability-First-Sent header must also be specified. The value should be the date and time at which the request was first created, expressed using the IMF-fixdate form of HTTP-date. Example: Sun, 06 Nov 1994 08:49:37 GMT.

Request Body

Name Required Type Description
targetParticipant True

CommunicationIdentifierModel

customCallingContext

CustomCallingContext

The custom calling context which will be sent to the target
operationCallbackUri

string

Set a callback URI that overrides the default callback URI set by CreateCall/AnswerCall for this operation. This setup is per-action. If this is not set, the default callback URI set by CreateCall/AnswerCall will be used.
operationContext

string

Used by customers when calling mid-call actions to correlate the request to the response event.
sourceCallerIdNumber

PhoneNumberIdentifierModel

transferee

CommunicationIdentifierModel

Responses

Name Type Description
202 Accepted

TransferCallResponse

The service has accepted the transfer request and will begin processing it. You will receive either CallTransferAccepted or CallTransferFailed event at your specified callback URI to update you on the status of the request.
Other Status Codes

CommunicationErrorResponse

Error

Security

Authorization

An Azure Communication Services user access token.

Type: apiKey
In: header

Examples

CallConnection_TransferToParticipant

Sample request

POST https://contoso.communications.azure.com/calling/callConnections/18dea47f-b081-4107-9a5c-4300819d2c6c:transferToParticipant?api-version=2026-03-12

{
  "targetParticipant": {
    "kind": "communicationUser",
    "communicationUser": {
      "id": "8:acs:b9614373-fd0b-480c-8fd2-cb58b70eab9f_da7be3a9-8788-42a6-85c6-56b2cf784fce"
    }
  },
  "transferee": {
    "kind": "communicationUser",
    "communicationUser": {
      "id": "8:acs:b9614373-fd0b-480c-8fd2-cb58b70eab9f_ae9e3307-f56e-44be-8934-80a63f080538"
    }
  },
  "operationCallbackUri": "https://app.contoso.com/callback",
  "operationContext": "trasferring call"
}

Sample response

Status code:
202 
{
  "operationContext": "trasferring call"
}

Definitions

Name Description
CustomCallingContext

The custom calling context which will be sent to the target
TeamsPhoneCallDetails

The call details which will be sent to the target
TeamsPhoneCallerDetails

Container for details relating to the original caller of the call
TeamsPhoneSourceDetails

Container for details relating to the entity responsible for the creation of these call details
TransferCallResponse

The response payload for transferring the call.
TransferToParticipantRequest

The request payload for transferring call to a participant.

CustomCallingContext

Object

The custom calling context which will be sent to the target

Name Type Description
sipHeaders

object

Custom calling context SIP headers
teamsPhoneCallDetails

TeamsPhoneCallDetails

The call details which will be sent to the target
voipHeaders

object

Custom calling context VoiP headers

TeamsPhoneCallDetails

Object

The call details which will be sent to the target

Name Type Description
callContext

string

A summary of the call thus far. It will be displayed on a side panel in the Teams UI
callSentiment

string

Sentiment of the call thus far
callTopic

string

A very short description (max 48 chars) of the reason for the call. To be displayed in Teams CallNotification
intent

string

The intent of the call
sessionId

string

Id to exclusively identify this call session. IVR will use this for their telemetry/reporting.
suggestedActions

string

Recommendations for resolving the issue based on the customer's intent and interaction history
teamsPhoneCallerDetails

TeamsPhoneCallerDetails

Container for details relating to the original caller of the call
teamsPhoneSourceDetails

TeamsPhoneSourceDetails

Container for details relating to the entity responsible for the creation of these call details
transcriptUrl

string

Url for fetching the transcript of the call

TeamsPhoneCallerDetails

Object

Container for details relating to the original caller of the call

Name Type Description
additionalCallerInformation

object

A set of key value pairs (max 10, any additional entries would be ignored) which a bot author wants to pass to the Teams Client for display to the agent
caller

CommunicationIdentifierModel

isAuthenticated

boolean

Flag indicating whether the caller was authenticated
name

string

Caller's name
phoneNumber

string

Caller's phone number
recordId

string

Caller's record ID (ex in CRM)
screenPopUrl

string

Caller's screen pop URL

TeamsPhoneSourceDetails

Object

Container for details relating to the entity responsible for the creation of these call details

Name Type Description
intendedTargets

Intended targets of the source entity passing along the call details
language

string

Language of the source entity passing along the call details, passed in the ISO-639 standard
source

CommunicationIdentifierModel

status

string

Status of the source entity passing along the call details

TransferCallResponse

Object

The response payload for transferring the call.

Name Type Description
operationContext

string

The operation context provided by client.

TransferToParticipantRequest

Object

The request payload for transferring call to a participant.

Name Type Description
customCallingContext

CustomCallingContext

The custom calling context which will be sent to the target
operationCallbackUri

string

Set a callback URI that overrides the default callback URI set by CreateCall/AnswerCall for this operation. This setup is per-action. If this is not set, the default callback URI set by CreateCall/AnswerCall will be used.
operationContext

string

Used by customers when calling mid-call actions to correlate the request to the response event.
sourceCallerIdNumber

PhoneNumberIdentifierModel

targetParticipant

CommunicationIdentifierModel

transferee

CommunicationIdentifierModel