This browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
Important
SMS and PSTN capabilities depend on the phone number you use and the country/region that you're operating within as determined by your Azure billing address. For more information, visit the Subscription eligibility documentation.
Important
For high-volume orders or in the event that your desired phone number is unavailable, please visit this page for further assistance.
To begin provisioning numbers, go to your Communication Services resource on the Azure portal.
Navigate to the Phone Numbers blade in the resource menu.
Press the Get button to launch the wizard. The wizard on the Phone numbers blade will walk you through a series of questions that helps you choose the phone number that best fits your scenario.
You will first need to choose the Country/region where you would like to provision the phone number. After selecting the Country/region, you will then need to select the Use case which best suites your needs.
Configuring your phone number is broken down into two steps:
You can select from two phone number types: Local, and Toll-free. When you've selected a number type, you can then choose the feature.
In our example, we've selected a Toll-free number type with Make calls and Send and receive SMS features.
From here, click the Next: Numbers button at the bottom of the page to customize the phone number(s) you would like to provision.
On the Numbers page, you will customize the phone number(s) which you'd like to provision.
Note
This quickstart is showing the Toll-free Number type customization flow. The experience may be slightly different if you have chosen the Local Number type, but the end-result will be the same.
Choose the Area code from the list of available Area codes and enter the quantity which you'd like to provision, then click Search to find numbers which meet your selected requirements. The phone numbers which meet your needs will be shown along with their monthly cost.
Note
Availability depends on the Number type, location, and the features that you have selected. Numbers are reserved for a short time before the transaction expires. If the transaction expires, you will need to re-select the numbers.
To view the purchase summary and place your order, click the Next: Summary button at the bottom of the page.
The summary page will review the Number type, Features, Phone Numbers, and Total monthly cost to provision the phone numbers.
Note
The prices shown are the monthly recurring charges which cover the cost of leasing the selected phone number to you. Not included in this view is the Pay-as-you-go costs which are incurred when you make or receive calls. The price lists are available here. These costs depend on number type and destinations called. For example, price-per-minute for a call from a Seattle regional number to a regional number in New York and a call from the same number to a UK mobile number may be different.
Finally, click Place order at the bottom of the page to confirm.
Navigate to your Azure Communication Services resource on the Azure portal:
Select the Phone Numbers blade in the menu to manage your phone numbers.
Note
It may take a few minutes for the provisioned numbers to be shown on this page.
On the Phone Numbers page, you can select a phone number to configure it.
Select the features from the available options, then click Save to apply your selection.
On the Numbers page, you can release phone numbers.
Select the phone number that you want to release and then click on the Release button.
Important
This feature of Azure Communication Services is currently in preview.
Preview APIs and SDKs are provided without a service-level agreement. We recommend that you don't use them for production workloads. Some features might not be supported, or they might have constrained capabilities.
For more information, review Supplemental Terms of Use for Microsoft Azure Previews.
Azure Communication Services is introducing a new user experience for purchasing phone numbers. This experience is currently being flighted, and you might be introduced to this experience when purchasing a phone number in Azure portal. If you have feedback on this experience, don't hesitate to give it through the Give feedback button on Azure portal extension.
Navigate to your Communication Service resource in the Azure portal.
In the Communication Services resource overview, select on the "Phone numbers" option in the left-hand menu.
Select Get on the top left of the page to purchase your phone number. Selecting this launches our shopping wizard:
Choose the Country/region where you would like to provision the phone number. Country/region availability is based on the billing location for your Azure subscription. More information on what numbers are available for each country/region can be found here. Next you'll choose the number type. You can select from two phone number types: Local, and Toll-free.
Select Search to pull up numbers that meet your selected criteria. You have various filters to search for the number that fits your needs, including:
Once you find the phone number or numbers to your choosing, select Add to cart to hold the numbers in the Telephony cart. These numbers are held for 16 minutes before your cart is automatically cleared.
Note
The prices shown are the monthly recurring charges which cover the cost of leasing the selected phone number to you. Not included in this view is the Pay-as-you-go costs which are incurred when you make or receive calls. The price lists are available here. These costs depend on number type and destinations called. For example, price-per-minute for a call from a Seattle regional number to a regional number in New York and a call from the same number to a UK mobile number may be different.
Select Next to review your purchase. To complete your purchase, select Buy now.
You can find your purchased numbers back on the Phone numbers page. It might take a few minutes for the numbers to be provisioned.
On the Phone Numbers page, you can select a phone number to configure it.
Select the features from the available options, then select Save to apply your selection.
On the Numbers page, you can release phone numbers.
Select the phone number that you want to release and then select on the Release button.
An Azure account with an active subscription. Create an account for free.
An active Communication Services resource and connection string. Create a Communication Services resource.
Install Azure CLI.
A purchased phone number.
Add the Azure Communication Services extension for Azure CLI by using the az extension command.
az extension add --name communication
You'll need to sign in to Azure CLI. You can sign in running the az login command from the terminal and providing your credentials.
Run the following command to retrieve all of the purchased phone numbers.
az communication phonenumber list --connection-string "<yourConnectionString>"
Make this replacement in the code:
<yourConnectionString> with your connection string.Run the following command to get the phone number details for a purchased phone number.
az communication phonenumber show --phonenumber <purchasedPhoneNumber> --connection-string "<yourConnectionString>"
Make these replacements in the code:
<purchasedPhoneNumber> with a phone number that's associated with your Communication Services resource.<yourConnectionString> with your connection string.Note
The Azure CLI option provides functionality only for listing and showing phone numbers. It does not support other operations such as searching, purchasing, editing or releasing phone numbers.
You can configure the AZURE_COMMUNICATION_CONNECTION_STRING environment variable to use Azure CLI phone numbers operations without having to use --connection_string to pass in the connection string. To configure an environment variable, open a console window and select your operating system from the below tabs. Replace <yourConnectionString> with your actual connection string.
Edit your .bash_profile, and add the environment variable:
export AZURE_COMMUNICATION_CONNECTION_STRING="<yourConnectionString>"
After you add the environment variable, run source ~/.bash_profile from your console window to make the changes effective. If you created the environment variable with your IDE open, you may need to close and reopen the editor, IDE, or shell in order to access the variable.
Note
Find the finalized code for this quickstart on GitHub
dotnet command to check that the .NET client library is installed.In a console window (such as cmd, PowerShell, or Bash), use the dotnet new command to create a new console app with the name PhoneNumbersQuickstart. This command creates a simple "Hello World" C# project with a single source file: Program.cs.
dotnet new console -o PhoneNumbersQuickstart
Change your directory to the newly created app folder and use the dotnet build command to compile your application.
cd PhoneNumbersQuickstart
dotnet build
While still in the application directory, install the Azure Communication PhoneNumbers client library for .NET package by using the dotnet add package command.
dotnet add package Azure.Communication.PhoneNumbers --version 1.0.0
Add a using directive to the top of Program.cs to include the namespaces.
using System;
using System.Linq;
using System.Threading.Tasks;
using Azure.Communication.PhoneNumbers;
Update Main function signature to be async.
static async Task Main(string[] args)
{
...
}
Phone Number clients can be authenticated using connection string acquired from an Azure Communication Services resources in the Azure portal.
// Get a connection string to our Azure Communication Services resource.
var connectionString = "<connection_string>";
var client = new PhoneNumbersClient(connectionString);
Phone Number clients also have the option to authenticate with Microsoft Entra authentication. With this option,
AZURE_CLIENT_SECRET, AZURE_CLIENT_ID and AZURE_TENANT_ID environment variables need to be set up for authentication.
// Get an endpoint to our Azure Communication Services resource.
var endpoint = new Uri("<endpoint_url>");
TokenCredential tokenCredential = new DefaultAzureCredential();
client = new PhoneNumbersClient(endpoint, tokenCredential);
In order to purchase phone numbers, you must first search for available phone numbers. To search for phone numbers, provide the area code, assignment type, phone number capabilities, phone number type, and quantity. Note that for the toll-free phone number type, providing the area code is optional.
var capabilities = new PhoneNumberCapabilities(calling:PhoneNumberCapabilityType.None, sms:PhoneNumberCapabilityType.Outbound);
var searchOptions = new PhoneNumberSearchOptions { AreaCode = "833", Quantity = 1 };
var searchOperation = await client.StartSearchAvailablePhoneNumbersAsync("US", PhoneNumberType.TollFree, PhoneNumberAssignmentType.Application, capabilities, searchOptions);
await searchOperation.WaitForCompletionAsync();
The result of searching for phone numbers is a PhoneNumberSearchResult. This contains a SearchId which can be passed to the purchase numbers API to acquire the numbers in the search. Note that calling the purchase phone numbers API will result in a charge to your Azure Account.
var purchaseOperation = await client.StartPurchasePhoneNumbersAsync(searchOperation.Value.SearchId);
await purchaseOperation.WaitForCompletionResponseAsync();
After a purchasing number, you can retrieve it from the client.
var getPhoneNumberResponse = await client.GetPurchasedPhoneNumberAsync("+14255550123");
Console.WriteLine($"Phone number: {getPhoneNumberResponse.Value.PhoneNumber}, country code: {getPhoneNumberResponse.Value.CountryCode}");
You can also retrieve all the purchased phone numbers.
var purchasedPhoneNumbers = client.GetPurchasedPhoneNumbersAsync();
await foreach (var purchasedPhoneNumber in purchasedPhoneNumbers)
{
Console.WriteLine($"Phone number: {purchasedPhoneNumber.PhoneNumber}, country code: {purchasedPhoneNumber.CountryCode}");
}
With a purchased number, you can update the capabilities.
var updateCapabilitiesOperation = await client.StartUpdateCapabilitiesAsync("+14255550123", calling: PhoneNumberCapabilityType.Outbound, sms: PhoneNumberCapabilityType.InboundOutbound);
await updateCapabilitiesOperation.WaitForCompletionAsync();
You can release a purchased phone number.
var releaseOperation = await client.StartReleasePhoneNumberAsync("+14255550123");
await releaseOperation.WaitForCompletionResponseAsync();
Run the application from your application directory with the dotnet run command.
dotnet run
You can download the sample app from GitHub
Note
Find the finalized code for this quickstart on GitHub
Open your terminal or command window. Navigate to the directory where you'd like to create your Java application. Run the command below to generate the Java project from the maven-archetype-quickstart template.
mvn archetype:generate -DgroupId=com.communication.quickstart -DartifactId=communication-quickstart -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false
You'll notice that the 'generate' task created a directory with the same name as the artifactId. Under this directory, the src/main/java directory contains the project source code, the src/test/java directory contains the test source, and the pom.xml file is the project's Project Object Model, or POM.
Open the pom.xml file in your text editor. Add the following dependency elements to the group of dependencies.
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-communication-common</artifactId>
<version>1.0.0</version>
</dependency>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-communication-phonenumbers</artifactId>
<version>1.0.0</version>
</dependency>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-identity</artifactId>
<version>1.2.3</version>
</dependency>
From the project directory:
System.out.println("Hello world!"); statementimport directivesUse the following code to begin:
import com.azure.communication.phonenumbers.*;
import com.azure.communication.phonenumbers.models.*;
import com.azure.core.http.rest.*;
import com.azure.core.util.Context;
import com.azure.core.util.polling.LongRunningOperationStatus;
import com.azure.core.util.polling.PollResponse;
import com.azure.core.util.polling.SyncPoller;
import com.azure.identity.*;
import java.io.*;
public class App
{
public static void main( String[] args ) throws IOException
{
System.out.println("Azure Communication Services - Phone Numbers Quickstart");
// Quickstart code goes here
}
}
The PhoneNumberClientBuilder is enabled to use Microsoft Entra authentication
// You can find your endpoint and access key from your resource in the Azure portal
String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";
PhoneNumbersClient phoneNumberClient = new PhoneNumbersClientBuilder()
.endpoint(endpoint)
.credential(new DefaultAzureCredentialBuilder().build())
.buildClient();
Alternatively, using the endpoint and access key from the communication resource to authenticate is also possible.
// You can find your connection string from your resource in the Azure portal
String connectionString = "endpoint=https://<RESOURCE_NAME>.communication.azure.com/;accesskey=<ACCESS_KEY>";
PhoneNumbersClient phoneNumberClient = new PhoneNumbersClientBuilder()
.connectionString(connectionString)
.buildClient();
In order to purchase phone numbers, you must first search for available phone numbers. To search for phone numbers, provide the area code, assignment type, phone number capabilities, phone number type, and quantity. Note that for the toll-free phone number type, providing the area code is optional.
PhoneNumberCapabilities capabilities = new PhoneNumberCapabilities()
.setCalling(PhoneNumberCapabilityType.INBOUND)
.setSms(PhoneNumberCapabilityType.INBOUND_OUTBOUND);
PhoneNumberSearchOptions searchOptions = new PhoneNumberSearchOptions().setAreaCode("833").setQuantity(1);
SyncPoller<PhoneNumberOperation, PhoneNumberSearchResult> poller = phoneNumberClient
.beginSearchAvailablePhoneNumbers("US", PhoneNumberType.TOLL_FREE, PhoneNumberAssignmentType.APPLICATION, capabilities, searchOptions, Context.NONE);
PollResponse<PhoneNumberOperation> response = poller.waitForCompletion();
String searchId = "";
if (LongRunningOperationStatus.SUCCESSFULLY_COMPLETED == response.getStatus()) {
PhoneNumberSearchResult searchResult = poller.getFinalResult();
searchId = searchResult.getSearchId();
System.out.println("Searched phone numbers: " + searchResult.getPhoneNumbers());
System.out.println("Search expires by: " + searchResult.getSearchExpiresBy());
System.out.println("Phone number costs:" + searchResult.getCost().getAmount());
}
The result of searching for phone numbers is a PhoneNumberSearchResult. This contains a searchId which can be passed to the purchase numbers API to acquire the numbers in the search. Note that calling the purchase phone numbers API will result in a charge to your Azure Account.
PollResponse<PhoneNumberOperation> purchaseResponse = phoneNumberClient.beginPurchasePhoneNumbers(searchId, Context.NONE).waitForCompletion();
System.out.println("Purchase phone numbers operation is: " + purchaseResponse.getStatus());
After a purchasing number, you can retrieve it from the client.
PurchasedPhoneNumber phoneNumber = phoneNumberClient.getPurchasedPhoneNumber("+14255550123");
System.out.println("Phone Number Country Code: " + phoneNumber.getCountryCode());
You can also retrieve all the purchased phone numbers.
PagedIterable<PurchasedPhoneNumber> phoneNumbers = phoneNumberClient.listPurchasedPhoneNumbers(Context.NONE);
PurchasedPhoneNumber phoneNumber = phoneNumbers.iterator().next();
System.out.println("Phone Number Country Code: " + phoneNumber.getCountryCode());
With a purchased number, you can update the capabilities.
PhoneNumberCapabilities capabilities = new PhoneNumberCapabilities();
capabilities
.setCalling(PhoneNumberCapabilityType.INBOUND)
.setSms(PhoneNumberCapabilityType.INBOUND_OUTBOUND);
SyncPoller<PhoneNumberOperation, PurchasedPhoneNumber> poller = phoneNumberClient.beginUpdatePhoneNumberCapabilities("+18001234567", capabilities, Context.NONE);
PollResponse<PhoneNumberOperation> response = poller.waitForCompletion();
if (LongRunningOperationStatus.SUCCESSFULLY_COMPLETED == response.getStatus()) {
PurchasedPhoneNumber phoneNumber = poller.getFinalResult();
System.out.println("Phone Number Calling capabilities: " + phoneNumber.getCapabilities().getCalling()); //Phone Number Calling capabilities: inbound
System.out.println("Phone Number SMS capabilities: " + phoneNumber.getCapabilities().getSms()); //Phone Number SMS capabilities: inbound+outbound
}
You can release a purchased phone number.
PollResponse<PhoneNumberOperation> releaseResponse =
phoneNumberClient.beginReleasePhoneNumber("+14255550123", Context.NONE).waitForCompletion();
System.out.println("Release phone number operation is: " + releaseResponse.getStatus());
Navigate to the directory containing the pom.xml file and compile the project by using the following mvn command.
mvn compile
Then, build the package.
mvn package
Run the following mvn command to execute the app.
mvn exec:java -Dexec.mainClass="com.communication.quickstart.App" -Dexec.cleanupDaemonThreads=false
The output of the app describes each action that is completed:
Azure Communication Services - Phone Numbers Quickstart
Searched phone numbers: [+18001234567]
Purchase phone numbers operation is: SUCCESSFULLY_COMPLETED
Phone Number Country Code: US
Phone Number Calling capabilities: inbound
Phone Number SMS capabilities: inbound
Release phone number operation is: SUCCESSFULLY_COMPLETED
Note
Find the finalized code for this quickstart on GitHub
Open your terminal or command window and create a new directory for your app, then navigate to it.
mkdir phone-numbers-quickstart && cd phone-numbers-quickstart
Use a text editor to create a file called phone_numbers_sample.py in the project root directory and add the following code. We'll be adding the remaining quickstart code in the following sections.
import os
from azure.communication.phonenumbers import PhoneNumbersClient
try:
print('Azure Communication Services - Phone Numbers Quickstart')
# Quickstart code goes here
except Exception as ex:
print('Exception:')
print(ex)
While still in the application directory, install the Azure Communication Services Administration client library for Python package by using the pip install command.
pip install azure-communication-phonenumbers
The PhoneNumbersClient is enabled to use Microsoft Entra authentication. Using the DefaultAzureCredential object is the easiest way to get started with Microsoft Entra ID and you can install it using the pip install command.
pip install azure-identity
Creating a DefaultAzureCredential object requires you to have AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, and AZURE_TENANT_ID already set as environment variables with their corresponding values from your registered Microsoft Entra application.
For a quick ramp-up on how to get these environment variables, you can follow the Set up service principals from CLI quickstart.
Once you have installed the azure-identity library, we can continue authenticating the client.
import os
from azure.communication.phonenumbers import PhoneNumbersClient
from azure.identity import DefaultAzureCredential
# You can find your endpoint from your resource in the Azure portal
endpoint = 'https://<RESOURCE_NAME>.communication.azure.com'
try:
print('Azure Communication Services - Phone Numbers Quickstart')
credential = DefaultAzureCredential()
phone_numbers_client = PhoneNumbersClient(endpoint, credential)
except Exception as ex:
print('Exception:')
print(ex)
Alternatively, using the endpoint and access key from the communication resource to authenticate is also possible.
import os
from azure.communication.phonenumbers import PhoneNumbersClient
# You can find your connection string from your resource in the Azure portal
connection_string = 'https://<RESOURCE_NAME>.communication.azure.com/;accesskey=<YOUR_ACCESS_KEY>'
try:
print('Azure Communication Services - Phone Numbers Quickstart')
phone_numbers_client = PhoneNumbersClient.from_connection_string(connection_string)
except Exception as ex:
print('Exception:')
print(ex)
Once the PhoneNumbersClient has been authenticated, we can start working on the different functions it can do.
In order to purchase phone numbers, you must first search for any available phone numbers. To search for phone numbers, provide the area code, assignment type, phone number capabilities, phone number type, and quantity (default quantity is set to 1). Note that for the toll-free phone number type, providing the area code is optional.
import os
from azure.communication.phonenumbers import PhoneNumbersClient, PhoneNumberCapabilityType, PhoneNumberAssignmentType, PhoneNumberType, PhoneNumberCapabilities
from azure.identity import DefaultAzureCredential
# You can find your endpoint from your resource in the Azure portal
endpoint = 'https://<RESOURCE_NAME>.communication.azure.com'
try:
print('Azure Communication Services - Phone Numbers Quickstart')
credential = DefaultAzureCredential()
phone_numbers_client = PhoneNumbersClient(endpoint, credential)
capabilities = PhoneNumberCapabilities(
calling = PhoneNumberCapabilityType.INBOUND,
sms = PhoneNumberCapabilityType.INBOUND_OUTBOUND
)
search_poller = phone_numbers_client.begin_search_available_phone_numbers(
"US",
PhoneNumberType.TOLL_FREE,
PhoneNumberAssignmentType.APPLICATION,
capabilities,
polling = True
)
search_result = search_poller.result()
print ('Search id: ' + search_result.search_id)
phone_number_list = search_result.phone_numbers
print('Reserved phone numbers:')
for phone_number in phone_number_list:
print(phone_number)
except Exception as ex:
print('Exception:')
print(ex)
The result of searching for phone numbers is a PhoneNumberSearchResult. This contains a searchId which can be passed to the purchase numbers API to acquire the numbers in the search. Note that calling the purchase phone numbers API will result in a charge to your Azure Account.
import os
from azure.communication.phonenumbers import (
PhoneNumbersClient,
PhoneNumberCapabilityType,
PhoneNumberAssignmentType,
PhoneNumberType,
PhoneNumberCapabilities
)
from azure.identity import DefaultAzureCredential
# You can find your endpoint from your resource in the Azure portal
endpoint = 'https://<RESOURCE_NAME>.communication.azure.com'
try:
print('Azure Communication Services - Phone Numbers Quickstart')
credential = DefaultAzureCredential()
phone_numbers_client = PhoneNumbersClient(endpoint, credential)
capabilities = PhoneNumberCapabilities(
calling = PhoneNumberCapabilityType.INBOUND,
sms = PhoneNumberCapabilityType.INBOUND_OUTBOUND
)
search_poller = phone_numbers_client.begin_search_available_phone_numbers(
"US",
PhoneNumberType.TOLL_FREE,
PhoneNumberAssignmentType.APPLICATION,
capabilities,
area_code="833",
polling = True
)
search_result = poller.result()
print ('Search id: ' + search_result.search_id)
phone_number_list = search_result.phone_numbers
print('Reserved phone numbers:')
for phone_number in phone_number_list:
print(phone_number)
purchase_poller = phone_numbers_client.begin_purchase_phone_numbers(search_result.search_id, polling = True)
purchase_poller.result()
print("The status of the purchase operation was: " + purchase_poller.status())
except Exception as ex:
print('Exception:')
print(ex)
After a purchasing number, you can retrieve it from the client.
purchased_phone_number_information = phone_numbers_client.get_purchased_phone_number("+18001234567")
print('Phone number: ' + purchased_phone_number_information.phone_number)
print('Country code: ' + purchased_phone_number_information.country_code)
You can also retrieve all the purchased phone numbers.
purchased_phone_numbers = phone_numbers_client.list_purchased_phone_numbers()
print('Purchased phone numbers:')
for purchased_phone_number in purchased_phone_numbers:
print(purchased_phone_number.phone_number)
You can update the capabilities of a previously purchased phone number.
update_poller = phone_numbers_client.begin_update_phone_number_capabilities(
"+18001234567",
PhoneNumberCapabilityType.OUTBOUND,
PhoneNumberCapabilityType.OUTBOUND,
polling = True
)
update_poller.result()
print('Status of the operation: ' + update_poller.status())
You can release a purchased phone number.
release_poller = phone_numbers_client.begin_release_phone_number("+18001234567")
release_poller.result()
print('Status of the operation: ' + release_poller.status())
From a console prompt, navigate to the directory containing the phone_numbers_sample.py file, then execute the following Python command to run the app.
python phone_numbers_sample.py
Note
Find the finalized code for this quickstart on GitHub
node --version to check that Node.js is installed.First, open your terminal or command window, create a new directory for your app, and navigate to it.
mkdir phone-numbers-quickstart && cd phone-numbers-quickstart
Run npm init -y to create a package.json file with default settings.
npm init -y
Create a file called phone-numbers-quickstart.js in the root of the directory you just created. Add the following snippet to it:
async function main() {
// quickstart code will here
}
main();
Use the npm install command to install the Azure Communication Services Phone Numbers client library for JavaScript.
npm install @azure/communication-phone-numbers --save
The --save option adds the library as a dependency in your package.json file.
Import the PhoneNumbersClient from the client library and instantiate it with your connection string. The code below retrieves the connection string for the resource from an environment variable named COMMUNICATION_SERVICES_CONNECTION_STRING. Learn how to manage your resource's connection string.
Add the following code to the top of phone-numbers-quickstart.js:
const { PhoneNumbersClient } = require('@azure/communication-phone-numbers');
// This code demonstrates how to fetch your connection string
// from an environment variable.
const connectionString = process.env['COMMUNICATION_SERVICES_CONNECTION_STRING'];
// Instantiate the phone numbers client
const phoneNumbersClient = new PhoneNumbersClient(connectionString);
In order to purchase phone numbers, you must first search for available phone numbers. To search for phone numbers, provide the area code, assignment type, phone number capabilities, phone number type, and quantity. Note that for the toll-free phone number type, providing the area code is optional.
Add the following snippet to your main function:
/**
* Search for Available Phone Number
*/
// Create search request
const searchRequest = {
countryCode: "US",
phoneNumberType: "tollFree",
assignmentType: "application",
capabilities: {
sms: "outbound",
calling: "none"
},
areaCode: "833",
quantity: 1
};
const searchPoller = await phoneNumbersClient.beginSearchAvailablePhoneNumbers(searchRequest);
// The search is underway. Wait to receive searchId.
const { searchId, phoneNumbers } = await searchPoller.pollUntilDone();
const phoneNumber = phoneNumbers[0];
console.log(`Found phone number: ${phoneNumber}`);
console.log(`searchId: ${searchId}`);
The result of searching for phone numbers is a PhoneNumberSearchResult. This contains a searchId which can be passed to the purchase numbers API to acquire the numbers in the search. Note that calling the purchase phone numbers API will result in a charge to your Azure Account.
Add the following snippet to your main function:
/**
* Purchase Phone Number
*/
const purchasePoller = await phoneNumbersClient.beginPurchasePhoneNumbers(searchId);
// Purchase is underway.
await purchasePoller.pollUntilDone();
console.log(`Successfully purchased ${phoneNumber}`);
With a phone number now purchased, add the following code to update its capabilities:
/**
* Update Phone Number Capabilities
*/
// Create update request.
// This will update phone number to send and receive sms, but only send calls.
const updateRequest = {
sms: "inbound+outbound",
calling: "outbound"
};
const updatePoller = await phoneNumbersClient.beginUpdatePhoneNumberCapabilities(
phoneNumber,
updateRequest
);
// Update is underway.
await updatePoller.pollUntilDone();
console.log("Phone number updated successfully.");
After a purchasing number, you can retrieve it from the client. Add the following code to your main function to get the phone number you just purchased:
/**
* Get Purchased Phone Number
*/
const { capabilities } = await phoneNumbersClient.getPurchasedPhoneNumber(phoneNumber);
console.log("These capabilities:", capabilities, "should be the same as these:", updateRequest, ".");
You can also retrieve all the purchased phone numbers.
const purchasedPhoneNumbers = await phoneNumbersClient.listPurchasedPhoneNumbers();
for await (const purchasedPhoneNumber of purchasedPhoneNumbers) {
console.log(`Phone number: ${purchasedPhoneNumber.phoneNumber}, country code: ${purchasedPhoneNumber.countryCode}.`);
}
You can now release the purchased phone number. Add the code snippet below to your main function:
/**
* Release Purchased Phone Number
*/
const releasePoller = await phoneNumbersClient.beginReleasePhoneNumber(phoneNumber);
// Release is underway.
await releasePoller.pollUntilDone();
console.log("Successfully release phone number.");
Use the node command to run the code you added to the phone-numbers-quickstart.js file.
node phone-numbers-quickstart.js
Common Questions and Issues:
When a phone number is released, the phone number shows up in your ACS resource on Azure portal until the end of the billing cycle. It also can't be repurchased until the end of the billing cycle.
When a Communication Services resource is deleted, the phone numbers associated with that resource are automatically released at the same time.
In this quickstart you learned how to:
Training
Module
Send an SMS message from a C# console application with Azure Communication Services - Training
In this module, you'll create a C# console application that sends SMS messages using a phone number provisioned via Azure Communication Services.