Merge pull request #242808 from jadacampbell/trial

adding trial phone numbers documentation

Author: Stacyrch140

articles/communication-services/concepts/telephony/trial-phone-numbers-faq.md

@@ -0,0 +1,71 @@
+---
+title: Frequently asked questions about trial phone numbers in Azure Communication Services
+description: A conceptual overview plus FAQ for trial phone numbers and verified phone numbers.
+author: jadacampbell
+ms.author: jadacampbell
+ms.service: azure-communication-services
+ms.topic: conceptual
+ms.date: 07/19/2023
+ms.custom: template-concept
+---
+
+# Frequently asked questions about trial phone numbers in Azure Communication Services
+
+[!INCLUDE [Public Preview Notice](../../includes/public-preview-include.md)]
+
+This article answers commonly asked questions about Trial Phone Numbers and Verified Phone Numbers. 
+
+
+
+## Trial Phone Numbers
+### How many trial phone numbers can I request? 
+Customers are limited to one trial phone number.
+ 
+### Is my subscription eligible for a trial phone number? 
+Currently trial phone numbers are only available for US subscriptions. For more information on subscriptions in other regions available for purchase, see our subscription eligibility documentation.  
+
+### Can I use the trial phone number for SMS messaging? 
+No, currently the trial phone number for Azure Communication Services only supports PSTN Calling capabilities. SMS messaging capabilities for trial phone numbers will be available soon. Keep an eye on the Azure Communication Services documentation for updates on when SMS functionality will be added to the trial phone numbers. 
+
+### Can I choose a specific phone number or area code for the trial number? 
+Currently, customers who can activate a trial phone number will be provided a US toll-free number. If you require a specific phone number or area code, then you must [purchase a phone number](../../quickstarts/telephony/get-phone-number.md). 
+
+### How long can I use the trial phone number? 
+The trial phone number is available for 30 days. After the trial period ends, the phone number will no longer be accessible. It's recommended to upgrade to a production subscription if you require a longer-term phone number. 
+
+
+### How can I make and receive calls using the trial phone number? 
+You can use Azure Communication Services APIs or SDKs to make and receive calls using the trial phone number. Microsoft provides comprehensive documentation and code samples to help you integrate the PSTN Calling capabilities into your applications. 
+
+### What are the calling limitations on my trial phone number? 
+Trial phone numbers have 60 minutes of inbound and 60 minutes of outbound PSTN calling. The max duration of a phone call is 5 minutes. The trial phone number may not be used to dial emergency services such as 911, 311, 988 or any emergency numbers.
+ 
+### Are there any costs associated with the trial phone number? 
+While the trial phone number itself is provided at no cost during the trial period, there may be associated costs for making and receiving calls or other PSTN Calling services. It's essential to review the pricing details for Azure Communication Services to understand the costs involved.  
+
+## Verified Phone Numbers
+
+### Why do I need to verify the recipient phone number for a trial phone number?
+Verifying the recipient phone number is a security measure that ensures the trial phone number can only make calls to the verified number. This helps protect against misuse and unauthorized usage of trial phone numbers.
+
+### How is the recipient phone number verified?
+The verification process involves sending a one-time passcode via SMS to the recipient phone number. The recipient needs to enter this code in the Azure portal to complete the verification.
+
+### Can I verify multiple recipient phone numbers for the same trial phone number?
+Currently the trial phone number can be verified for up to three recipient phone numbers. If you need to make calls to more numbers, then you'll need to [purchase a phone number](../../quickstarts/telephony/get-phone-number.md)
+
+### What happens if I enter the verification code incorrectly?
+If the verification code is entered incorrectly, the verification process fails. You can request a new verification code and try again.
+
+### Does the recipient phone number need to be in a specific format for verification?
+Yes, the recipient phone number should be entered in the correct international format, including the country code. Ensure that the phone number is accurate and free of any typos or formatting errors.
+
+### How long does the verification process take?
+The verification code is typically sent within a few seconds after initiating the verification process. The overall process should be completed quickly, depending on the recipient's ability to receive the SMS and enter the code in the Azure portal. 
+
+
+## Next steps
+
+> [!div class="nextstepaction"]
+> [Get a trial phone number](../../quickstarts/telephony/get-trial-phone-number.md)
+

articles/communication-services/quickstarts/call-automation/includes/quickstart-make-an-outbound-call-using-callautomation-csharp.md

