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:

Diagram that shows the Teams interoperability pattern for calling and chat.

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

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.

Diagram that shows the recommended UI Library architecture.

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.

Diagram that shows the Teams interoperability pattern for call and chat.

The following figure shows an example of the user experience before a caller is added to a Teams meeting:

Screenshot that shows 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
Screenshot that shows Android theming for a caller experience. Screenshot that shows iOS theming for a caller experience.

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
Screenshot that demonstrates a split-screen view. Screenshot that demonstrates 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.

GIF animation that shows the pre-meeting experience and joining experience on iOS.

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

Audio Only Mode

The Audio Only Mode in the UI Library allows participants to join calls using only their audio, without sharing or receiving video. This feature is used to conserve bandwidth and maximize privacy. When activated, the Audio Only Mode automatically disables the video functionalities for both sending and receiving streams, and adjusts the UI to reflect this change by removing video-related controls. This mode can be enabled through the CallComposite configuration, more information available through the Audio Only Quick Start

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

Multitasking and Picture-in-Picture

UI Library supports picture in picture mode for call screen. While being in the call, user can click back button on call screen to enable multitasking which will take user back to previous screen. If Picture-in-Picture is enabled, a system Picture-in-Picture will be displayed for call. To learn more about the multitasking and Picture-in-Picture for both Android and iOS platform and usage of the API, see How to use Picture-in-Picture

CallKit support

UI Library supports CallKit Integration to handle interaction with CallKit for calls. To learn more about the integration for iOS platform and usage of the API, see How to use CallKit

One-to-one call and PUSH notification support

UI Library supports one-to-one VoIP call to dial users by communication identifier. To receive incoming call UI Library also supports registering for PUSH notifications. To learn more about the integration for Android and iOS platform and usage of the API, see How to make one-to-one call and receive PUSH notifications

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
an image that shows the chat experience on iOS in a navigation view. an image that shows the chat experience on iOS in a 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.

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.

Diagram that shows the recommended architecture for UI Library.

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
Screenshot of the call screen during the call. Screenshot of the call screen with the diagnostic options location. Screenshot of showing share Call ID with Contoso.