Merge pull request #217684 from ashwinder/ci-qs

pricing and troubleshooting updates

Author: JamesJBarnett

articles/communication-services/concepts/media/troubleshooting/correlation-id-in-callback-event.png

@@ -10,7 +10,7 @@ ms.service: azure-communication-services
 ---
 # Pricing Scenarios
 
-Prices for Azure Communication Services are generally based on a pay-as-you-go model. The prices in the following examples are for illustrative purposes and may not reflect the latest Azure pricing.
+Prices for Azure Communication Services are based on a pay-as-you-go model. The prices in the following examples are for illustrative purposes and may not reflect the latest Azure pricing.
 
 ## Voice/Video calling and screen sharing
 
@@ -83,7 +83,7 @@ Alice is a Dynamics 365 contact center agent, who makes an outbound call from Om
 
 - One participant on the VoIP leg (Alice) from Omnichannel for Customer Service client application x 10 minutes x $0.004 per participant leg per minute = $0.04
 - One participant on the Communication Services direct routing outbound leg (Bob) from Communication Services servers to an SBC x 10 minutes x $0.004 per participant leg per minute = $0.04.
-- Omnichannel for Customer Servicebot does not introduce additional ACS charges.
+- Omnichannel for Customer Service bot does not introduce additional ACS charges.
 
 **Total cost for the call**: $0.04 + $0.04 = $0.08
 
@@ -101,7 +101,24 @@ Alice and Bob are on a VOIP Call. Bob escalated the call to Charlie on Charlie's
 
 Note: USA mixed rates to `+1-425` is $0.013. Refer to the following link for details: https://github.com/Azure/Communication/blob/master/pricing/communication-services-pstn-rates.csv)
 
-**Total cost for the VoIP + escalation call**: $0.16 + $0.13 = $.29
+**Total cost for the VoIP + escalation call**: $0.16 + $0.13 = $0.29
+
+### Pricing example: Group call managed by Call Automation SDK
+
+Asha calls your US toll-free number (acquired from Communication Services) from her mobile. Your service application answers the call using Call Automation SDK and plays out an IVR menu using Play and Recognize actions. Your application then adds a human agent, David, to the call who answers the call through a custom application using Calling SDK. 
+
+- Asha was on the call as a PSTN endpoint for a total of 10 minutes.
+- Your application was on the call for the entire 10 minutes of the call. 
+- David was on the call for the last 5 minutes of the call using Calling JS SDK. 
+
+**Cost calculations**
+
+- Inbound PSTN leg by Asha to toll-free number acquired from Communication Services x 10 minutes x $0.0220 per minute for receiving the call = $0.22
+- One participant on the VOIP leg (David) x 5 minutes x $0.004 per participant leg per minute = $0.02
+
+Note that the service application that uses Call Automation SDK isn't charged to be part of the call. The additional monthly cost of leasing a US toll-free number isn't included in this calculation.
+
+**Total cost for the call**: $0.22 + $0.02 = $0.24
 
 ## Call Recording
 
@@ -147,7 +164,7 @@ Bob starts a call with his financial advisor, Charlie.
 
 ## Chat
 
-With Communication Services you can enhance your application with the ability to send and receive chat messages between two or more users. Chat SDKs are available for JavaScript, .NET, Python, and Java. Refer to [this page to learn about SDKs](./sdk-options.md)
+With Communication Services, you can enhance your application with the ability to send and receive chat messages between two or more users. Chat SDKs are available for JavaScript, .NET, Python, and Java. Refer to [this page to learn about SDKs](./sdk-options.md)
 
 ### Price
 
@@ -177,7 +194,7 @@ Azure Communication Services allows for adding SMS messaging capabilities to you
 
 ### Pricing
 
-The SMS usage price is a per-message segment charge based on the destination of the message. The carrier surcharge is calculated based on the destination of the message for sent messages and based on the sender of the message for received messages. Please refer to the [SMS Pricing Page](./sms-pricing.md) for pricing details. 
+The SMS usage price is a per-message segment charge based on the destination of the message. The carrier surcharge is calculated based on the destination of the message for sent messages and based on the sender of the message for received messages. Refer to the [SMS Pricing Page](./sms-pricing.md) for pricing details. 
 
 ### Pricing example: 1:1 SMS sending
 
@@ -198,18 +215,18 @@ Contoso is a healthcare company with clinics in US and Canada. Contoso has a Pat
 Contoso is a healthcare company with clinics in US and Canada. Contoso has a Patient Appointment Reminder application that sends out SMS appointment reminders to patients regarding upcoming appointments. Patients can respond to the messages with "Reschedule" and include their date/time preference to reschedule their appointments.
 
 - The application sends appointment reminders to 20 US patients and 30 Canada patients using a CA toll-free number.
-- 6 US patients and 4 CA patients respond back to reschedule their appointments. Contoso receives 10 SMS responses in total.
-- Message length of the reschedule messages is less than 1 message segment*. Hence, total messages received are 6 message segments for US and 4 message segments for CA.
+- Six US patients and four CA patients respond back to reschedule their appointments. Contoso receives 10 SMS responses in total.
+- Message length of the reschedule messages is less than one message segment*. Hence, total messages received are six message segments for US and four message segments for CA.
 
 **Cost calculations**
 
