Microsoft Azure Communication Services Recording API

openapi: 3.2.0
info:
  title: Azure Communication Service Call Automation Recording API
  description: Azure Communication Service Call Automation APIs
  version: '2026-03-12'
servers:
- url: https://contoso.communication.azure.com
security:
- Authorization: []
tags:
- name: Recording
paths:
  /calling/recordings:
    post:
      tags:
      - Recording
      summary: Start recording the call
      operationId: CallRecording_StartRecording
      parameters:
      - $ref: '#/components/parameters/ApiVersionParameter'
      - in: header
        name: Repeatability-Request-ID
        description: 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.
        schema:
          type: string
          format: uuid
      - in: header
        name: Repeatability-First-Sent
        description: '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.'
        schema:
          type: string
          format: date-time-rfc1123
      responses:
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunicationErrorResponse'
        '200':
          description: Returns the start call recording response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordingStateResponse'
        '202':
          description: The service has accepted the StartCallRecording request and will begin processing it. You will receive either a StartRecordingFailed event or RecordingStateChanged event at your specified callback URI to update you on the status of the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordingStateResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartCallRecordingRequest'
        description: The request body of start call recording request.
        required: true
  /calling/recordings/{recordingId}:
    get:
      tags:
      - Recording
      summary: Get call recording properties
      operationId: CallRecording_GetRecordingProperties
      parameters:
      - $ref: '#/components/parameters/ApiVersionParameter'
      - in: path
        name: recordingId
        description: The recording id.
        required: true
        schema:
          type: string
      responses:
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunicationErrorResponse'
        '200':
          description: Returns the recording properties.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordingStateResponse'
    delete:
      tags:
      - Recording
      summary: Stop recording the call
      operationId: CallRecording_StopRecording
      parameters:
      - $ref: '#/components/parameters/ApiVersionParameter'
      - in: path
        name: recordingId
        description: The recording id.
        required: true
        schema:
          type: string
      responses:
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunicationErrorResponse'
        '204':
          description: Returns the stop call recording response.
  /calling/recordings/{recordingId}:pause:
    post:
      tags:
      - Recording
      summary: Pause recording the call
      operationId: CallRecording_PauseRecording
      parameters:
      - $ref: '#/components/parameters/ApiVersionParameter'
      - in: path
        name: recordingId
        description: The recording id.
        required: true
        schema:
          type: string
      responses:
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunicationErrorResponse'
        '202':
          description: The service has accepted the pause request and will begin processing it.
  /calling/recordings/{recordingId}:resume:
    post:
      tags:
      - Recording
      summary: Resume recording the call
      operationId: CallRecording_ResumeRecording
      parameters:
      - $ref: '#/components/parameters/ApiVersionParameter'
      - in: path
        name: recordingId
        description: The recording id.
        required: true
        schema:
          type: string
      responses:
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunicationErrorResponse'
        '202':
          description: The service has accepted the resume request and will begin processing it.
