Azure Communication Services Rooms API

openapi: 3.0.3
info:
  title: Azure Communication Room Service
  description: Azure Communication Room Service
  version: '2025-03-13'
servers:
- url: '{endpoint}'
  variables:
    endpoint:
      default: https://{resource}.communication.azure.com
      description: The endpoint of the Azure Communication resource.
paths:
  /rooms:
    post:
      tags:
      - Rooms
      summary: Creates a new room.
      operationId: Rooms_Create
      x-ms-examples:
        Create a new meeting room.:
          $ref: ./examples/Rooms_Create.json
      requestBody:
        required: true
        description: The create room request body.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRoomRequest'
      parameters:
      - $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, globally unique for all time, identifier for the request. It is recommended to use version 4 (random) UUIDs.
        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.
        schema:
          type: string
          format: date-time-rfc1123
      responses:
        '201':
          description: Request successful. The action returns a new room.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoomModel'
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunicationErrorResponse'
          headers:
            x-ms-error-code:
              description: ''
              schema:
                type: string
    get:
      tags:
      - Rooms
      summary: Retrieves all created rooms.
      operationId: Rooms_List
      x-ms-examples:
        List all rooms.:
          $ref: ./examples/Rooms_List.json
      x-ms-pageable:
        nextLinkName: nextLink
        itemName: value
      parameters:
      - $ref: '#/components/parameters/ApiVersionParameter'
      responses:
        '200':
          description: Request successful. The action returns a collection of rooms.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoomsCollection'
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunicationErrorResponse'
          headers:
            x-ms-error-code:
              description: ''
              schema:
                type: string
  /rooms/{roomId}:
    get:
      tags:
      - Rooms
      summary: Retrieves an existing room by id.
      operationId: Rooms_Get
      x-ms-examples:
        Get meeting room.:
          $ref: ./examples/Rooms_Get.json
      parameters:
      - name: roomId
        in: path
        description: The id of the room requested.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/ApiVersionParameter'
      responses:
        '200':
          description: Request successful. The action returns a room.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoomModel'
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunicationErrorResponse'
          headers:
            x-ms-error-code:
              description: ''
              schema:
                type: string
    patch:
      tags:
      - Rooms
      summary: Update a room with given changes.
      operationId: Rooms_Update
      x-ms-examples:
        Update meeting room's properties.:
          $ref: ./examples/Rooms_Update.json
      requestBody:
        required: true
        description: The update room request.
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/UpdateRoomRequest'
      parameters:
      - name: roomId
        in: path
        description: The id of the room requested.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/ApiVersionParameter'
      responses:
        '200':
          description: Request successful. The action returns an updated room.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoomModel'
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunicationErrorResponse'
          headers:
            x-ms-error-code:
              description: ''
              schema:
                type: string
    delete:
      tags:
      - Rooms
      summary: Delete a room.
      operationId: Rooms_Delete
      x-ms-examples:
        Delete a meeting room.:
          $ref: ./examples/Rooms_Delete.json
      parameters:
      - name: roomId
        in: path
        description: The id of the room to be deleted.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/ApiVersionParameter'
      responses:
        '204':
          description: The room was successfully deleted.
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunicationErrorResponse'
          headers:
            x-ms-error-code:
              description: ''
              schema:
                type: string
  /rooms/{roomId}/participants:
    get:
      tags:
      - Participants
      summary: Get participants in a room.
      operationId: Participants_List
      x-ms-examples:
        Get participants:
          $ref: ./examples/Participants_List.json
      x-ms-pageable:
        nextLinkName: nextLink
        itemName: value
      parameters:
      - name: roomId
        in: path
        description: The id of the room to get participants from.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/ApiVersionParameter'
      responses:
        '200':
          description: Request successful. The action returns the participants of the room.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParticipantsCollection'
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunicationErrorResponse'
          headers:
            x-ms-error-code:
              description: ''
              schema:
                type: string
    patch:
      tags:
      - Participants
      summary: Update participants in a room.
      operationId: Participants_Update
      x-ms-examples:
        Update participants:
          $ref: ./examples/Participants_Update.json
      requestBody:
        required: true
        description: An updated set of participants of the room.
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/UpdateParticipantsRequest'
      parameters:
      - name: roomId
        in: path
        description: The id of the room to update the participants in.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/ApiVersionParameter'
      responses:
        '200':
          description: The participants were successfully updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateParticipantsResult'
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunicationErrorResponse'
          headers:
            x-ms-error-code:
              description: ''
              schema:
                type: string