-- US - 6 message segments x $0.0075 per received message segment + 6 message segments x $0.0010 carrier surcharge per received message segment = $0.051
-- CA - 4 message segments x $0.0075 per received message segment = $0.03
+- US - six message segments x $0.0075 per received message segment + 6 message segments x $0.0010 carrier surcharge per received message segment = $0.051
+- CA - four message segments x $0.0075 per received message segment = $0.03
 
 **Total cost for receiving patient responses from 6 US patients and 4 CA patients**: $0.051 + $0.03 = $0.081
 
 ## Telephony
-Please refer to the following links for details on Telephony pricing
+Refer to the following links for details on Telephony pricing
 
 - [PSTN Pricing Details](./pstn-pricing.md)
 

articles/communication-services/concepts/media/troubleshooting/response-header.png

@@ -18,16 +18,18 @@ Inbound PSTN calling is currently supported in GA for Dynamics Omnichannel. You
 
 **Inbound calling with Dynamics 365 Omnichannel (OC)**
 
-Supported in General Availability, to set up inbound calling for Dynamics 365 OC with direct routing or Voice Calling (PSTN) follow [these instructions](/dynamics365/customer-service/voice-channel-inbound-calling)
-
-**Inbound calling with Power Virtual Agents**
-
-*Coming soon*
+Supported in General Availability, to set up inbound calling for Dynamics 365 OC with direct routing or Voice Calling (PSTN) follow [these instructions](/dynamics365/customer-service/voice-channel-inbound-calling).
 
 **Inbound calling with ACS Call Automation SDK**
 
-[Available in private preview](../call-automation/call-automation.md)
+Call Automation enables you to build custom calling workflows within your applications to optimize business processes and boost customer satisfaction. The library supports managing incoming calls to the phone numbers acquired from Communication Services and incoming calls via Direct Routing. You can also use Call Automation to place outbound calls from the phone numbers owned by your resource, among other capabilities.   
+
+Learn more about [Call Automation](../voice-video-calling/call-automation.md), currently available in public preview.
 
 **Inbound calling with Azure Bot Framework**
 
-Customers participating in Azure Bot Framework Telephony Channel preview can find the [instructions here](/azure/bot-service/bot-service-channel-connect-telephony)
+Customers participating in Azure Bot Framework Telephony Channel preview can find the [instructions here](/azure/bot-service/bot-service-channel-connect-telephony)
+
+**Inbound calling with Power Virtual Agents**
+
+*Coming soon*

articles/communication-services/concepts/pricing.md

@@ -35,7 +35,7 @@ Communication Services offers two types of phone numbers: **local** and **toll-f
 Local (Geographic) numbers are 10-digit telephone numbers consisting of the local area codes in the United States. For example, `+1 (206) XXX-XXXX` is a local number with an area code of `206`. This area code is assigned to the city of Seattle. These phone numbers are generally used by individuals and local businesses. Azure Communication Services offers local numbers in the United States. These numbers can be used to place phone calls, but not to send SMS messages.
 
 ### Toll-free Numbers
-Toll-free numbers are 10-digit telephone numbers with distinct area codes that can be called from any phone number free of charge. For example, `+1 (800) XXX-XXXX` is a toll-free number in the North America region. These phone numbers are generally used for customer service purposes. Azure Communication Services offers toll-free numbers in the United states. These numbers can be used to place phone calls and to send SMS messages. Toll-free numbers cannot be used by people and can only be assigned to applications.
+Toll-free numbers are 10-digit telephone numbers with distinct area codes that can be called from any phone number free of charge. For example, `+1 (800) XXX-XXXX` is a toll-free number in the North America region. These phone numbers are generally used for customer service purposes. Azure Communication Services offers toll-free numbers in the United states. These numbers can be used to place phone calls and to send SMS messages. Toll-free numbers can't be used by people and can only be assigned to applications.
 
 #### Choosing a phone number type
 
@@ -73,20 +73,22 @@ The following table shows you where you can acquire different types of phone num
 | Toll-Free | US                 | US                                                   | US                                                    |US                | US |
 
 *Currently, you can receive calls only to a Microsoft number that is assigned to a Telephony Channel bot. Read more about Telephony Channel [here](/azure/bot-service/bot-service-channel-connect-telephony)
-**For more details about call destinations and pricing, refer to the [pricing page](../pricing.md).
+**For more information about call destinations and pricing, see the [pricing page](../pricing.md).
 
 
 ## Next steps
 
 ### Quickstarts
 
 - [Get a phone Number](../../quickstarts/telephony/get-phone-number.md)
+- [Manage inbound and outbound calls](../../quickstarts/voice-video-calling/callflows-for-customer-interactions.md) with Call Automation.
 - [Place a call](../../quickstarts/voice-video-calling/getting-started-with-calling.md)
 - [Send an SMS](../../quickstarts/sms/send.md)
 
 ### Conceptual documentation
 
 - [Voice and video concepts](../voice-video-calling/about-call-types.md)
 - [Telephony concepts](./telephony-concept.md)
