Merge pull request #210719 from rzdor/main

Documentation for Raise Hand

Author: v-dirichards

articles/communication-services/how-tos/calling-sdk/includes/raise-hand/raise-hand-web.md

@@ -0,0 +1,85 @@
+---
+author: ruslanzdor
+ms.service: azure-communication-services
+ms.topic: include
+ms.date: 09/08/2022
+ms.author: rifox
+---
+[!INCLUDE [Install SDK](../install-sdk/install-sdk-web.md)]
+
+> [!NOTE]
+> Raise Hand API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. To use this api please use 'beta' release of Azure Communication Services Calling Web SDK
+
+Raise Hand is an extended feature of the core `Call` API. You first need to import calling Features from the Calling SDK:
+
+```js
+import { Features} from "@azure/communication-calling";
+```
+
+Then you can get the feature API object from the call instance:
+
+```js
+const raiseHandFeature = call.feature(Features.RaiseHand );
+```
+
+### Raise and lower hand for current participant:
+Raise Hand state can be used in any call type: on 1:1 calls and on calls with many participants, in ACS and in Teams calls.
+If it Teams meeting - organizer will have ability to enable or disable raise hand states for all participants.
+To change state for current participant, you can use methods:
+```js
+const raiseHandFeature = call.feature(Features.RaiseHand );
+//raise
+raiseHandFeature.raiseHand();
+//lower
+raiseHandFeature.lowerHand();
+```
+
+### Lower hands for other participants
+Currently ACS calls aren't allowed to change state of other participants, for example, lower all hands. But Teams calls allow it using these methods:
+```js
+const raiseHandFeature = call.feature(Features.RaiseHand );
+//lower all hands on the call
+raiseHandFeature.lowerHandForEveryone();
+//or we can provide array of CommunicationIdentifier to specify list of participants
+CommunicationUserIdentifier acsUser = new CommunicationUserIdentifier(<USER_ID>);
+MicrosoftTeamsUserIdentifier teamsUser = new MicrosoftTeamsUserIdentifier(<USER_ID>)
+CommunicationIdentifier participants[] = new CommunicationIdentifier[]{ acsUser, teamsUser };
+raiseHandFeature.lowerHand(participants);
+```
+
+### Handle changed states
+The `Raise Hand` API allows you to subscribe to `raiseHandChanged` events. A `raiseHandChanged` event comes from a `call` instance and contain information about participant and new state.
+```js
+const raiseHandFeature = call.feature(Features.RaiseHand );
+
+// event : {identifier: CommunicationIdentifier, isRaised: true, order:1}
+const isRaiseHandChangedHandler = (event) => {
+    console.log(`Participant ${event.identifier} ${event.isRaised ? "Raised" : "Lower"} hand`);
+};
+raiseHandFeature.feature(SDK.Features.RaiseHand).on('raiseHandChanged', isRaiseHandChangedHandler):
+```
+
+### List of all participants with active state
+To get information about all participants that have Raise Hand state on current call, you can use this api array is sorted by order field:
+```js
+const raiseHandFeature = call.feature(Features.RaiseHand );
+let activeStates = raiseHandFeature.getStatus();
+```
+
+### Order of raised Hands
+It possible to get order of all raised hand states on the call, this order is started from 1.
+There are two ways: get all raise hand state on the call or use `raiseHandChanged` event subscription.
+In event subscription when any participant will lower a hand - call will generate only one event, but not for all participants with order above.
+
+```js
+const raiseHandFeature = call.feature(Features.RaiseHand );
+
+// event : {identifier: CommunicationIdentifier, isRaised: true, order:1}
+const isRaiseHandChangedHandler = (event) => {
+    console.log(`List of participants with raised hand`);
+    for (let state : raiseHandFeature.getStatus()) {
+        console.log(`Participant ${state.identifier} has order ${state.order}`);
+    }
+};
+raiseHandFeature.feature(SDK.Features.RaiseHand).on('raiseHandChanged', isRaiseHandChangedHandler):
+```

articles/communication-services/how-tos/calling-sdk/raise-hand.md

@@ -0,0 +1,35 @@
+---
+title: Raise hand states
+titleSuffix: An Azure Communication Services how-to guide
+description: Use Azure Communication Services SDKs to send raise hand state.
+author: rzdor
+ms.author: ruslanzdor
+ms.service: azure-communication-services
+ms.subservice: calling
+ms.topic: how-to 
+ms.date: 09/09/2022
+ms.custom: template-how-to
+
+#Customer intent: As a developer, I want to learn how to send and receive Raise Hand state using SDK.
+---
+
+# Raise hand states
+
+[!INCLUDE [Public Preview Disclaimer](../../includes/public-preview-include-document.md)]
+
+During an active call, you may want to send or receive states from other users. Let's learn how. 
+
+## Prerequisites
+
+- An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F). 
+- A deployed Communication Services resource. [Create a Communication Services resource](../../quickstarts/create-communication-resource.md).
+- A user access token to enable the calling client. For more information, see [Create and manage access tokens](../../quickstarts/access-tokens.md).
+- Optional: Complete the quickstart to [add voice calling to your application](../../quickstarts/voice-video-calling/getting-started-with-calling.md)
+
+[!INCLUDE [Raise Hand Client-side JavaScript](./includes/raise-hand/raise-hand-web.md)]
+
+## Next steps
+- [Learn how to manage calls](./manage-calls.md)
+- [Learn how to manage video](./manage-video.md)
+- [Learn how to record calls](./record-calls.md)
+- [Learn how to transcribe calls](./call-transcription.md)