Merge pull request #206995 from radubulboaca/master

Update rooms concept doc for public preview

Author: v-ccolin

articles/communication-services/concepts/media/rooms/decision-tree.png

@@ -2,82 +2,142 @@
 title: Azure Communication Services Rooms overview
 titleSuffix: An Azure Communication Services concept document
 description: Learn about the Azure Communication Services Rooms.
-author: nmurav
-manager: antval
+author: farrukhghaffar
+manager: nmurav
 services: azure-communication-services
 
-ms.author: nmurav
-ms.date: 11/24/2021
+ms.author: FAGHAFFA
+ms.date: 07/24/2022
 ms.topic: conceptual
 ms.service: azure-communication-services
 ---
-
 # Rooms overview
 
-[!INCLUDE [Private Preview Disclaimer](../../includes/private-preview-include-section.md)]
-
-Azure Communication services provide a concept of rooms for developers who are building structured conversations. Rooms support only voice and video calling in Private Preview.
-Here are main scenarios where Rooms are useful:
+[!INCLUDE [Public Preview Notice](../../includes/public-preview-include.md)]
 
-- **Service-managed communication.** Rooms help service platforms deliver meeting-style experiences while still being suitably generic for a wide variety of industry applications. Services can create and manage rooms for patients seeking medical advice, financial planners working with clients, and lawyers providing legal services. 
-- **Ability to have Invite-only experiences.** Rooms allow your services to control which users can join the rooms. Board members can discuss sensitive topics confidentially.
+Azure Communication Services provides a concept of a room for developers who are building structured conversations such as virtual appointments or virtual events. Rooms currently allow voice and video calling.
 
+Here are the main scenarios where rooms are useful:
 
-## When to use Rooms
-Not every solution needs a Room. Some scenarios, like building basic one-to-one or one-to-few ad-hoc interactions, can be created using the Calling or Chat SDKs without the need for rooms.
+- **Rooms enable scheduled communication experience.** Rooms help service platforms deliver meeting-style experiences while still being suitably generic for a wide variety of industry applications. Services can schedule and manage rooms for patients seeking medical advice, financial planners working with clients, and lawyers providing legal services. 
+- **Rooms enable an invite-only experience.** Rooms allow your services to control which users can join the room for a virtual appointment with doctors or financial consultants. Developers can use the "Join Policy" for a room, to either let all or only a subset of users with assigned Communication Services identities to join a room call.
+- **Rooms enable structured communications through roles and permissions.** Rooms allow developers to assign predefined roles to users to exercise a higher degree of control and structure in communication. Ensure only presenters can speak and share content in a large meeting or in a virtual conference.
 
-Use rooms when you need:
-- Control who can access a calling session on server side
-- Need coordinates that can be expired at a specific moment of time
-- Have a call to which only invited users can join
+## When to use rooms
 
- :::image type="content" source="../media/rooms/decision-tree.png" alt-text="Diagram showing decision tree to select a Room.":::
+Use rooms when you need any of the following capabilities:
+- Control which users can join room calls.
+- Need scheduling/coordinates that are enabled and expire at a specified time and date.
+- Need structured communication through roles and permissions for users. 
 
-Note while you can use either group CallID or rooms if you just need an ephemeral coordinate. We recommend using rooms API for all new solutions you are building.
+ :::image type="content" source="../media/rooms/room-decision-tree.png" alt-text="Diagram showing decision tree to select a Room.":::
 
-| Capability  | 1:N Call | 1:N Call <br>with ephemeral ID</br> |  Room call | 
+| Capability | 1:N Call | 1:N Call <br>with ephemeral ID</br> |  Room call | 
 | ------ | :------: | :------: | :------: |
-| Interactive participants  | 350 | 350 | 350 |
-| Ephemeral ID to distribute to participants  | No  | Yes (Group ID) | Yes (Room ID) |
-| Invitee only participation   | No  | No | Yes <br>(Mandatory in private preview)</br> |
-| API to create. remove, update, delete the call   | No  | No | Rooms API |
-| Set validity period for a call   | No  | No | Yes <br> Up to six months </br> |
-
+| Interactive participants | 350 | 350 | 350 |
+| Ephemeral ID to distribute to participants | ❌ | ✔️ <br>(Group ID)</br> | ✔️ <br>(Room ID)</br> |
+| Invitee only participation   | ❌ | ❌ | ✔️ |
+| All users in communication service resource to join a call   | ❌ | ✔️ | ✔️ |
+| Set validity period for a call   | ❌ | ❌ | ✔️ <br> Up to six months </br> |
+| Set user roles and permissions for a call   | ❌ | ❌ | ✔️ |
+| API to create, remove, update, delete the call   | ❌ | ❌ | ✔️ <br> Rooms API <br> |
 