components:
  schemas:
    CommonMicrosoftTeamsAppIdentifierModel:
      description: A Microsoft Teams application.
      type: object
      required:
      - appId
      properties:
        appId:
          type: string
          description: The Id of the Microsoft Teams application.
        cloud:
          $ref: '#/components/schemas/CommunicationCloudEnvironmentModel'
          description: The cloud that the Microsoft Teams application belongs to. By default 'public' if missing.
    CommonCommunicationIdentifierModel:
      description: 'Identifies a participant in Azure Communication services. A participant is, for example, a phone number or an Azure communication user. This model is polymorphic: Apart from kind and rawId, at most one further property may be set which must match the kind enum value.'
      type: object
      properties:
        kind:
          $ref: '#/components/schemas/CommunicationIdentifierModelKind'
          description: The identifier kind. Only required in responses.
        rawId:
          type: string
          description: Raw Id of the identifier. Optional in requests, required in responses.
        communicationUser:
          $ref: '#/components/schemas/CommunicationUserIdentifierModel'
          description: The communication user.
        phoneNumber:
          $ref: '#/components/schemas/PhoneNumberIdentifierModel'
          description: The phone number.
        microsoftTeamsUser:
          $ref: '#/components/schemas/MicrosoftTeamsUserIdentifierModel'
          description: The Microsoft Teams user.
        microsoftTeamsApp:
          $ref: '#/components/schemas/MicrosoftTeamsAppIdentifierModel'
          description: The Microsoft Teams application.
        teamsExtensionUser:
          $ref: '#/components/schemas/TeamsExtensionUserIdentifierModel'
          description: The Microsoft Teams Extension user.
    StartCallRecordingRequest:
      description: The request payload start for call recording operation with call locator.
      type: object
      properties:
        callLocator:
          $ref: '#/components/schemas/CallLocator'
        callConnectionId:
          description: The call connection Id. (Only one of callLocator or callConnectionId to be used)
          type: string
        recordingStateCallbackUri:
          description: The uri to send notifications to.
          type: string
        recordingContentType:
          $ref: '#/components/schemas/RecordingContentType'
        recordingChannelType:
          $ref: '#/components/schemas/RecordingChannelType'
        recordingFormatType:
          $ref: '#/components/schemas/RecordingFormatType'
        audioChannelParticipantOrdering:
          description: 'The sequential order in which audio channels are assigned to participants in the unmixed recording.

            When ''recordingChannelType'' is set to ''unmixed'' and `audioChannelParticipantOrdering is not specified,

            the audio channel to participant mapping will be automatically assigned based on the order in which participant

            first audio was detected.  Channel to participant mapping details can be found in the metadata of the recording.'
          type: array
          items:
            $ref: '#/components/schemas/CommunicationIdentifierModel'
        channelAffinity:
          description: 'The channel affinity of call recording

            When ''recordingChannelType'' is set to ''unmixed'', if channelAffinity is not specified, ''channel'' will be automatically assigned.

            Channel-Participant mapping details can be found in the metadata of the recording.

            ///'
          type: array
          items:
            $ref: '#/components/schemas/ChannelAffinity'
        pauseOnStart:
          description: When set to true will start recording in Pause mode, which can be resumed.
          type: boolean
        externalStorage:
          $ref: '#/components/schemas/ExternalStorage'
      additionalProperties: false
    RecordingStorageKind:
      description: Defines the kind of external storage
      enum:
      - azureCommunicationServices
      - azureBlobStorage
      type: string
      x-ms-enum:
        name: RecordingStorageKind
        modelAsString: true
    CommonCommunicationErrorResponse:
      description: The Communication Services error.
      type: object
      required:
      - error
      properties:
        error:
          description: The Communication Services error.
          $ref: '#/components/schemas/CommunicationError'
    CommunicationError:
      $ref: '#/components/schemas/CommonCommunicationError'
    CommonPhoneNumberIdentifierModel:
      description: A phone number.
      type: object
      required:
      - value
      properties:
        value:
          type: string
          description: The phone number, usually in E.164 format.
        isAnonymous:
          type: boolean
          description: True if the phone number is anonymous. By default false if missing. If the phone number is anonymous, the value will be the string 'anonymous'.
        assertedId:
          type: string
          description: The asserted Id of the phone number. An asserted Id gets generated when the same phone number joins the same call more than once.
    RecordingState:
      enum:
      - active
      - inactive
      type: string
      x-ms-enum:
        name: RecordingState
        modelAsString: true
    CommonCommunicationError:
      description: The Communication Services error.
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: The error code.
        message:
          type: string
          description: The error message.
        target:
          type: string
          readOnly: true
          description: The error target.
        details:
          type: array
          items:
            $ref: '#/components/schemas/CommunicationError'
          readOnly: true
          description: Further details about specific errors that led to this error.
        innererror:
          x-ms-client-name: innerError
          readOnly: true
          $ref: '#/components/schemas/CommunicationError'
          description: The inner error if any.
    CommonCommunicationUserIdentifierModel:
      description: A user that got created with an Azure Communication Services resource.
      type: object
      required:
      - id
      properties:
        id:
          type: string
          description: The Id of the communication user.
    CallLocatorKind:
      description: The call locator kind
      enum:
      - groupCallLocator
      - serverCallLocator
      - roomCallLocator
      type: string
      x-ms-enum:
        name: CallLocatorKind
        modelAsString: true
    RecordingKind:
      enum:
      - azureCommunicationServices
      - teams
      - teamsCompliance
      type: string
      x-ms-enum:
        name: RecordingKind
        modelAsString: true
    CallLocator:
      description: The locator used for joining or taking action on a call
      type: object
      properties:
        groupCallId:
          description: The group call id
          type: string
        serverCallId:
          description: The server call id.
          type: string
        roomId:
          description: The Acs room id. (Not supported for Start Recording)
          type: string
        kind:
          $ref: '#/components/schemas/CallLocatorKind'
      additionalProperties: false
    RecordingContentType:
      description: The content type of call recording.
      enum:
      - audio
      - audioVideo
      type: string
      x-ms-enum:
        name: RecordingContentType
        modelAsString: true
    CommonTeamsExtensionUserIdentifierModel:
      description: A Microsoft Teams Phone user who is using a Communication Services resource to extend their Teams Phone set up.
      type: object
      required:
      - userId
      - tenantId
      - resourceId
      properties:
        userId:
          type: string
          description: The Id of the Microsoft Teams Extension user, i.e. the Entra ID object Id of the user.
        tenantId:
          type: string
          description: The tenant Id of the Microsoft Teams Extension user.
        resourceId:
          type: string
          description: The Communication Services resource Id.
        cloud:
          $ref: '#/components/schemas/CommunicationCloudEnvironmentModel'
          description: The cloud that the Microsoft Teams Extension user belongs to. By default 'public' if missing.
    ExternalStorage:
      required:
      - recordingStorageKind
      type: object
      properties:
        recordingStorageKind:
          $ref: '#/components/schemas/RecordingStorageKind'
        recordingDestinationContainerUrl:
          format: uri
          description: Uri of a container or a location within a container
          type: string
      additionalProperties: false
    RecordingFormatType:
      description: Defines the format type of call recording.
      enum:
      - wav
      - mp3
      - mp4
      type: string
      x-ms-enum:
        name: RecordingFormatType
        modelAsString: true
    TeamsExtensionUserIdentifierModel:
      $ref: '#/components/schemas/CommonTeamsExtensionUserIdentifierModel'
    CommunicationIdentifierModel:
      $ref: '#/components/schemas/CommonCommunicationIdentifierModel'
    RecordingStateResponse:
      type: object
      properties:
        recordingId:
          type: string
        recordingState:
          $ref: '#/components/schemas/RecordingState'
        recordingKind:
          $ref: '#/components/schemas/RecordingKind'
      additionalProperties: false
    CommunicationErrorResponse:
      $ref: '#/components/schemas/CommonCommunicationErrorResponse'
    MicrosoftTeamsUserIdentifierModel:
      $ref: '#/components/schemas/CommonMicrosoftTeamsUserIdentifierModel'
    MicrosoftTeamsAppIdentifierModel:
      $ref: '#/components/schemas/CommonMicrosoftTeamsAppIdentifierModel'
    RecordingChannelType:
      description: Defines the channel type of call recording.
      enum:
      - mixed
      - unmixed
      type: string
      x-ms-enum:
        name: RecordingChannelType
        modelAsString: true
    CommonMicrosoftTeamsUserIdentifierModel:
      description: A Microsoft Teams user.
      type: object
      required:
      - userId
      properties:
        userId:
          type: string
          description: The Id of the Microsoft Teams user. If not anonymous, this is the Entra ID object Id of the user.
        isAnonymous:
          type: boolean
          description: True if the Microsoft Teams user is anonymous. By default false if missing.
        cloud:
          $ref: '#/components/schemas/CommunicationCloudEnvironmentModel'
          description: The cloud that the Microsoft Teams user belongs to. By default 'public' if missing.
    ChannelAffinity:
      description: Channel affinity for a participant
      required:
      - participant
      type: object
      properties:
        channel:
          format: int32
          description: Channel number to which bitstream from a particular participant will be written.
          maximum: 4
          minimum: 0
          type: integer
        participant:
          $ref: '#/components/schemas/CommunicationIdentifierModel'
      additionalProperties: false
    PhoneNumberIdentifierModel:
      $ref: '#/components/schemas/CommonPhoneNumberIdentifierModel'
    CommunicationUserIdentifierModel:
      $ref: '#/components/schemas/CommonCommunicationUserIdentifierModel'
  parameters:
    ApiVersionParameter:
      in: query
      name: api-version
      description: Version of the API to invoke.
      required: true
      x-ms-parameter-location: method
      schema:
        type: string
  securitySchemes:
    Authorization:
      type: apiKey
      name: Authorization
      in: header
      description: An Azure Communication Services user access token.
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/components/parameters/Endpoint'