Merge pull request #302993 from paulth1/comm-services-samples-tutorials

[AQ] edit pass: Comm services samples tutorials

Author: ShawnJackson

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

@@ -1,7 +1,7 @@
 ---
-title: Azure Communication Services Call Automation how-to for passing call contextual data in Call Automation 
+title: Azure Communication Services Call Automation How-to for Passing Call Contextual Data in Call Automation 
 titleSuffix: An Azure Communication Services how-to document
-description: Provides a how-to guide for passing contextual information with Call Automation.
+description: The article shows how to pass contextual information with Call Automation.
 author: jutik0
 ms.topic: how-to
 ms.service: azure-communication-services
@@ -12,38 +12,39 @@ manager: visho
 services: azure-communication-services
 ---
 
-# How to pass contextual data between calls
+# Pass contextual data between calls
 
-Call Automation allows developers to pass along custom contextual information when routing calls. Developers can pass metadata about the call, callee or any other information that is relevant to their application or business logic. This allows businesses to manage, and route calls across networks without having to worry about losing context.
+Call Automation allows developers to pass along custom contextual information when routing calls. Developers can pass metadata about the call, caller, or any other information that's relevant to their application or business logic. Businesses can then manage and route calls across networks without having to worry about losing context.
 
-Passing context is supported by specifying custom headers. These are an optional list of key-value pairs that can be included as part of `AddParticipant` or `Transfer` actions. The context can be later retrieved as part of the `IncomingCall` event payload.
+Passing context is supported by specifying custom headers. This optional list of key/value pairs is included as part of `AddParticipant` or `Transfer` actions. The context is retrieved later as part of the `IncomingCall` event payload.
 
-Custom call context is also forwarded to the SIP protocol, this includes both the freeform custom headers as well as the standard User-to-User Information (UUI) SIP header. When routing an inbound call from your telephony network, the data set from your SBC in the custom headers and UUI is similarly included in the `IncomingCall` event payload. 
+Custom call context is also forwarded to the Session Initiation Protocol (SIP), which includes both the freeform custom headers and the standard user-to-user information (UUI) SIP header. When an inbound call from your telephony network is routed, the data set from your Session Border Controller (SBC) in the custom headers and UUI is similarly included in the `IncomingCall` event payload.
 
-All custom context data is opaque to Call Automation or SIP protocols and its content is unrelated to any basic functions.
+All custom context data is opaque to Call Automation or SIP protocols, and its content is unrelated to any basic functions.
 
-Below are samples on how to get started using custom context headers in Call Automation. 
+The following samples show how to get started by using custom context headers in Call Automation.
 
-As a prerequisite, we recommend you to read these articles to make the most of this guide:
+## Prerequisites
 
