Rooms overview
Important
This feature of Azure Communication Services is currently in preview.
Preview APIs and SDKs are provided without a service-level agreement. We recommend that you don't use them for production workloads. Some features might not be supported, or they might have constrained capabilities.
For more information, review Supplemental Terms of Use for Microsoft Azure Previews.
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:
- 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.
When to use rooms
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.
| Capability | 1:N Call | 1:N Call with ephemeral ID |
Room call |
|---|---|---|---|
| Interactive participants | 350 | 350 | 350 |
| Ephemeral ID to distribute to participants | ❌ | ✔️ (Group ID) |
✔️ (Room ID) |
| Invitee only participation | ❌ | ❌ | ✔️ |
| All users in communication service resource to join a call | ❌ | ✔️ | ✔️ |
| Set validity period for a call | ❌ | ❌ | ✔️ Up to six months |
| Set user roles and permissions for a call | ❌ | ❌ | ✔️ |
| API to create, remove, update, delete the call | ❌ | ❌ | ✔️ Rooms API |
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.
| 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.
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 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.
Rooms can also be accessed using the Azure Communication Services UI Library. The UI Library enables developers to add a call client that is Rooms enabled into their application with only a couple lines of code.
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) | ✔️ | ✔️ | ✔️ (Only Remote) |
| - Set/Update video scaling mode | ✔️ | ✔️ | ✔️ (Only Remote) |
| - 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 published via Event Grid 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.
- Learn how to join a room call.
- Review the Network requirements for media and signaling.
Feedback
Submit and view feedback for