@@ -15,7 +15,7 @@ ms.custom: mode-other
 
 - 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](../../create-communication-resource.md).
-- A [phone number](../../telephony/get-phone-number.md) in your Azure Communication Services resource that can make outbound calls. NB: phone numbers aren't available in free subscriptions.
+- A [phone number](../../telephony/get-phone-number.md) in your Azure Communication Services resource that can make outbound calls. If you have a free subscription, you can [get a trial phone number](../../telephony/get-trial-phone-number.md).
 - Create and host an Azure Dev Tunnel. Instructions [here](/azure/developer/dev-tunnels/get-started)
 
 ## Sample code

articles/communication-services/quickstarts/call-automation/includes/quickstart-make-an-outbound-call-using-callautomation-java.md

@@ -15,7 +15,7 @@ ms.custom: mode-other
 
 - 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](../../create-communication-resource.md).
-- A [phone number](../../telephony/get-phone-number.md) in your Azure Communication Services resource that can make outbound calls. NB: phone numbers aren't available in free subscriptions.
+- A [phone number](../../telephony/get-phone-number.md) in your Azure Communication Services resource that can make outbound calls. If you have a free subscription, you can [get a trial phone number](../../telephony/get-trial-phone-number.md).
 - Create and host an Azure Dev Tunnel. Instructions [here](/azure/developer/dev-tunnels/get-started)
 - [Java Development Kit (JDK) version 11 or above](/azure/developer/java/fundamentals/java-jdk-install)
 - [Apache Maven](https://maven.apache.org/download.cgi)

articles/communication-services/quickstarts/call-automation/includes/quickstart-make-an-outbound-call-using-callautomation-node.md

@@ -15,7 +15,7 @@ ms.custom: mode-other
 
 - 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](../../create-communication-resource.md).
