UI Library use cases
Use components and composites in the Azure Communication Services UI Library to create call and chat experiences in your applications.
In a composite, call and chat capabilities are built in directly and exposed when you integrate the composite into an application. In a UI component, call and chat capabilities are exposed through a combination of UI functionality and underlying stateful libraries. To take full advantage of these capabilities, we recommend that you use UI components with stateful call and chat client libraries.
Get more conceptual documentation, quickstarts, and examples in the UI Library storybook.
Call use cases
| Area | Use cases |
|---|---|
| Call types | Join a Microsoft Teams meeting |
| Join an Azure Communication Services call by using a group ID | |
| Join an Azure Communication Services Room | |
| Start an outbound call to another Azure Communication Services user | |
| Start an outbound call to a phone number | |
| Teams interoperability | Join the call lobby |
| Display a transcription and recording alert banner | |
| Call controls | Mute and unmute a call |
| Turn video on and off during a call | |
| Turn on screen sharing | |
| End a call | |
| Participant gallery | Show remote participants on a grid |
| Make video preview available throughout a call for a local user | |
| Make default avatars available when video is off | |
| Show shared screen content in the participant gallery | |
| Call configuration | Manage the microphone device |
| Manage the camera device | |
| Manage the speaker device | |
| Make local preview available for user to check video | |
| Participants | Show a participant roster |
Chat use cases
| Area | Azure Communication Services Chat | Teams Interoperability Chat |
|---|---|---|
| Chat types | Join an Azure Communication Services chat thread | Join a Microsoft Teams meeting chat |
| Chat actions | Send and receive text messages | Send and receive text messages |
| Receive rich text messages | Receive rich text messages | |
| - | Receive inline images* | |
| Send and receive file attachments | Receive file attachments* | |
| Chat events | Send and receive typing indicators | Send and receive typing indicators** |
| Send and receive read receipts | Send and receive read receipts | |
| Show when a participant is added or removed | Show when a participant is added or removed | |
| Participants | Show a participant roster | Show a participant roster |
*Inline image and file attachment support are currently in public 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.
**The display name of typing event from the Teams user might not be shown properly.
Supported identities
To initialize a composite, and authenticate to the service, a user must have an Azure Communication Services identity. For more information, see Authenticate to Azure Communication Services and Quickstart: Create and manage access tokens.
Teams interoperability
For Teams interoperability scenarios, you can use UI Library composites to add a user to a Teams meeting via Communication Services. To enable Teams interoperability, use either the default features in the call composite or the chat composite, or use UI components to build a custom experience.
When you add both calling and chat to an application, it's important to remember that the chat client can't be initialized until the participant is admitted to the call. After the participant is admitted, the chat client can be initialized to join the meeting chat thread. The pattern is demonstrated in the following figure:
If you use UI components to deliver Teams interoperability experiences, begin by using UI Library examples to create key pieces of the experience:
- Lobby example. A sample lobby where a participant can wait to be admitted to a call.
- Compliance banner. A sample banner that shows the user if the call is being recorded.
- Teams theme. A sample theme that makes UI Library elements look like Microsoft Teams.
- Image sharing*. A sample of Azure Communication Service end user can receive images sent by the Teams user.
- File sharing*. A sample of Azure Communication Service end user can receive file attachments sent by the Teams user.
Customization
Use UI Library patterns to modify components to match the look and feel of your application. Customization is a key difference between composites and UI components in Communication Services. Composites have fewer customization options for a simpler integration experience.
The following table compares composites and UI components for customization use cases:
| Use case | Composites | UI components |
|---|---|---|
| Use Fluent-based theming | X | X |
| Compose the experience layout | X | |
| Use CSS styling to modify style properties | X | |
| Replace icons | X | |
| Modify the participant gallery layout | X | |
| Modify the call control layout | X | X |
| Inject data models to modify user metadata | X | X |
Observability
The state management architecture of UI Library is decoupled, so you can access stateful call and chat clients directly. You can hook into the stateful client to read the state, handle events, and override behavior to pass onto the UI components.
The following table compares composites and UI components for observability use cases:
| Use case | Composites | UI components |
|---|---|---|
| Access call and chat client state | X | X |
| Access and handle client events | X | X |
| Access and handle UI events | X | X |
Recommended architecture
Initialize a composite and base component by using an Azure Communication Services access token. It's important to get access tokens from Communication Services through a trusted service that you manage. For more information, see Quickstart: Create and manage access tokens and the trusted service tutorial.
Call and chat client libraries must have the context for the call or chat they join. Like user access tokens, disseminate the context to clients by using your own trusted service.
The following table summarizes initialization and resource management functions that are required to add context to a client library:
| Contoso responsibilities | UI Library responsibilities |
|---|---|
| Provide an access token from Azure | Pass through the provided access token to initialize components |
| Provide a refresh function | Refresh the access token by using a developer-provided function |
| Retrieve and pass join information for the call or chat | Pass through call and chat information to initialize components |
| Retrieve and pass user information for any custom data model | Pass through a custom data model to components to render |
Platform support
| SDK | Windows | macOS | Ubuntu | Linux | Android | iOS |
|---|---|---|---|---|---|---|
| UI SDK | Chrome*, Microsoft Edge | Chrome*, Safari** | Chrome* | Chrome* | Chrome* | Safari** |
* The current version of Chrome and the two preceding releases are supported.
** Safari version 13.1 and later versions are supported. Outgoing video for Safari macOS isn't yet supported, but it's supported for iOS. Outgoing screen sharing is supported only on desktop iOS.
Accessibility
Accessibility by design is a principle across Microsoft products. UI Library follows this principle, and all UI components are fully accessible.
Localization
Localization is key to making products for users around the world and who speak different languages. UI Library provides default support for some languages and capabilities, including right-to-left languages. You can provide their own localization files to use with UI Library.
Use the CallComposite and the ChatComposite in the Azure Communication Services UI Library to create call experiences in your iOS and Android applications. By using a couple lines of code, you can easily integrate an entire call and chat experience in your application. Composites in Communication Services manage the entire lifecycle of the call and chat, from setup until the call and chat end.
Calling use cases
You can use the call composite in Communication Services to create these use cases:
| Area | Use cases |
|---|---|
| Call types | Join a Microsoft Teams meeting |
| Join a call by using a group ID | |
| Teams interoperability | Join the call lobby |
| Display a transcription and recording alert banner | |
| Participant gallery | Show remote participants on a grid |
| Make video preview available throughout a call for a local user | |
| Make default avatars available when video is off | |
| Show shared screen content in the participant gallery | |
| Enable participant avatar customization | |
| Show a participant roster | |
| Call configuration | Manage the microphone device |
| Manage the camera device | |
| Manage the speaker device (wired or Bluetooth) | |
| Make local preview available for a user to check video | |
| Call controls | Mute and unmute a call |
| Turn video on or off during a call | |
| End a call | |
| Hold and resume a call after audio interruption |
Teams interoperability
For Teams interoperability scenarios, you can use UI Library composites to add a user to a Teams meeting via Communication Services. To enable Teams interoperability, use the call composite. The composite manages the entire lifecycle of joining a Teams interoperability call.
The following figure shows an example of the user experience before a caller is added to a Teams meeting:
View shared content
Through the UI Library for mobile native platforms, call participants can view shared content when other participants share their screens during a Teams call. A remote participant can use stretch and pinch gestures to zoom in or out on the shared content in the call.
Theming
You can use the UI Library call composite for iOS and Android to create a custom theme of a caller's experience. To create the platform experience, pass a set of theming colors as shown in the following table. For more information, see How to create your theme.
| Android | iOS |
|---|---|
|
|
Screen size
You can adapt the Azure Communication Services call composite to adapt to screen sizes from 5 inches to tablet size. Use split mode and tablet mode in the call composite to get the dynamic participants' roster layout, provide clarity on the view, and focus on the conversation.
| Split mode | Tablet mode |
|---|---|
|
|
Localization
Localization is key to making products for users around the world and who speak different languages. UI Library supports 12 languages: English, Spanish, French, German, Italian, Japanese, Korean, Dutch, Portuguese, Russian, Turkish, and Chinese. It also supports right-to-left languages. For more information, see How to add localization to your app.
Accessibility
Accessibility is a key focus of the call libraries. You can use a screen reader to make important announcements about call status and to help ensure that visually impaired users can effectively participate when they use the application.
View data injection
Use the UI Library for mobile native platforms to give local and remote participants the option to customize how they appear as users in a call. A local participant can choose a local avatar, custom display name, navigation's title and subtitle on Setup screen when a call begins. A remote user can create a customized avatar when they join the meeting. For more information, see How to customize pre-meeting view.
Skip Setup Screen
UI Library provides the capability to join a call skipping the setup screen of the call join experience. By default, user goes through a setup screen to join a call. Here, user sets the call configuration such as camera turn on or off, microphone turn on or off and audio device selection before joining a call. This screen requires user interaction to join a call, which might be unnecessary for some users. So we provide the capability to join a call by skipping the setup screen and providing the call configuration APIs. For more information, see How to use Skip Setup Screen Feature
Orientation
UI Library supports screen orientation setup for each of the screen separately prior to launch the library experience. This allows application developers to set up a fixed orientation for the calling experience which would align their application orientation. To learn more about the list of supported orientation for both Android and iOS platform and usage of the API, see How to use Orientation Feature
Chat use cases
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.
| Area | Use cases |
|---|---|
| Chat types | Join an Azure Communication Services chat thread |
| Chat actions | Send a chat message |
| Receive a chat message | |
| Chat events | Show typing indicators |
| Show a read receipt | |
| Show when a participant is added or removed | |
| Show changes to the chat title |
Flexibility
The ChatComposite was designed to fit into different layouts and views in your application. For example, you could choose to place Chat in a navigation view, modal view or some other view. The ChatComposite would adjust itself and ensure the user has a seamless experience.
| In Navigation View | In Modal View |
|---|---|
|
|
Supported identities
To initialize a composite, and authenticate to the service, a user must have an Azure Communication Services identity. For more information, see Authenticate to Azure Communication Services and Quickstart: Create and manage access tokens.
Recommended architecture
Initialize a composite by using an Azure Communication Services access token. It's important to get access tokens from Azure Communication Services through a trusted service that you manage. For more information, see Quickstart: Create and manage access tokens and the trusted service tutorial.
Call and chat client libraries must have the context for the call they join. Like user access tokens, disseminate the context to clients by using your own trusted service. The following table summarizes the initialization and resource management functions that are required to add context to a client library:
| Contoso responsibilities | UI Library responsibilities |
|---|---|
| Provide an access token from Azure | Pass through the provided access token to initialize components |
| Provide a refresh function | Refresh the access token by using a developer-provided function |
| Retrieve and pass join information for the call or chat | Pass through call and chat information to initialize components |
| Retrieve and pass user information for any custom data model | Pass through a custom data model to components to render |
Platform support
| Platform | Versions |
|---|---|
| iOS | iOS 14 and later |
| Android | API 21 and later |
Troubleshooting guide
When troubleshooting happens for voice or video calls, you may be asked to provide a CallID; this ID is used to identify Communication Services calls.
This CallID can be retrieved via the action bar on the bottom of the call screen; you see an ellipsis button; once the user performs the tap action an option of "Share diagnostics info"; the user can share the diagnostics info that's required to track any issues by the support team.
For programmatic access to CallID, see "How to get debug information programmatically".
You can learn more about troubleshooting guidelines here: "Troubleshooting in Azure Communication Services" page.
| Calling screen | Diagnostic info menu | Share CallID |
|---|---|---|
|
|
|
Feedback
Submit and view feedback for