-## Managing the Rooms
 
-Rooms are managed via Rooms SDK or Rooms API. In the initial release, the rooms allows only have voice and video calls within the Room. 
-
-Use the **Rooms API/SDK** in your server application for Room:
-- Creation 
-- Modification
-- Deletion
-- Defining and updating the set of participants
-- Setting and modifying the Room validity (up to six months).
-
-Use the  **JS Calling SDKs** (with other Calling SDKs and chat support on the roadmap) to join the room. 
+## Managing rooms and joining room calls
 
+ **Rooms API/SDK** is used to accomplish actions such as creating a room, adding participants, and setting up schedule etc. Calling SDK is used to initiate the call within a Room from the client side. Most actions available in a one-to-one or group-calls in **Calling SDKs** are also available in room calls. Full list of capabilities offered in Calling SDK is listed in the [Calling SDK Overview](../voice-video-calling/calling-sdk-features.md#detailed-capabilities).
+ 
+| Capability                                   | Calling SDK | Rooms API/SDK |
+|----------------------------------------------|--------|--------|
+| Join a room call with voice and video        | ✔️ | ❌ |
+| List participants that joined the rooms call | ✔️ | ❌ | 
+| Create room                                  | ❌ | ✔️ |
+| List all participants that are invited to the room | ❌ | ✔️ |
+| Add or remove a VoIP participant             |  ❌ | ✔️ |
+| Assign roles to room participants            |  ❌ | ✔️ |
 
 The picture below illustrates the concept of managing and joining the rooms.
 
- :::image type="content" source="../media/rooms/rooms-management.png" alt-text="Diagram showing Rooms Management.":::
+:::image type="content" source="../media/rooms/rooms-management.png" alt-text="Diagram showing Rooms Management.":::
 
- ## Runtime operations
- 
- Most actions available in regular one-to-one or group calls in JS Calling SDK are also available in rooms. You cannot promote the existing one-to-one or group call to a room call or Invite an ad hoc user to join a Room (you need to add the user using the Rooms API)
-Full list of capabilities that are available in JS SDK are listed in the [Calling SDK Overview](../voice-video-calling/calling-sdk-features.md#detailed-capabilities).
-
-| Capability | JS Calling SDK | Rooms API/SDK |
-|----------------------------------------------| :--------: | :---------: |
-| Join a Room call with voice and video | ✔️ | ❌ |
-| List participants that joined the Rooms call | ✔️ | ❌ |
-| List all participants that are invited to the Room call | ❌ | ✔️ |
-| Add or remove a VoIP participant  | ❌ | ✔️ |
-| Add or remove a new PSTN participant  | ❌ | ❌ |
+### Rooms API/SDKs
+
+Rooms are created and managed via rooms APIs or SDKs. Use the rooms API/SDKs in your server application for `room` operations:
+- Create  
+- Modify
+- Delete
+- Set and update the list of participants
+- Set and modify the Room validity
+- Control who gets to join a room, using `roomJoinPolicy`. Details below.
+- Assign roles and permissions to users. Details below.
+
+### Calling SDKs
+
+Use the [Calling SDKs](../voice-video-calling/calling-sdk-features.md) to join the room call. Room calls can be joined using the Web, iOS or Android Calling SDKs. You can find quick start samples for joining room calls [here](../../quickstarts/rooms/join-rooms-call.md).
+
+## Control access to room calls
+
+Rooms can be set to operate in two levels of control over who is allowed to join a room call. 
+
+| Room type | roomJoinPolicy value | Who can participate in Room?
+|-------------------------------------| --------------------------------- | ------------------------------------------------------------------------------ | 
+| **Private Room** | `inviteOnly` | User must be explicitly added to the room roster, to be able to join a room |
+| **Open Room** | `communicationServiceUsers` | All valid users created under company's Azure Communication Service resource are allowed to join this room | 
+
+## Predefined participant roles and permissions
+
+Room participants can be assigned one of the following roles: **Presenter**, **Attendee** and **Consumer**. By default, a user is assigned an **Attendee** role, if no other role is assigned. 
+
+The tables below provide detailed capabilities mapped to the roles. At a high level, **Presenter** role has full control, **Attendee** capabilities are limited to audio and video, while **Consumer** can only receive audio, video and screen sharing.
+
+| Capability | Role: Presenter | Role: Attendee | Role: Consumer
+|---------------------------------------------| :--------: | :--------: | :--------: |
+| **Mid call controls** | | |
+| - Turn video on/off | ✔️ | ✔️ | ❌ |
+| - Mute/Unmute mic | ✔️ | ✔️ | ❌ |
+| - Switch between cameras | ✔️ | ✔️ | ❌ |
+| - Active speaker | ✔️ | ✔️ | ✔️ |
+| - Choose speaker for calls | ✔️ | ✔️ | ✔️ |
+| - Choose mic for calls | ✔️ | ✔️ | ❌ |
+| - Show participants state (idle, connecting, connected, On-hold, Disconnecting, Disconnected etc.) | ✔️ | ✔️ | ✔️ |
+| - Show call state (Early media, Incoming, Connecting, Ringing, Connected, Hold, Disconnecting, Disconnected | ✔️ | ✔️ | ✔️ |
+| - Show if a participant is muted | ✔️ | ✔️ | ✔️ |
+| - Show the reason why a participant left a call | ✔️ | ✔️ | ✔️ |
+| **Screen sharing** | | |
+| - Share screen | ✔️ *  | ❌ | ❌ |
+| - Share an application | ✔️ * | ❌ | ❌ |
+| - Share a browser tab | ✔️ * | ❌ | ❌ |
+| - Participants can view shared screen | ✔️ | ✔️ | ✔️ |
+| **Roster management** | | |
+| - Remove a participant | ✔️ | ❌ | ❌ |
+| **Device management** | | |
+| - Ask for permission to use audio and/or video | ✔️ | ✔️ | ❌ |
+| - Get camera list | ✔️ | ✔️ | ❌ |
+| - Set camera | ✔️ | ✔️ | ❌ |
+| - Get selected camera | ✔️ | ✔️ | ❌ |
+| - Get mic list | ✔️ * | ✔️ * | ❌ |
+| - Set mic | ✔️ * | ✔️ * | ❌ |
+| - Get selected mic | ✔️ * | ✔️ * | ❌ |
+| - Get speakers list | ✔️ * | ✔️ * | ✔️ * |
+| - Set speaker | ✔️ * | ✔️ * | ✔️ * |
+| - Get selected speaker | ✔️ | ✔️ | ✔️ |
+| **Video rendering** | | |
+| - Render a video in multiple places (local camera or remote stream) | ✔️ | ✔️ | ✔️ <br>(Only Remote)</br> |
+| - Set/Update video scaling mode | ✔️ | ✔️ | ✔️ <br>(Only Remote)</br> |
+| - Render remote video stream | ✔️ | ✔️ | ✔️ |
+
+*) Only available on the web calling SDK. Not available on iOS and Android calling SDKs
+
+## Event handling
+
+[Voice and video calling events](../../../event-grid/communication-services-voice-video-events.md) published via [Event Grid](../../../event-grid/event-schema-communication-services.md) are annotated with room call information. 
+
+- **CallStarted** is published when a room call starts.
+- **CallEnded** is published when a room call ends.
+- **CallParticipantAdded** is published when a new participant joins a room call.
+- **CallParticipantRemoved** is published when a participant drops from a room call.
 
 ## Next steps:
--	Use the [QuickStart to create, manage and join a room.](../../quickstarts/rooms/get-started-rooms.md)
--	Review the [Network requirements for media and signaling](../voice-video-calling/network-requirements.md)
-
-
-
+- Use the [QuickStart to create, manage and join a room](../../quickstarts/rooms/get-started-rooms.md).
+- Learn how to [join a room call](../../quickstarts/rooms/join-rooms-call.md).
+- Review the [Network requirements for media and signaling](../voice-video-calling/network-requirements.md).

articles/communication-services/concepts/media/rooms/room-decision-tree.png

@@ -209,6 +209,10 @@ items:
         href: concepts/detailed-call-flows.md
       - name: Known issues
         href: concepts/known-issues.md
+  - name: Rooms
+    items:
+      - name: Rooms overview
+        href: concepts/rooms/room-concept.md
   - name: UI Library
     items:
       - name: UI Library overview