-- A [phone number](../../telephony/get-phone-number.md) in your Azure Communication Services resource that can make outbound calls
+- A [phone number](../../telephony/get-phone-number.md) in your Azure Communication Services resource that can make outbound calls. If you have a free subscription, you can [get a trial phone number](../../telephony/get-trial-phone-number.md).
 - Create and host an Azure Dev Tunnel. Instructions [here](/azure/developer/dev-tunnels/get-started)
 - [Node.js](https://nodejs.org/en/) LTS installation.
 - [Visual Studio Code](https://code.visualstudio.com/download) installed

articles/communication-services/quickstarts/call-automation/includes/quickstart-make-an-outbound-call-using-callautomation-python.md

@@ -15,7 +15,7 @@ ms.custom: mode-other
 
 - 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](../../create-communication-resource.md).
-- A [phone number](../../telephony/get-phone-number.md) in your Azure Communication Services resource that can make outbound calls. NB: phone numbers aren't available in free subscriptions.
+- A [phone number](../../telephony/get-phone-number.md) in your Azure Communication Services resource that can make outbound calls. If you have a free subscription, you can [get a trial phone number](../../telephony/get-trial-phone-number.md).
 - Create and host an Azure Dev Tunnel. Instructions [here](/azure/developer/dev-tunnels/get-started)
 - [Python](https://www.python.org/downloads/) 3.7+.
 

articles/communication-services/quickstarts/telephony/get-trial-phone-number.md

@@ -0,0 +1,79 @@
+---
+title: Quickstart - get and manage trial phone numbers in Azure Communication Services
+description: Learn how to get and use trial phone numbers in Azure Communication Services.
+author: jadacampbell
+ms.author: jadacampbell
+ms.service: azure-communication-services
+ms.topic: quickstart
+ms.date: 07/19/2023
+ms.custom: template-quickstart
+---
+
+# Quickstart: get and manage a trial phone number in Azure Communication Services
+
+[!INCLUDE [Public Preview Notice](../../includes/public-preview-include.md)]
+
+> [!NOTE]
+> Trial Phone Numbers are currently only supported by Azure subscriptions with billing addresses based in the United States. To those outside the US, you can visit the [Subscription eligibility](../../concepts/numbers/sub-eligibility-number-capability.md) documentation to determine where you purchase a phone number. 
+
+Azure Communication Services provides powerful communication capabilities for developers to integrate voice, video, and SMS functionalities into their applications. One of the key features is the ability to acquire phone numbers for making and receiving calls. This quickstart guide walks you through the process of obtaining a trial phone number for Azure Communication Services. 
+
+## Prerequisites
+
+- An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
+- An active Communication Services resource. [Create a Communication Services resource](../create-communication-resource.md).
+
+## Get a trial phone number
+
+1. Navigate to your Communication Service resource in the [Azure portal](https://portal.azure.com). 
+:::image type="content" source="./media/trial-phone-numbers/trial-overview.png" alt-text="Screenshot showing a Communication Services resource's main page." lightbox="./media/trial-phone-numbers/trial-overview.png":::
+
+2. In the Communication Services resource overview, select on the "Phone numbers" option in the left-hand menu. 
+:::image type="content" source="./media/trial-phone-numbers/trial-empty.png" alt-text="Screenshot showing a Communication Services resource's phone numbers page." lightbox="./media/trial-phone-numbers/trial-empty.png":::
+If you don’t have any phone numbers yet, you will see an empty list of phone numbers followed by this call to action for trial phone numbers.  
+If you already have numbers for your Communication Services resource, you can also activate a trial phone number: 
+:::image type="content" source="./media/trial-phone-numbers/trial-empty-with-purchased-numbers.png" alt-text="Screenshot showing a Communication Services resource's phone numbers page with already purchased numbers." lightbox="./media/trial-phone-numbers/trial-empty-with-purchased-numbers.png":::
+
+3. Select on “Activate trial phone number”. This immediately provisions a trial phone number to your Communication Services resource.  Once the trial phone number is provisioned, you can view it on the Phone numbers page. 
+:::image type="content" source="./media/trial-phone-numbers/trial-activated.png" alt-text="Screenshot showing a Communication Services resource's phone numbers page with a trial phone number." lightbox="./media/trial-phone-numbers/trial-activated.png":::
+
+## Add a verified phone number to your trial phone number
+When using a trial phone number in Azure Communication Services for PSTN Calling capabilities, it is required to verify the recipient phone number. This verification process ensures that the trial phone number can only make calls to the verified number. 
+
+1. Once your trial phone number is provisioned, select on the number in the Phone Numbers page and navigate to the “Trial details” tab: 
+:::image type="content" source="./media/trial-phone-numbers/trial-details.png" alt-text="Screenshot showing a Communication Services resource's phone numbers page with a side panel open with the trial details tab." lightbox="./media/trial-phone-numbers/trial-details.png":::
+This tab shows the current limitations on the number, including the days left to use the number, the total calling minutes, and how many verified phone numbers are attached to the trial phone number. You can find more information on the trial phone number limitations [here](../../concepts/telephony/trial-phone-numbers-faq.md).
+
+2. Select on “Manage verified phone numbers” to start adding verified phone numbers. 
+:::image type="content" source="./media/trial-phone-numbers/verified-empty.png" alt-text="Screenshot showing a side panel with an empty list of verified phone numbers." lightbox="./media/trial-phone-numbers/verified-empty.png":::
+
+3. Select “Add” or “Verify a phone number” and enter your phone number and designated country code associated with it. This recipient phone number is verified by sending a one-time passcode (OTP) to their number either through SMS or automated voicemail. Choose which option you prefer, and then press “Next” to receive the OTP. 
+:::image type="content" source="./media/trial-phone-numbers/verified-enter-number.png" alt-text="Screenshot showing a side panel with an entered phone number to verify. The radio button to text the phone number has been selected." lightbox="./media/trial-phone-numbers/verified-enter-number.png":::
+
+4. Once the user gets the one-time-passcode (OTP), enter the code into the Portal to verify the number.  
+:::image type="content" source="./media/trial-phone-numbers/verified-text-code.png" alt-text="Screenshot showing a side panel with an entered one-time passcode." lightbox="./media/trial-phone-numbers/verified-text-code.png":::
+
+5. Once the correct OTP is entered, the phone number is verified, and it shows in the list of verified numbers that the trial number can call. 
+:::image type="content" source="./media/trial-phone-numbers/verified-added.png" alt-text="Screenshot showing a side panel with an added verified phone number." lightbox="./media/trial-phone-numbers/verified-added.png"::: 
+
+## Conclusion
+Congratulations! You have successfully obtained a trial phone number for Azure Communication Services. You can now use this phone number to add voice capabilities to your applications. Explore the documentation and resources provided by Microsoft to learn more about Azure Communication Services and integrate it into your projects. 
+
+Remember that trial phone numbers have limitations and are intended for evaluation and development purposes. If you require production-ready phone numbers, you can upgrade your Azure Communication Services subscription and [purchase a phone number](get-phone-number.md). 
+
+
+## Next steps
+
+In this quickstart you learned how to:
+
+> [!div class="checklist"]
+> * Activate a trial phone number
+> * View your trial phone number limits
+> * Add a verified phone number
+
+> [!div class="nextstepaction"]
+> [Make your first outbound call with Call Automation](../call-automation/quickstart-make-an-outbound-call.md)
+
+> [!div class="nextstepaction"]
+> [Add PSTN calling in your app](pstn-call.md)
+

articles/communication-services/quickstarts/telephony/includes/pstn-call-android.md

@@ -15,7 +15,7 @@ Find the finalized code for this quickstart on [GitHub](https://github.com/Azure
 
 - 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](../../create-communication-resource.md).
-- A [phone number acquired](../get-phone-number.md) in your Communication Services resource, or Azure Communication Services [direct routing configured](../../../concepts/telephony/direct-routing-provisioning.md)
+- A [phone number acquired](../get-phone-number.md) in your Communication Services resource, or Azure Communication Services [Direct Routing configured](../../../concepts/telephony/direct-routing-provisioning.md). If you have a free subscription, you can [get a trial phone number](../../telephony/get-trial-phone-number.md).
 - A `User Access Token` to enable the call client. For more information on [how to get a `User Access Token`](../../identity/access-tokens.md)
 - Complete the quickstart for [getting started with adding calling to your application](../../voice-video-calling/getting-started-with-calling.md)
 
@@ -35,7 +35,7 @@ import com.azure.android.communication.common.PhoneNumberIdentifier;
 
 ## Start a call to phone
 
-Specify the phone number you acquired from within your Communication Services resource. This number will be used as a caller id to start the call:
+Specify the phone number you acquired from within your Communication Services resource. This number is used as a caller ID to start the call:
 
 > [!WARNING]
 > Note that phone numbers should be provided in E.164 international standard format. (e.g.: +12223334444)
@@ -59,7 +59,7 @@ Modify `startCall()` event handler in **MainActivity.java**, so that it handles
 
 ## Launch the app and call the echo bot
 
-The app can now be launched using the "Run App" button on the toolbar (Shift+F10). To make a call, provide a phone number in the added text field and click the **CALL** button.
+The app can now be launched using the "Run App" button on the toolbar (Shift+F10). To make a call, provide a phone number in the added text field and select the **CALL** button.
 > [!WARNING]
 > Note that phone numbers should be provided in E.164 international standard format. (e.g.: +12223334444)
 

articles/communication-services/quickstarts/telephony/includes/pstn-call-ios.md

@@ -11,7 +11,7 @@ ms.author: nikuklic
 
 - 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](../../create-communication-resource.md).
-- A [phone number acquired](../get-phone-number.md) in your Communication Services resource, or Azure Communication Services [direct routing configured](../../../concepts/telephony/direct-routing-provisioning.md)
+- A [phone number acquired](../get-phone-number.md) in your Communication Services resource, or Azure Communication Services [Direct routing configured](../../../concepts/telephony/direct-routing-provisioning.md). If you have a free subscription, you can [get a trial phone number](../../telephony/get-trial-phone-number.md).
 - A `User Access Token` to enable the call client. For more information on [how to get a `User Access Token`](../../identity/access-tokens.md)
 - Complete the quickstart for [getting started with adding calling to your application](../../voice-video-calling/getting-started-with-calling.md)
 
@@ -24,11 +24,11 @@ ms.author: nikuklic
 
 ## Start a call to phone
 
-Specify phone number you acquired in Communication Services resource, that will be used to start the call:
+Specify phone number you acquired in Communication Services resource that is used to start the call:
 > [!WARNING]
 > Note that phone numbers should be provided in E.164 international standard format. (e.g.: +12223334444)
 
-Modify `startCall` event handler that will be performed when the *Start Call* button is tapped:
+Modify `startCall` event handler that is performed when the *Start Call* button is tapped:
 
 ```swift
 func startCall() {
@@ -55,7 +55,7 @@ You can build and run your app on iOS simulator by selecting **Product** > **Run
 
 ![Final look and feel of the quick start app](../media/pstn-call/quick-start-make-call.png)
 
-You can make an call to phone by providing a phone number in the added text field and clicking the **Start Call** button.
+You can make a call to phone by providing a phone number in the added text field and clicking the **Start Call** button.
 > [!WARNING]
 > Note that phone numbers should be provided in E.164 international standard format. (e.g.: +12223334444)