+- [Call Automation concepts](../voice-video-calling/call-automation.md)
 - [Call Flows](../call-flows.md)
 - [Pricing](../pricing.md)

articles/communication-services/concepts/telephony/inbound-calling-capabilities.md

@@ -25,6 +25,7 @@ To help you troubleshoot certain types of issues, you may be asked for any of th
 * **Call ID**: This ID is used to identify Communication Services calls.
 * **SMS message ID**: This ID is used to identify SMS messages.
 * **Short Code Program Brief ID**: This ID is used to identify a short code program brief application.
+* **Correlation ID**: This ID is used to identify requests made using Call Automation. 
 * **Call logs**: These logs contain detailed information that can be used to troubleshoot calling and network issues.
 
 Also take a look at our [service limits](service-limits.md) documentation for more information on throttling and limitations.
@@ -75,26 +76,16 @@ chat_client = ChatClient(
 ```
 ---
 
-## Access your server call ID
-When troubleshooting issues with the Call Automation SDK, like call recording and call management problems, you'll need to collect the Server Call ID. This ID can be collected using the ```getServerCallId``` method.
+## Access IDs required for Call Automation
+When troubleshooting issues with the Call Automation SDK, like call management or recording problems, you'll need to collect the IDs that help identify the failing call or operation. You can provide either of the two IDs mentioned here. 
+- From the header of API response, locate the field `X-Ms-Skype-Chain-Id`.
+ 
+    ![Screenshot of response header showing X-Ms-Skype-Chain-Id.](media/troubleshooting/response-header.png) 
+- From the callback events your application receives after executing an action e.g. `CallConnected` or `PlayFailed`, locate the correlationID.
 
-#### JavaScript
-```
-callAgent.on('callsUpdated', (e: { added: Call[]; removed: Call[] }): void => {
-    e.added.forEach((addedCall) => {
-        addedCall.on('stateChanged', (): void => {
-            if (addedCall.state === 'Connected') {
-                addedCall.info.getServerCallId().then(result => {
-                    dispatch(setServerCallId(result));
-                }).catch(err => {
-                    console.log(err);
-                });
-            }
-        });
-    });
-});
-```
+    ![Screenshot of call disconnected event showing correlation ID.](media/troubleshooting/correlation-id-in-callback-event.png)
 
+In addition to one of these IDs, please provide the details on the failing use case and the timestamp for when the failure was observed. 
 
 ## Access your client call ID
 
@@ -325,6 +316,27 @@ The Azure Communication Services Calling SDK uses the following error codes to h
 | 500, 503, 504 | Communication Services infrastructure error. | File a support request through the Azure portal. |
 | 603 | Call globally declined by remote Communication Services participant | Expected behavior. |
 
+## Call Automation SDK error codes 
+The below error codes are exposed by Call Automation SDK.
+
+| Error Code | Description | Actions to take |
+|--|--|--|
+| 400 | Bad request           | The input request is invalid. Look at the error message to determine which input is incorrect.
+| 401 | Unauthorized          | HMAC authentication failed. Verify whether the connection string used to create CallAutomationClient is correct.
+| 403 | Forbidden             | Request is forbidden. Make sure that you can have access to the resource you are trying to access. 
+| 404 | Resource not found    | The call you are trying to act on doesn't exist. For example, transferring a call that has already disconnected.
+| 429 | Too many requests     | Retry after a delay suggested in the Retry-After header, then exponentially backoff.
+| 500 | Internal server error | Retry after a delay. If it persists, raise a support ticket.
+| 502 | Bad gateway           | Retry after a delay with a fresh http client.
+
+Consider the below tips when troubleshooting certain issues. 
+- Your application is not getting IncomingCall Event Grid event: Make sure the application endpoint has been [validated with Event Grid](../../event-grid/webhook-event-delivery.md) at the time of creating event subscription. The provisioning status for your event subscription will be marked as succeeded if the validation was successful. 
+- Getting the error 'The field CallbackUri is invalid': Call Automation does not support HTTP endpoints. Make sure the callback url you provide supports HTTPS.
+- PlayAudio action does not play anything: Currently only Wave file (.wav) format is supported for audio files. The audio content in the wave file must be mono (single-channel), 16-bit samples with a 16,000 (16KHz) sampling rate.
+- Actions on PSTN endpoints aren't working: CreateCall, Transfer, AddParticipant and Redirect to phone numbers require you to set the  SourceCallerId in the action request. Unless you are using Direct Routing, the source caller ID should be a phone number owned by your Communication Services resource for the action to succeed. 
+
+Refer to [this article](./known-issues.md) to learn about any known issues being tracked by the product team. 
+
 ## Chat SDK error codes
 
 The Azure Communication Services Chat SDK uses the following error codes to help you troubleshoot chat issues. The error codes are exposed through the `error.code` property in the error response.