Merge pull request #283553 from MicrosoftDocs/main

Publish to live, Sunday 4:00PM PDT, 08/04

Author: Stacyrch140

articles/azure-monitor/app/azure-ad-authentication.md

@@ -67,7 +67,7 @@ The following Software Development Kits (SDKs) and features are unsupported for
 Application Insights .NET SDK supports the credential classes provided by [Azure Identity](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/identity/Azure.Identity#credential-classes).
 
 - We recommend `DefaultAzureCredential` for local development.
-- Ensure you're authenticated on Visual Studio with the expected Azure user account. For more information, see [Authenticate via Visual Studio](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/identity/Azure.Identity#authenticate-via-visual-studio).
+- Authenticate on Visual Studio with the expected Azure user account. For more information, see [Authenticate via Visual Studio](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/identity/Azure.Identity#authenticate-via-visual-studio).
 - We recommend `ManagedIdentityCredential` for system-assigned and user-assigned managed identities.
   - For system-assigned, use the default constructor without parameters.
   - For user-assigned, provide the client ID to the constructor.
@@ -126,7 +126,7 @@ useAzureMonitor(options);
 > [!NOTE]
 > Support for Microsoft Entra ID in the Application Insights Node.JS is included starting with [version 2.1.0-beta.1](https://www.npmjs.com/package/applicationinsights/v/2.1.0-beta.1).
 
-If using applicationinsights npm package.
+If using `applicationinsights` npm package.
 ```typescript
 const appInsights = require("applicationinsights");
 const { DefaultAzureCredential } = require("@azure/identity");
@@ -139,7 +139,7 @@ appInsights.defaultClient.config.aadTokenCredential = credential;
 
 #### Environment variable configuration
 
-When using [Azure App Services autoinstrumentation](./azure-web-apps-nodejs.md) The `APPLICATIONINSIGHTS_AUTHENTICATION_STRING` environment variable lets Application Insights authenticate to Microsoft Entra ID and send telemetry.
+Use the `APPLICATIONINSIGHTS_AUTHENTICATION_STRING` environment variable to let Application Insights authenticate to Microsoft Entra ID and send telemetry when using [Azure App Services autoinstrumentation](./azure-web-apps-nodejs.md).
 
 - For system-assigned identity:
 
@@ -233,52 +233,9 @@ After setting it, restart your application. It now sends telemetry to Applicatio
 
 ### [Python](#tab/python)
 
-> [!NOTE]
-> Microsoft Entra authentication is only available for Python v2.7, v3.6, and v3.7. Support for Microsoft Entra ID in the Application Insights OpenCensus Python SDK
-is included starting with beta version [opencensus-ext-azure 1.1b0](https://pypi.org/project/opencensus-ext-azure/1.1b0/).
-
-> [!NOTE]
-> [OpenCensus Python SDK is deprecated](https://opentelemetry.io/blog/2023/sunsetting-opencensus/), but Microsoft supports it until retirement on September 30, 2024. We now recommend the [OpenTelemetry-based Python offering](./opentelemetry-enable.md?tabs=python) and provide [migration guidance](./opentelemetry-python-opencensus-migrate.md?tabs=aspnetcore).
-
-Construct the appropriate [credentials](/python/api/overview/azure/identity-readme#credentials) and pass them into the constructor of the Azure Monitor exporter. Make sure your connection string is set up with the instrumentation key and ingestion endpoint of your resource.
-
-The `OpenCensus` Azure Monitor exporters support these authentication types. We recommend using managed identities in production environments.
-
-#### System-assigned managed identity
-
-```python
-from azure.identity import ManagedIdentityCredential
-
-from opencensus.ext.azure.trace_exporter import AzureExporter
-from opencensus.trace.samplers import ProbabilitySampler
-from opencensus.trace.tracer import Tracer
+To configure a secure connection to Azure using OpenTelemetry, see [Enable Microsoft Entra ID (formerly Azure AD) authentication](./opentelemetry-configuration.md?tabs=python#enable-microsoft-entra-id-formerly-azure-ad-authentication).
 
-credential = ManagedIdentityCredential()
-tracer = Tracer(
-    exporter=AzureExporter(credential=credential, connection_string="InstrumentationKey=<your-instrumentation-key>;IngestionEndpoint=<your-ingestion-endpoint>"),
-    sampler=ProbabilitySampler(1.0)
-)
-...
-
-```
-
-#### User-assigned managed identity
-
-```python
-from azure.identity import ManagedIdentityCredential
-
-from opencensus.ext.azure.trace_exporter import AzureExporter
-from opencensus.trace.samplers import ProbabilitySampler
-from opencensus.trace.tracer import Tracer
-
-credential = ManagedIdentityCredential(client_id="<client-id>")
-tracer = Tracer(
-    exporter=AzureExporter(credential=credential, connection_string="InstrumentationKey=<your-instrumentation-key>;IngestionEndpoint=<your-ingestion-endpoint>"),
-    sampler=ProbabilitySampler(1.0)
-)
-...
-
-```
+To configure using OpenCensus (deprecated), see [Configure and enable Microsoft Entra ID-based authentication](/previous-versions/azure/azure-monitor/app/opencensus-python#configure-and-enable-microsoft-entra-id-based-authentication).
 
 ---
 
@@ -629,7 +586,7 @@ The main OAuth2 flow supported is through [authorization codes](/azure/active-di
     &resource=https://api.applicationinsights.io
 ```
 
-When a request is made to the authorized URL, the client\_id is the application ID from your Microsoft Entra app, copied from the app's properties menu. The redirect\_uri is the homepage/login URL from the same Microsoft Entra app. When a request is successful, this endpoint redirects you to the sign-in page you provided at sign-up with the authorization code appended to the URL. See the following example:
+When a request is made to the authorized URL, the `client\_id` is the application ID from your Microsoft Entra app, copied from the app's properties menu. The `redirect\_uri` is the `homepage/login` URL from the same Microsoft Entra app. When a request is successful, this endpoint redirects you to the sign-in page you provided at sign-up with the authorization code appended to the URL. See the following example:
 
 ```http
     http://<app-client-id>/?code=AUTHORIZATION_CODE&session_state=STATE_GUID
@@ -907,7 +864,7 @@ If the SDK fails to get a token, the exception message is logged as
 
 ### [Node.js](#tab/nodejs)
 
-Internal logs could be turned on by using the following setup. After they're enabled, error logs will be shown in the console, including any error related to Microsoft Entra integration. Examples include failure to generate the token when the wrong credentials are supplied or errors when the ingestion endpoint fails to authenticate by using the provided credentials.
+Turn on internal logs by using the following setup. After you enable them, the console shows error logs, including any error related to Microsoft Entra integration. Examples include failing to generate the token with the wrong credentials or errors when the ingestion endpoint fails to authenticate using the provided credentials.
 
 ```javascript
 let appInsights = require("applicationinsights");

articles/communication-services/concepts/call-automation/media/transcription.png

@@ -0,0 +1,43 @@
+---
+title: Generate real-time transcripts
+titleSuffix: An Azure Communication Services concept document
+description: Provides an overview of what real-time transcription is
+author: kunaal
+ms.service: azure-communication-services
+ms.subservice: call-automation
+ms.topic: include
+ms.date: 07/16/2024
+ms.author: kpunjabi
+services: azure-communication-services
+---
+
+# Generating real-time transcripts
+[!INCLUDE [Public Preview Disclaimer](../../includes/public-preview-include-document.md)]
+
+Real-time transcriptions are a crucial component in any major business for driving improved customer service experience. Powered by Azure Communication Services and Azure AI Services integration, developers can now use real-time transcriptions through Call Automation SDKs. 
+
+Using the Azure Communication Services real-time transcription, you can easily integrate your Azure AI Services resource with Azure Communication Services to generate transcripts directly during the call. This eliminates the need for developers to extract audio content and deal with the overhead of converting audio into text on your side. You can store the contents of this transcript to use later on for creating a history of the call, summarizing the call to save an agent's time, and even feeding it into your training/learning modules to help improve your contact center agents' customer interactions.
+
+Out of the box Microsoft utilizes a Universal Language Model as a base model that is trained with Microsoft-owned data and reflects commonly used spoken language. This model is pretrained with dialects and phonetics representing various common domains. For more information about supported languages, see [Languages and voice support for the Speech service](../../../../articles/ai-services/speech-service/language-support.md).
+
+## Common use cases
+
+### Improved customer experience
+Assist agents better understand customer needs and respond more quickly and accurately, leading to a better overall customer experience.
+
+### Increased efficency 
+Help agents focus on the conversation rather than note-taking, allowing them to handle more calls and improve productivity
+
+### Context for agents
+Provide context to an agent before the agent picks up the call, this way the agent knows the information that the caller has provided avoiding any need for the caller to repeat their issue.
+
+### Derive insights
+Using the transcript generated throughout the call, you can leverage other AI tools to gain live, real-time insights that will help agents and supervisors improve their interactions with customers.
+
+## Sample flow of real-time transcription using Call Automation
+![Diagram of real-time transcription flow.](./media/transcription.png)
+
+## Next Steps
+- Check out our how-to guide to learn [how-to use our Real-time Transcription](../../how-tos/call-automation/real-time-transcription-tutorial.md) to users.
+- Learn about [usage and operational logs](../analytics/logs/call-automation-logs.md) published by call automation.
+

articles/communication-services/concepts/call-automation/real-time-transcription.md

@@ -6,7 +6,7 @@ author: kunaal
 ms.topic: how-to
 ms.service: azure-communication-services
 ms.subservice: call-automation
-ms.date: 11/16/2023
+ms.date: 07/16/2024
 ms.author: kpunjabi
 ms.custom: public_preview
 services: azure-communication-services
@@ -356,3 +356,134 @@ if event.type == "Microsoft.Communication.ContinuousDtmfRecognitionStopped":
     app.logger.info("Tone stoped: context=%s", event.data["operationContext"])
 ```
 -----
+
+### Hold
+The hold action allows developers to temporarily pause a conversation between a participant and a system or agent. This can be useful in scenarios where the participant needs to be transferred to another agent or department or when the agent needs to consult a supervisor in the background before continuing the conversation. During this time you can choose to play audio to the participant that is on hold. 
+
+### [csharp](#tab/csharp)
+```csharp
+// Option 1: Hold without additional options
+await callAutomationClient.GetCallConnection(callConnectionId)
+    .GetCallMedia().HoldAsync(c2Target);
+
+/*
+// Option 2: Hold with play source
+PlaySource playSource = /* initialize playSource */;
+await callAutomationClient.GetCallConnection(callConnectionId)
+    .GetCallMedia().HoldAsync(c2Target, playSource);
+
+// Option 3: Hold with options
+var holdOptions = new HoldOptions(target) 
+{ 
+    OperationCallbackUri = new Uri(""),
+    OperationContext = "holdcontext"
+};
+await callMedia.HoldAsync(holdOptions);
+*/
+```
+
+### [java](#tab/java)
+```java
+// Option 1: Hold with options
+PlaySource playSource = /* initialize playSource */;
+HoldOptions holdOptions = new HoldOptions(target)
+    .setOperationCallbackUrl(appConfig.getBasecallbackuri())
+    .setPlaySource(playSource)
+    .setOperationContext("holdPstnParticipant");
+
+client.getCallConnection(callConnectionId).getCallMedia().holdWithResponse(holdOptions, Context.NONE);
+
+/*
+// Option 2: Hold without additional options
+client.getCallConnection(callConnectionId).getCallMedia().hold(target);
+*/
+```
+
+### [JavaScript](#tab/javascript)
+```javascript
+// Option 1: Hold with options
+const options = {
+    playSource: playSource,
+    operationContext: "holdUserContext",
+    operationCallbackUrl: "URL" // replace with actual callback URL
+};
+await callMedia.hold(targetuser, options);
+
+/*
+// Option 2: Hold without additional options
+await callMedia.hold(targetuser);
+*/
+```
+
+### [Python](#tab/python)
+```python
+# Option 1: Hold without additional options
+call_connection_client.hold(target_participant=PhoneNumberIdentifier(TARGET_PHONE_NUMBER))
+
+'''
+# Option 2: Hold with options
+call_connection_client.hold(
+    target_participant=PhoneNumberIdentifier(TARGET_PHONE_NUMBER),
+    play_source=play_source,
+    operation_context="holdUserContext",
+    operation_callback_url="URL" # replace with actual callback URL
+)
+'''
+```
+-----
+### Unhold
+The unhold action allows developers to resume a conversation between a participant and a system or agent that was previously paused. When the participant is taken off hold they will be able to hear the system or agent again. 
+
+### [csharp](#tab/csharp)
+``` csharp
+var unHoldOptions = new UnholdOptions(target) 
+{ 
+    OperationContext = "UnHoldPstnParticipant" 
+}; 
+
+// Option 1
+var UnHoldParticipant = await callMedia.UnholdAsync(unHoldOptions);
+
+/* 
+// Option 2
+var UnHoldParticipant = await callMedia.UnholdAsync(target);
+*/
+```
+
+### [java](#tab/java)
+``` java
+// Option 1
+client.getCallConnection(callConnectionId).getCallMedia().unholdWithResponse(target, "unholdPstnParticipant", Context.NONE);
+
+/* 
+// Option 2
+client.getCallConnection(callConnectionId).getCallMedia().unhold(target);
+*/
+```
+
+### [JavaScript](#tab/javascript)
+```javascript
+const unholdOptions = { 
+    operationContext: "unholdUserContext" 
+}; 
+
+// Option 1
+await callMedia.unhold(target);
+
+/* 
+// Option 2
+await callMedia.unhold(target, unholdOptions);
+*/
+```
+
+### [Python](#tab/python)
+```python
+# Option 1
+call_connection_client.unhold(target_participant=PhoneNumberIdentifier(TARGET_PHONE_NUMBER)) 
+
+'''
+# Option 2
+call_connection_client.unhold(target_participant=PhoneNumberIdentifier(TARGET_PHONE_NUMBER), operation_context="holdUserContext") 
+'''
+```
+-----

articles/communication-services/how-tos/call-automation/control-mid-call-media-actions.md

@@ -124,6 +124,45 @@ await callAutomationClient.getCallConnection(callConnectionId)
     .playToAll([ playSource ]);
 ```
 
+### Support for barge-in
+During scenarios where you're playing audio on loop to all participants e.g. waiting lobby you maybe playing audio to the participants in the lobby and keep them updated on their number in the queue. When you use the barge-in support, this will cancel the on-going audio and play your new message. Then if you wanted to continue playing your original audio you would make another play request.
+
+```javascript
+// Interrupt media with text source 
+//Option1:
+
+const playSource: TextSource = { text: "Interrupt prompt", voiceName: "en-US-NancyNeural", kind: "textSource" };
+
+const interruptOption: PlayToAllOptions = { 
+loop: false, 
+interruptCallMediaOperation: true, 
+operationContext: "interruptOperationContext", 
+operationCallbackUrl: process.env.CALLBACK_URI + "/api/callbacks" 
+}; 
+
+await callConnectionMedia.playToAll([playSource], interruptOption); 
+
+/*
+// Interrupt media with file source 
+
+Option2: 
+
+const playSource: FileSource = { 
+url: MEDIA_URI + "MainMenu.wav", 
+kind: "fileSource" 
+}; 
+
+const interruptOption: PlayToAllOptions = { 
+loop: false, 
+interruptCallMediaOperation: true, 
+operationContext: "interruptOperationContext", 
+operationCallbackUrl: process.env.CALLBACK_URI + "/api/callbacks" 
+}; 
+
+await callConnectionMedia.playToAll([playSource], interruptOption); 
+*/
+```
+
 ## Play audio - Specific participant
 
 In this scenario, audio is played to a specific participant.
@@ -155,7 +194,7 @@ If you're playing the same audio file multiple times, your application can provi
 const playSource: FileSource = { url: audioUri, playsourcacheid: "<playSourceId>", kind: "fileSource" }; 
 await callAutomationClient.getCallConnection(callConnectionId) 
 .getCallMedia() 
-.play([ playSource ], [ targetParticipant ]); 
+.play([ playSource ], [ targetParticipant ]);
 ```
 
 ## Handle play action event updates 
@@ -177,6 +216,12 @@ if (event.type === "Microsoft.Communication.PlayFailed") {
     console.log("Play failed: data=%s", JSON.stringify(eventData)); 
 } 
 ```
+### Example of how you can deserialize the *PlayStarted* event:
+```javascript
+if (event.type === "Microsoft.Communication.PlayStarted") { 
+    console.log("Play started: data=%s", JSON.stringify(eventData)); 
+} 
+```
 
 To learn more about other supported events, visit the [Call Automation overview document](../../../concepts/call-automation/call-automation.md#call-automation-webhook-events).