-- Call Automation [concepts guide](../../concepts/call-automation/call-automation.md#call-actions) that describes the action-event programming model and event callbacks.
-- Learn about [user identifiers](../../concepts/identifiers.md#the-communicationidentifier-type) like CommunicationUserIdentifier and PhoneNumberIdentifier used in this guide.
+- Read the Call Automation [concepts article](../../concepts/call-automation/call-automation.md#call-actions) that describes the action-event programming model and event callbacks.
+- Learn about the [user identifiers](../../concepts/identifiers.md#the-communicationidentifier-type) like `CommunicationUserIdentifier` and PhoneNumberIdentifier` that are used in this article.
 
-For all the code samples, `client` is CallAutomationClient object that can be created as shown and `callConnection` is the CallConnection object obtained from Answer or CreateCall response. You can also obtain it from callback events received by your application.
+For all the code samples, `client` is the `CallAutomationClient` object that you can create, and `callConnection` is the `CallConnection` object that you obtain from an `Answer` or `CreateCall` response. You can also obtain it from callback events that your application receives.
 
 ## Technical parameters
-Call Automation supports up to 5 custom SIP headers and 1000 custom VOIP headers. Additionally, developers can include a dedicated User-To-User header as part of SIP headers list.
 
-The custom SIP header key must start with a mandatory ‘X-MS-Custom-’ prefix.  The maximum length of a SIP header key is 64 chars, including the X-MS-Custom prefix. The SIP header key may consist of alphanumeric characters and a few selected symbols which includes `.`, `!`, `%`, `*`, `_`, `+`, `~`, `-`. The maximum length of SIP header value is 256 chars. The same limitations apply when configuring the SIP headers on your SBC. The SIP header value may consist of alphanumeric characters and a few selected symbols which includes `=`, `;`, `.`, `!`, `%`, `*`, `_`, `+`, `~`, `-`.
+Call Automation supports up to five custom SIP headers and 1,000 custom voice-over-IP (VoIP) headers. Developers can include a dedicated user-to-user header as part of a SIP headers list.
 
-The maximum length of a VOIP header key is 64 chars. These headers can be sent without ‘x-MS-Custom’ prefix. The maximum length of VOIP header value is 1024 chars.
+The custom SIP header key must start with a mandatory `X-MS-Custom-` prefix. The maximum length of a SIP header key is 64 characters, including the `X-MS-Custom` prefix. The SIP header key consists of alphanumeric characters and a few selected symbols, which include `.`, `!`, `%`, `*`, `_`, `+`, `~`, and `-`. The maximum length of a SIP header value is 256 characters. The same limitations apply when you configure the SIP headers on your SBC. The SIP header value consists of alphanumeric characters and a few selected symbols, which include `=`, `;`, `.`, `!`, `%`, `*`, `_`, `+`, `~`, and `-`.
 
-## Adding custom context when inviting a participant
+The maximum length of a VoIP header key is 64 characters. These headers can be sent without the `x-MS-Custom` prefix. The maximum length of a VoIP header value is 1,024 characters.
 
-### [csharp](#tab/csharp)
+## Add custom context when you invite a participant
+
+### [C#](#tab/csharp)
 
 ```csharp
-// Invite a communication services user and include one VOIP header
+// Invite an Azure Communication Services user and include one VOIP header
 var addThisPerson = new CallInvite(new CommunicationUserIdentifier("<user_id>"));
 addThisPerson.CustomCallingContext.AddVoip("myHeader", "myValue");
 AddParticipantsResult result = await callConnection.AddParticipantAsync(addThisPerson);
@@ -60,7 +61,7 @@ AddParticipantsResult result = await callConnection.AddParticipantAsync(addThisP
 ```
 ### [Java](#tab/java)
 ```java
-// Invite a communication services user and include one VOIP header
+// Invite an Azure Communication Services user and include one VOIP header
 CallInvite callInvite = new CallInvite(new CommunicationUserIdentifier("<user_id>"));
 callInvite.getCustomCallingContext().addVoip("voipHeaderName", "voipHeaderValue");
 AddParticipantOptions addParticipantOptions = new AddParticipantOptions(callInvite);
@@ -77,7 +78,7 @@ Response<AddParticipantResult> addParticipantResultResponse = callConnectionAsyn
 
 ### [JavaScript](#tab/javascript)
 ```javascript
-// Invite a communication services user and include one VOIP header
+// Invite an Azure Communication Services user and include one VOIP header
 const customCallingContext: CustomCallingContext = [];
 customCallingContext.push({ kind: "voip", key: "voipHeaderName", value: "voipHeaderValue" })
 const addThisPerson = {
@@ -101,7 +102,7 @@ const addParticipantResult = await callConnection.addParticipant(addThisPerson);
 
 ### [Python](#tab/python)
 ```python
-#Invite a communication services user and include one VOIP header
+#Invite an Azure Communication Services user and include one VOIP header
 voip_headers = {"voipHeaderName", "voipHeaderValue"}
 target = CommunicationUserIdentifier("<acs_user_id>")
 result = call_connection_client.add_participant(
@@ -123,12 +124,12 @@ result = call_connection_client.add_participant(
 ```
 
 -----
-## Adding custom context during call transfer
+## Add a custom context during a call transfer
 
-### [csharp](#tab/csharp)
+### [C#](#tab/csharp)
 
 ```csharp
-//Transfer to communication services user and include one VOIP header
+//Transfer to an Azure Communication Services user and include one VOIP header
 var transferDestination = new CommunicationUserIdentifier("<user_id>"); 
 var transferOption = new TransferToParticipantOptions(transferDestination);   
 var transferOption = new TransferToParticipantOptions(transferDestination) {
@@ -148,7 +149,7 @@ TransferCallToParticipantResult result = await callConnection.TransferCallToPart
 
 ### [Java](#tab/java)
 ```java
-//Transfer to communication services user and include one VOIP header
+//Transfer to an Azure Communication Services user and include one VOIP header
 CommunicationIdentifier transferDestination = new CommunicationUserIdentifier("<user_id>");
 TransferCallToParticipantOptions options = new TransferCallToParticipantOptions(transferDestination);
 options.getCustomCallingContext().addVoip("voipHeaderName", "voipHeaderValue");
@@ -164,7 +165,7 @@ Response<TransferCallResult> transferResponse = callConnectionAsync.transferToPa
 
 ### [JavaScript](#tab/javascript)
 ```javascript
-//Transfer to communication services user and include one VOIP header
+//Transfer to an Azure Communication Services user and include one VOIP header
 const transferDestination = { communicationUserId: "<user_id>" };
 const transferee = { communicationUserId: "<transferee_user_id>" };
 const options = { transferee: transferee, operationContext: "<Your_context>", operationCallbackUrl: "<url_endpoint>" };
@@ -186,7 +187,7 @@ const result = await callConnection.transferCallToParticipant(transferDestinatio
 
 ### [Python](#tab/python)
 ```python
-#Transfer to communication services user and include one VOIP header
+#Transfer to an Azure Communication Services user and include one VOIP header
 transfer_destination = CommunicationUserIdentifier("<user_id>")
 transferee = CommunicationUserIdentifier("transferee_user_id")
 voip_headers = {"customVoipHeader1", "customVoipHeaderValue1"}
@@ -213,12 +214,12 @@ result = call_connection_client.transfer_call_to_participant(
 )
 ```
 
-Transfer of a VoIP call to a phone number is currently not supported.
+Currently, transfer of a VoIP call to a phone number isn't supported.
 
 -----
-## Reading custom context from an incoming call event
+## Read custom context from an incoming call event
 
-### [csharp](#tab/csharp)
+### [C#](#tab/csharp)
 
 ```csharp
 AcsIncomingCallEventData incomingEvent = <incoming call event from Event Grid>;
@@ -282,8 +283,7 @@ userToUser = sipHeaders["user-To-User"]
 ```
 
 -----
-## Additional resources
-
-- For a sample payload of the incoming call, refer to this [guide](../../../event-grid/communication-services-voice-video-events.md#microsoftcommunicationincomingcall).
+## Related content
 
+- For a sample payload of the incoming call, see [Azure Communication Services: Voice and video calling events](../../../event-grid/communication-services-voice-video-events.md#microsoftcommunicationincomingcall).
 - Learn more about [SIP protocol details for direct routing](../../concepts/telephony/direct-routing-sip-specification.md).