Microsoft Azure MidConnections API

openapi: 3.2.0
info:
  version: 2022-04-07-preview
  title: Microsoft Azure Azure Communication Service Call Automation…
  description: Azure Communication Service Call Automation APIs
tags:
- name: MidConnections
paths:
  /calling/callConnections/{callConnectionId}:
    get:
      tags:
      - MidConnections
      summary: Microsoft Azure Get Call Connection
      operationId: microsoftAzureCallconnectionsGetcall
      parameters:
      - name: callConnectionId
        in: path
        description: The call connection id.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/ApiVersionParameter'
      responses:
        '200':
          description: Returns the get call response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallConnectionProperties'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunicationErrorResponse'
      x-ms-examples:
        Get call connection.:
          $ref: ./examples/CallConnections_GetCall.json
      description: Needs a more full description created.
    delete:
      tags:
      - MidConnections
      summary: Microsoft Azure Hangup The Call
      description: Hangup the call.
      operationId: microsoftAzureCallconnectionsHangupcall
      parameters:
      - name: callConnectionId
        in: path
        description: The call connection id.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/ApiVersionParameter'
      responses:
        '204':
          description: Returns the hangup call response.
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunicationErrorResponse'
      x-ms-examples:
        Hangup the call.:
          $ref: ./examples/CallConnections_HangupCall.json
  /calling/callConnections/{callConnectionId}:terminate:
    post:
      tags:
      - MidConnections
      summary: Microsoft Azure Terminate A Call Using Callconnectionid
      description: Terminate a call using CallConnectionId.
      operationId: microsoftAzureCallconnectionsTerminatecall
      parameters:
      - name: callConnectionId
        in: path
        description: The terminate call request.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/ApiVersionParameter'
      - name: Repeatability-Request-ID
        in: header
        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
      - name: Repeatability-First-Sent
        in: header
        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
      responses:
        '204':
          description: Returns the terminate call response.
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunicationErrorResponse'
      x-ms-examples:
        Terminate a call using CallConnectionId.:
          $ref: ./examples/CallConnections_TerminateCall.json
  /calling/callConnections/{callConnectionId}:transferToParticipant:
    post:
      tags:
      - MidConnections
      summary: Microsoft Azure Transfer The Call To A Participant
      description: Transfer the call to a participant.
      operationId: microsoftAzureCallconnectionsTransfertoparticipant
      parameters:
      - name: callConnectionId
        in: path
        description: The call connection id.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/ApiVersionParameter'
      - name: Repeatability-Request-ID
        in: header
        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
      - name: Repeatability-First-Sent
        in: header
        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
      responses:
        '202':
          description: Returns the transfer call response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransferCallResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunicationErrorResponse'
      x-ms-examples:
        Transfer the call to a participant.:
          $ref: ./examples/CallConnections_TransferToParticipant.json
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransferToParticipantRequest'
        description: The transfer to participant request.
        required: true
  /calling/callConnections/{callConnectionId}:play:
    post:
      tags:
      - MidConnections
      summary: Microsoft Azure Plays Audio To Participants In The Call
      description: Plays audio to participants in the call.
      operationId: microsoftAzureContentPlay
      parameters:
      - name: callConnectionId
        in: path
        description: The call connection id.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/ApiVersionParameter'
      responses:
        '202':
          description: Returns the play audio response.
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunicationErrorResponse'
      x-ms-examples:
        Plays audio to participants in the call.:
          $ref: ./examples/Content_Play.json
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlayRequest'
        description: play request payload.
        required: true
  /calling/callConnections/{callConnectionId}:cancelAllMediaOperations:
    post:
      tags:
      - MidConnections
      summary: Microsoft Azure Cancel All Media Operations In A Call
      description: Cancel all media operations in a call.
      operationId: microsoftAzureContentCancelallmediaoperations
      parameters:
      - name: callConnectionId
        in: path
        description: The call connection id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/ApiVersionParameter'
      responses:
        '202':
          description: Returns the cancel all media operations response.
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunicationErrorResponse'
      x-ms-examples:
        Cancel all media operations in a call.:
          $ref: ./examples/Content_CancelAllMediaOperations.json
  /calling/callConnections/{callConnectionId}:recognize:
    post:
      tags:
      - MidConnections
      summary: Microsoft Azure Recognize Media From Call
      description: Recognize media from call.
      operationId: microsoftAzureContentRecognize
      parameters:
      - name: callConnectionId
        in: path
        description: The call connection id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/ApiVersionParameter'
      responses:
        '202':
          description: Returns the recognize response.
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunicationErrorResponse'
      x-ms-examples:
        Recognize media from call.:
          $ref: ./examples/Content_Recognize.json
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecognizeRequest'
        description: The media recognize request
        required: true
  /calling/callConnections/{callConnectionId}/participants:
    get:
      tags:
      - MidConnections
      summary: Microsoft Azure Get Participants From A Call
      description: Get participants from a call.
      operationId: microsoftAzureCallconnectionsGetparticipants
      parameters:
      - name: callConnectionId
        in: path
        description: The call connection Id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/ApiVersionParameter'
      responses:
        '200':
          description: Returns the get participants response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetParticipantsResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunicationErrorResponse'
      x-ms-examples:
        Get participants from a call.:
          $ref: ./examples/CallConnections_GetParticipants.json
  /calling/callConnections/{callConnectionId}/participants:add:
    post:
      tags:
      - MidConnections
      summary: Microsoft Azure Add Participants To The Call
      description: Add participants to the call.
      operationId: microsoftAzureCallconnectionsAddparticipant
      parameters:
      - name: callConnectionId
        in: path
        description: The call connection Id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/ApiVersionParameter'
      - name: Repeatability-Request-ID
        in: header
        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
      - name: Repeatability-First-Sent
        in: header
        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
      responses:
        '202':
          description: Returns the add participant response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddParticipantsResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunicationErrorResponse'
      x-ms-examples:
        Add participants to the call.:
          $ref: ./examples/CallConnections_AddParticipant.json
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddParticipantsRequest'
        description: The add participants request.
        required: true
  /calling/callConnections/{callConnectionId}/participants:remove:
    post:
      tags:
      - MidConnections
      summary: Microsoft Azure Remove Participant From The Call Using Identifier
      description: Remove participant from the call using identifier.
      operationId: microsoftAzureCallconnectionsRemoveparticipants
      parameters:
      - name: callConnectionId
        in: path
        description: The call connection id.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/ApiVersionParameter'
      - name: Repeatability-Request-ID
        in: header
        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
      - name: Repeatability-First-Sent
        in: header
        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
      responses:
        '202':
          description: Returns the remove participant response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RemoveParticipantsResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunicationErrorResponse'
      x-ms-examples:
        Remove participant from the call using identifier.:
          $ref: ./examples/CallConnections_RemoveParticipants.json
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RemoveParticipantsRequest'
        description: The participants to be removed from the call.
        required: true
  /calling/callConnections/{callConnectionId}/participants/{participantMri}:
    get:
      tags:
      - MidConnections
      summary: Microsoft Azure Get Participant From A Call
      description: Get participant from a call.
      operationId: microsoftAzureCallconnectionsGetparticipant
      parameters:
      - name: callConnectionId
        in: path
        description: The call connection Id
        required: true
        schema:
          type: string
      - name: participantMri
        in: path
        description: MRI of the participants to retrieve.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/ApiVersionParameter'
      responses:
        '200':
          description: Returns the get participant response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcsCallParticipant'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunicationErrorResponse'
      x-ms-examples:
        Get participant from a call.:
          $ref: ./examples/CallConnections_GetParticipant.json
