Call Connection - Add Participant

Service:: Communication

API Version:: 2026-03-12

Add a participant to the call.

POST {endpoint}/calling/callConnections/{callConnectionId}/participants:add?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
participantToAdd	True	CommunicationIdentifierModel
customCallingContext		CustomCallingContext	The custom calling context which will be sent to the target
invitationTimeoutInSeconds		integer (int32) minimum: 0 maximum: 180	Gets or sets the timeout to wait for the invited participant to pickup. The maximum value of this is 180 seconds
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
sourceDisplayName		string	(Optional) The display name of the source that is associated with this invite operation when adding a PSTN participant or teams user. Note: Will not update the display name in the roster.

Responses

Name	Type	Description
202 Accepted	AddParticipantResponse	The service has accepted the add participant request and will begin processing it. You will receive either AddParticipantSucceeded or AddParticipantFailed 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_AddParticipant

Sample request

HTTP

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

{
  "participantToAdd": {
    "kind": "communicationUser",
    "communicationUser": {
      "id": "8:acs:b9614373-fd0b-480c-8fd2-cb58b70eab9f_ae9e3307-f56e-44be-8934-80a63f080538"
    }
  },
  "operationContext": "adding participant",
  "sourceCallerIdNumber": {
    "value": "+18440123456"
  },
  "operationCallbackUri": "https://app.contoso.com/callback"
}

Sample response

Status code:: 202

{
  "operationContext": "adding participant",
  "participant": {
    "identifier": {
      "kind": "communicationUser",
      "communicationUser": {
        "id": "8:acs:b9614373-fd0b-480c-8fd2-cb58b70eab9f_ae9e3307-f56e-44be-8934-80a63f080538"
      }
    },
    "isMuted": false
  },
  "invitationId": "7b4244f8-d2ff-46d1-a629-4f9fb5f73d40"
}

Definitions

Name	Description
AddParticipantRequest	The request payload for adding participant to the call.
AddParticipantResponse	The response payload for adding participants to the call.
CallParticipant	A call participant.
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

AddParticipantRequest

Object

The request payload for adding participant to the call.

Name	Type	Description
customCallingContext	CustomCallingContext	The custom calling context which will be sent to the target
invitationTimeoutInSeconds	integer (int32) minimum: 0 maximum: 180	Gets or sets the timeout to wait for the invited participant to pickup. The maximum value of this is 180 seconds
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.
participantToAdd	CommunicationIdentifierModel
sourceCallerIdNumber	PhoneNumberIdentifierModel
sourceDisplayName	string	(Optional) The display name of the source that is associated with this invite operation when adding a PSTN participant or teams user. Note: Will not update the display name in the roster.

AddParticipantResponse

Object

The response payload for adding participants to the call.

Name	Type	Description
invitationId	string	Invitation ID used to add a participant.
operationContext	string	The operation context provided by client.
participant	CallParticipant	A call participant.

CallParticipant

Object

A call participant.

Name	Type	Description
identifier	CommunicationIdentifierModel
isMuted	boolean	Is participant muted
isOnHold	boolean	Is participant on hold.

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