AddParticipantRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/microsoft-azure-communication-services/json-schema/microsoft-azure-communication-services-add-participant-request-schema.json",
  "title": "AddParticipantRequest",
  "description": "The request payload for adding participant to the call.",
  "x-generated": "2026-11-05",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/_superseded/microsoft-azure-communication-services-callautomation-api-openapi.yml#/components/schemas/AddParticipantRequest",
  "required": [
    "participantToAdd"
  ],
  "type": "object",
  "properties": {
    "sourceCallerIdNumber": {
      "$ref": "#/$defs/PhoneNumberIdentifierModel"
    },
    "sourceDisplayName": {
      "description": "(Optional) The display name of the source that is associated with this invite operation when\r\nadding a PSTN participant or teams user.  Note: Will not update the display name in the roster.",
      "type": "string"
    },
    "participantToAdd": {
      "$ref": "#/$defs/CommunicationIdentifierModel"
    },
    "invitationTimeoutInSeconds": {
      "format": "int32",
      "description": "Gets or sets the timeout to wait for the invited participant to pickup.\r\nThe maximum value of this is 180 seconds",
      "maximum": 180,
      "minimum": 0,
      "type": "integer"
    },
    "operationContext": {
      "description": "Used by customers when calling mid-call actions to correlate the request to the response event.",
      "type": "string"
    },
    "operationCallbackUri": {
      "description": "Set a callback URI that overrides the default callback URI set by CreateCall/AnswerCall for this operation.\r\nThis setup is per-action. If this is not set, the default callback URI set by CreateCall/AnswerCall will be used.",
      "type": "string"
    },
    "customCallingContext": {
      "$ref": "#/$defs/CustomCallingContext"
    }
  },
  "additionalProperties": false,
  "$defs": {
    "CommunicationIdentifierModel": {
      "$ref": "../../../Common/stable/2025-06-30/common.json#/components/schemas/CommunicationIdentifierModel"
    },
    "CustomCallingContext": {
      "description": "The custom calling context which will be sent to the target",
      "type": "object",
      "properties": {
        "voipHeaders": {
          "description": "Custom calling context VoiP headers",
          "type": "object",
          "additionalProperties": {
            "type": "string"
          }
        },
        "sipHeaders": {
          "description": "Custom calling context SIP headers",
          "type": "object",
          "additionalProperties": {
            "type": "string"
          }
        },
        "teamsPhoneCallDetails": {
          "$ref": "#/$defs/TeamsPhoneCallDetails"
        }
      },
      "additionalProperties": false
    },
    "PhoneNumberIdentifierModel": {
      "$ref": "../../../Common/stable/2025-06-30/common.json#/components/schemas/PhoneNumberIdentifierModel"
    },
    "TeamsPhoneCallDetails": {
      "description": "The call details which will be sent to the target",
      "type": "object",
      "properties": {
        "teamsPhoneCallerDetails": {
          "$ref": "#/$defs/TeamsPhoneCallerDetails"
        },
        "teamsPhoneSourceDetails": {
          "$ref": "#/$defs/TeamsPhoneSourceDetails"
        },
        "sessionId": {
          "description": "Id to exclusively identify this call session. IVR will use this for their telemetry/reporting.",
          "type": "string"
        },
        "intent": {
          "description": "The intent of the call",
          "type": "string"
        },
        "callTopic": {
          "description": "A very short description (max 48 chars) of the reason for the call. To be displayed in Teams CallNotification",
          "type": "string"
        },
        "callContext": {
          "description": "A summary of the call thus far. It will be displayed on a side panel in the Teams UI",
          "type": "string"
        },
        "transcriptUrl": {
          "description": "Url for fetching the transcript of the call",
          "type": "string"
        },
        "callSentiment": {
          "description": "Sentiment of the call thus far",
          "type": "string"
        },
        "suggestedActions": {
          "description": "Recommendations for resolving the issue based on the customer's intent and interaction history",
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "TeamsPhoneCallerDetails": {
      "description": "Container for details relating to the original caller of the call",
      "required": [
        "caller",
        "name",
        "phoneNumber"
      ],
      "type": "object",
      "properties": {
        "caller": {
          "$ref": "#/$defs/CommunicationIdentifierModel"
        },
        "name": {
          "description": "Caller's name",
          "type": "string"
        },
        "phoneNumber": {
          "description": "Caller's phone number",
          "type": "string"
        },
        "recordId": {
          "description": "Caller's record ID (ex in CRM)",
          "type": "string"
        },
        "screenPopUrl": {
          "description": "Caller's screen pop URL",
          "type": "string"
        },
        "isAuthenticated": {
          "description": "Flag indicating whether the caller was authenticated",
          "type": "boolean"
        },
        "additionalCallerInformation": {
          "description": "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",
          "type": "object",
          "additionalProperties": {
            "type": "string"
          }
        }
      },
      "additionalProperties": false
    },
    "TeamsPhoneSourceDetails": {
      "description": "Container for details relating to the entity responsible for the creation of these call details",
      "required": [
        "language",
        "source",
        "status"
      ],
      "type": "object",
      "properties": {
        "source": {
          "$ref": "#/$defs/CommunicationIdentifierModel"
        },
        "language": {
          "description": "Language of the source entity passing along the call details, passed in the ISO-639 standard",
          "type": "string"
        },
        "status": {
          "description": "Status of the source entity passing along the call details",
          "type": "string"
        },
        "intendedTargets": {
          "description": "Intended targets of the source entity passing along the call details",
          "type": "object",
          "additionalProperties": {
            "$ref": "#/$defs/CommunicationIdentifierModel"
          }
        }
      },
      "additionalProperties": false
    }
  }
}