components:
  schemas:
    CommunicationError:
      $ref: ../../../Common/stable/2023-11-15/common.json#/components/schemas/CommunicationError
    CommunicationErrorResponse:
      $ref: ../../../Common/stable/2023-11-15/common.json#/components/schemas/CommunicationErrorResponse
    CreateRoomRequest:
      description: Request payload for creating new room.
      type: object
      properties:
        validFrom:
          format: date-time
          description: 'The timestamp from when the room is open for joining. The timestamp is in RFC3339 format: `yyyy-MM-ddTHH:mm:ssZ`. The default value is the current date time.'
          type: string
          example: '2021-09-07T07:55:41Z'
        validUntil:
          format: date-time
          description: 'The timestamp from when the room can no longer be joined. The timestamp is in RFC3339 format: `yyyy-MM-ddTHH:mm:ssZ`. The default value is the current date time plus 180 days.'
          type: string
          example: '2021-09-08T15:55:41Z'
        pstnDialOutEnabled:
          description: Set this flag to true if, at the time of the call, dial out to a PSTN number is enabled in a particular room. By default, this flag is set to false.
          type: boolean
          example: true
        participants:
          description: (Optional) Participants to be invited to the room.
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ParticipantProperties'
          example:
            rawId1:
              role: Presenter
            rawId2:
              role: Attendee
            rawId3:
              role: Collaborator
            rawId4: null
    ParticipantProperties:
      required:
      - role
      type: object
      properties:
        role:
          $ref: '#/components/schemas/Role'
    ParticipantsCollection:
      description: A collection of participants in a room.
      required:
      - value
      type: object
      properties:
        value:
          description: A collection of participants.
          type: array
          items:
            $ref: '#/components/schemas/RoomParticipant'
        nextLink:
          description: If there are more participants that can be retrieved, the next link will be populated.
          type: string
    Role:
      description: The role of a room participant. The default value is Attendee.
      enum:
      - Presenter
      - Attendee
      - Consumer
      - Collaborator
      type: string
      x-ms-enum:
        name: Role
        modelAsString: true
    RoomModel:
      description: The meeting room.
      type: object
      required:
      - createdAt
      - id
      - validFrom
      - validUntil
      - pstnDialOutEnabled
      properties:
        id:
          description: Unique identifier of a room. This id is server generated.
          type: string
          example: '99199690362660524'
        createdAt:
          format: date-time
          description: 'The timestamp when the room was created at the server. The timestamp is in RFC3339 format: `yyyy-MM-ddTHH:mm:ssZ`.'
          type: string
          example: '2021-09-06T05:55:41Z'
        validFrom:
          format: date-time
          description: 'The timestamp from when the room is open for joining. The timestamp is in RFC3339 format: `yyyy-MM-ddTHH:mm:ssZ`.'
          type: string
          example: '2021-09-07T07:55:41Z'
        validUntil:
          format: date-time
          description: 'The timestamp from when the room can no longer be joined. The timestamp is in RFC3339 format: `yyyy-MM-ddTHH:mm:ssZ`.'
          type: string
          example: '2021-09-08T15:55:41Z'
        pstnDialOutEnabled:
          description: Set this flag to true if, at the time of the call, dial out to a PSTN number is enabled in a particular room. By default, this flag is set to false.
          type: boolean
          example: true
    RoomParticipant:
      description: A participant of the room.
      required:
      - rawId
      - role
      type: object
      properties:
        rawId:
          description: Raw ID representation of the communication identifier. Please refer to the following document for additional information on Raw ID. <br> https://learn.microsoft.com/azure/communication-services/concepts/identifiers?pivots=programming-language-rest#raw-id-representation
          type: string
        role:
          $ref: '#/components/schemas/Role'
    RoomsCollection:
      description: A collection of rooms.
      required:
      - value
      type: object
      properties:
        value:
          description: A collection of rooms.
          type: array
          items:
            $ref: '#/components/schemas/RoomModel'
        nextLink:
          description: If there are more rooms that can be retrieved, the next link will be populated.
          type: string
    UpdateParticipantsRequest:
      description: Participants to be updated in the room.
      type: object
      properties:
        participants:
          description: Participants to be updated.
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ParticipantProperties'
          example:
            rawId1:
              role: Presenter
            rawId2:
              role: Attendee
            rawId3:
              role: Collaborator
            rawId4: null
    UpdateParticipantsResult:
      description: Request response for updating participants.
      type: object
    UpdateRoomRequest:
      description: Request payload for updating a room.
      type: object
      properties:
        validFrom:
          format: date-time
          description: '(Optional) The timestamp from when the room is open for joining. The timestamp is in RFC3339 format: `yyyy-MM-ddTHH:mm:ssZ`.'
          type: string
          example: '2021-09-07T07:55:41Z'
        validUntil:
          format: date-time
          description: '(Optional) The timestamp from when the room can no longer be joined. The timestamp is in RFC3339 format: `yyyy-MM-ddTHH:mm:ssZ`.'
          type: string
          example: '2021-09-08T15:55:41Z'
        pstnDialOutEnabled:
          description: (Optional) Set this flag to true if, at the time of the call, dial out to a PSTN number is enabled in a particular room. By default, this flag is set to false.
          type: boolean
          example: true
  parameters:
    ApiVersionParameter:
      name: api-version
      in: query
      description: Version of API to invoke.
      required: true
      schema:
        type: string
      x-ms-parameter-location: method
    Endpoint:
      name: endpoint
      in: path
      description: The endpoint of the Azure Communication resource.
      required: true
      schema:
        type: string
        format: url
      x-ms-skip-url-encoding: true
      x-ms-parameter-location: client
  securitySchemes:
    Authorization:
      type: apiKey
      name: Authorization
      in: header
      description: An authentication string containing a signature generated using HMAC-SHA256 scheme.
security:
- Authorization: []
x-converted-from:
  format: swagger 2.0
  source: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/specification/communication/data-plane/Rooms/stable/2025-03-13/communicationservicesrooms.json
  tool: apievangelist s2o.py (structural conversion, no content added)