components:
  schemas:
    CallConnectionStateModel:
      description: The state of the call connection.
      enum:
      - unknown
      - connecting
      - connected
      - transferring
      - transferAccepted
      - disconnecting
      - disconnected
      type: string
      x-ms-enum:
        name: CallConnectionStateModel
        modelAsString: true
    AddParticipantsRequest:
      description: The request payload for adding participants to the call.
      required:
      - participantsToAdd
      type: object
      properties:
        sourceCallerId:
          $ref: '#/components/schemas/PhoneNumberIdentifierModel'
          description: "The source caller Id, a phone number, that's shown to the PSTN participant being invited. \nRequired only when inviting a PSTN participant."
        participantsToAdd:
          description: The participants to invite.
          type: array
          items:
            $ref: '#/components/schemas/CommunicationIdentifierModel'
        invitationTimeoutInSeconds:
          format: int32
          description: 'Gets or sets the timeout to wait for the invited participant to pickup.

            The 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
    PlayRequest:
      required:
      - playSourceInfo
      type: object
      properties:
        playSourceInfo:
          $ref: '#/components/schemas/PlaySource'
          description: The source of the audio to be played.
        playTo:
          description: "The list of call participants play provided audio to. \nPlays to everyone in the call when not provided."
          type: array
          items:
            $ref: '#/components/schemas/CommunicationIdentifierModel'
        playOptions:
          $ref: '#/components/schemas/PlayOptions'
          description: Defines options for playing the audio.
        operationContext:
          description: The value to identify context of the operation.
          type: string
    TransferToParticipantRequest:
      description: The request payload for transferring call to a participant.
      required:
      - targetParticipant
      type: object
      properties:
        targetParticipant:
          $ref: '#/components/schemas/CommunicationIdentifierModel'
          description: The identity of the target where call should be transferred to.
        transfereeCallerId:
          $ref: '#/components/schemas/PhoneNumberIdentifierModel'
          description: The caller ID of the transferee when transferring to PSTN.
        userToUserInformation:
          description: The user to user information.
          type: string
        operationContext:
          description: Used by customers when calling mid-call actions to correlate the request to the response event.
          type: string
    RecognizeOptions:
      required:
      - targetParticipant
      type: object
      properties:
        interruptPrompt:
          description: Determines if we interrupt the prompt and start recognizing.
          type: boolean
        initialSilenceTimeoutInSeconds:
          format: int32
          description: Time to wait for first input after prompt (if any).
          maximum: 300
          minimum: 0
          type: integer
        targetParticipant:
          $ref: '#/components/schemas/CommunicationIdentifierModel'
          description: Target participant of DTMF tone recognition.
        dtmfOptions:
          $ref: '#/components/schemas/DtmfOptions'
          description: Defines configurations for DTMF.
    RemoveParticipantsResponse:
      description: The response payload for removing participants of the call.
      type: object
      properties:
        operationContext:
          description: The operation context provided by client.
          type: string
    CallSource:
      description: The caller.
      required:
      - identifier
      type: object
      properties:
        callerId:
          $ref: '#/components/schemas/PhoneNumberIdentifierModel'
          description: "The source caller Id, a phone number, that's shown to the PSTN participant being invited. \nRequired only when calling a PSTN callee."
        displayName:
          description: Display name of the call if dialing out to a pstn number
          type: string
        identifier:
          $ref: '#/components/schemas/CommunicationIdentifierModel'
          description: The identifier of the source of the call
    CommunicationUserIdentifierModel:
      required:
      - id
      type: object
      properties:
        id:
          type: string
    FileSource:
      required:
      - uri
      type: object
      properties:
        uri:
          description: Uri for the audio file to be played
          type: string
    AcsCallParticipant:
      description: Contract model of an ACS call participant
      type: object
      properties:
        identifier:
          $ref: '#/components/schemas/CommunicationIdentifierModel'
          description: Communication identifier of the participant
        isMuted:
          description: Is participant muted
          type: boolean
    CommunicationCloudEnvironmentModel:
      enum:
      - public
      - dod
      - gcch
      type: string
      x-ms-enum:
        name: CommunicationCloudEnvironmentModel
        modelAsString: true
    RemoveParticipantsRequest:
      description: The remove participant by identifier request.
      required:
      - participantsToRemove
      type: object
      properties:
        participantsToRemove:
          description: The participants to be removed from the call.
          type: array
          items:
            $ref: '#/components/schemas/CommunicationIdentifierModel'
        operationContext:
          description: Used by customers when calling mid-call actions to correlate the request to the response event.
          type: string
    PlaySource:
      required:
      - sourceType
      type: object
      properties:
        sourceType:
          $ref: '#/components/schemas/PlaySourceType'
        playSourceId:
          description: Defines the identifier to be used for caching related media
          type: string
        fileSource:
          $ref: '#/components/schemas/FileSource'
          description: Defines the file source info to be used for play
    AddParticipantsResponse:
      description: The response payload for adding participants to the call.
      type: object
      properties:
        participants:
          description: List of current participants in the call.
          type: array
          items:
            $ref: '#/components/schemas/AcsCallParticipant'
        operationContext:
          description: The operation context provided by client.
          type: string
    CommunicationIdentifierModel:
      type: object
      properties:
        rawId:
          description: Full ID of the identifier.
          type: string
        kind:
          $ref: '#/components/schemas/CommunicationIdentifierModelKind'
        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.
    RecognizeInputType:
      description: Determines the type of the recognition.
      enum:
      - dtmf
      type: string
      x-ms-enum:
        name: RecognizeInputType
        modelAsString: true
    MicrosoftTeamsUserIdentifierModel:
      required:
      - userId
      type: object
      properties:
        userId:
          type: string
        isAnonymous:
          type: boolean
        cloud:
          $ref: '#/components/schemas/CommunicationCloudEnvironmentModel'
    Tone:
      enum:
      - zero
      - one
      - two
      - three
      - four
      - five
      - six
      - seven
      - eight
      - nine
      - a
      - b
      - c
      - d
      - pound
      - asterisk
      type: string
      x-ms-enum:
        name: Tone
        modelAsString: true
    CommunicationIdentifierModelKind:
      description: Type of CommunicationIdentifierModel.
      enum:
      - unknown
      - communicationUser
      - phoneNumber
      - microsoftTeamsUser
      type: string
      x-ms-enum:
        name: CommunicationIdentifierModelKind
        modelAsString: true
    RecognizeRequest:
      required:
      - recognizeInputType
      - recognizeOptions
      type: object
      properties:
        recognizeInputType:
          $ref: '#/components/schemas/RecognizeInputType'
        playPrompt:
          $ref: '#/components/schemas/PlaySource'
          description: The source of the audio to be played for recognition.
        interruptCallMediaOperation:
          description: If set recognize can barge into other existing queued-up/currently-processing requests.
          type: boolean
        recognizeOptions:
          $ref: '#/components/schemas/RecognizeOptions'
          description: Defines options for recognition.
        operationContext:
          description: The value to identify context of the operation.
          type: string
    PlayOptions:
      required:
      - loop
      type: object
      properties:
        loop:
          description: The option to play the provided audio source in loop when set to true
          type: boolean
    DtmfOptions:
      description: Options for DTMF recognition
      type: object
      properties:
        interToneTimeoutInSeconds:
          format: int32
          description: Time to wait between DTMF inputs to stop recognizing.
          maximum: 60
          minimum: 1
          type: integer
        maxTonesToCollect:
          format: int32
          description: Maximum number of DTMF tones to be collected.
          type: integer
        stopTones:
          description: List of tones that will stop recognizing.
          type: array
          items:
            $ref: '#/components/schemas/Tone'
    CallConnectionProperties:
      description: Properties of a call connection
      type: object
      properties:
        callConnectionId:
          description: The call connection id.
          type: string
        serverCallId:
          description: The server call id.
          type: string
        source:
          $ref: '#/components/schemas/CallSource'
          description: The source of the call, which is the caller.
        targets:
          description: The targets of the call.
          type: array
          items:
            $ref: '#/components/schemas/CommunicationIdentifierModel'
        callConnectionState:
          $ref: '#/components/schemas/CallConnectionStateModel'
        callbackUri:
          description: The callback URI.
          type: string
        mediaSubscriptionId:
          description: SubscriptionId for media streaming
          type: string
    CommunicationError:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        target:
          type: string
        details:
          type: array
          items:
            $ref: '#/components/schemas/CommunicationError'
        innererror:
          $ref: '#/components/schemas/CommunicationError'
    PhoneNumberIdentifierModel:
      required:
      - value
      type: object
      properties:
        value:
          type: string
    TransferCallResponse:
      description: The response payload for transferring the call.
      type: object
      properties:
        operationContext:
          description: The operation context provided by client.
          type: string
    PlaySourceType:
      description: Defines the type of the play source
      enum:
      - file
      type: string
      x-ms-enum:
        name: PlaySourceType
        modelAsString: true
    CommunicationErrorResponse:
      description: The Communication Services error response
      required:
      - error
      type: object
      properties:
        error:
          $ref: '#/components/schemas/CommunicationError'
    GetParticipantsResponse:
      description: The response payload for getting participants of the call.
      type: object
      properties:
        values:
          description: List of the current participants in the call.
          type: array
          items:
            $ref: '#/components/schemas/AcsCallParticipant'
        nextLink:
          description: Continue of the list of participants
          type: string
  parameters:
    ApiVersionParameter:
      name: api-version
      in: query
      description: Version of API to invoke.
      required: true
      x-ms-parameter-location: method
      schema:
        type: string
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - name: endpoint
    description: The endpoint of the Azure Communication resource.
    required: true
    type: string
    format: url
    in: path
    x-ms-skip-url-encoding: true
    x-ms-parameter-location: client