Quickstart: Get and manage phone numbers

Important

Phone number availability is currently restricted to Azure subscriptions that have a billing address in the United States. For more information, visit the Phone number types documentation.

Important

For high-volume orders or in the event that your desired phone number is unavailable, complete this form and email it to acstnrequest@microsoft.com with a subject line beginning with "ACS Number Request:".

Prerequisites

Get a phone number

To begin provisioning numbers, go to your Communication Services resource on the Azure portal.

Screenshot showing a Communication Services resource's main page.

Search for Available Phone Numbers

Navigate to the Phone Numbers blade in the resource menu.

Screenshot showing a Communication Services resource's phone page.

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.

Screenshot showing the Get phone numbers view.

Select your phone number features

Configuring your phone number is broken down into two steps:

  1. The selection of the number type
  2. The selection of the number capabilities

You can select from two phone number types: Geographic, 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 the Outbound calling and Inbound and Outbound SMS features.

Screenshot showing the Select features view.

From here, click the Next: Numbers button at the bottom of the page to customize the phone number(s) you would like to provision.

Customizing phone numbers

On the Numbers page, you will customize the phone number(s) which you'd like to provision.

Screenshot showing the Numbers selection page.

Note

This quickstart is showing the Toll-free Number type customization flow. The experience may be slightly different if you have chosen the Geographic 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.

Screenshot showing the Numbers selection page with reserved numbers.

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.

Purchase Phone Numbers

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.

Screenshot showing the Summary page with the Number type, Features, Phone Numbers, and Total monthly cost shown.

Find your phone numbers on the Azure portal

Navigate to your Azure Communication Services resource on the Azure portal:

Screenshot showing a Communication Services Resource's main page.

Select the Phone Numbers blade in the menu to manage your phone numbers.

Screenshot showing a Communication Services Resource's phone number page.

Note

It may take a few minutes for the provisioned numbers to be shown on this page.

Update Phone Number Capabilities

On the Numbers page, you can select a phone number to configure it.

Screenshot showing the update features page.

Select the features from the available options, then click Confirm to apply your selection.

Release Phone Number

On the Numbers page, you can release phone numbers.

Screenshot showing the release phone numbers page.

Select the phone number that you want to release and then click on the Release button.

Note

Find the finalized code for this quickstart on GitHub

Prerequisites

Prerequisite check

  • In a terminal or command window, run the dotnet command to check that the .NET client library is installed.

Setting up

Create a new C# application

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

Install the package

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)
{
  ...
}

Authenticate the client

Phone Number clients can be authenticated using connection string acquired from an Azure Communication Services resources in the [Azure portal][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 Azure Active Directory 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);

Manage phone numbers

Search for available phone numbers

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();

Purchase phone numbers

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();

Get phone number(s)

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}");
}

Update phone number capabilities

With a purchased number, you can update the capabilities.

var updateCapabilitiesOperation = await client.StartUpdateCapabilitiesAsync("+14255550123", calling: PhoneNumberCapabilityType.Outbound, sms: PhoneNumberCapabilityType.InboundOutbound);
await updateCapabilitiesOperation.WaitForCompletionAsync();

Release phone number

You can release a purchased phone number.

var releaseOperation = await client.StartReleasePhoneNumberAsync("+14255550123");
await releaseOperation.WaitForCompletionResponseAsync();

Run the code

Run the application from your application directory with the dotnet run command.

dotnet run

Sample Code

You can download the sample app from GitHub

Note

Find the finalized code for this quickstart on GitHub

Prerequisites

Setting Up

Create a new Java application

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.

Install the package

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>

Set up the app framework

From the project directory:

  1. Navigate to the /src/main/java/com/communication/quickstart directory
  2. Open the App.java file in your editor
  3. Replace the System.out.println("Hello world!"); statement
  4. Add import directives

Use 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
    }
}

Authenticate the Phone Numbers Client

The PhoneNumberClientBuilder is enabled to use Azure Active Directory 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();

Manage Phone Numbers

Search for Available Phone Numbers

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());
}

Purchase Phone Numbers

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());

Get Phone Number(s)

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());

Update Phone Number Capabilities

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
}

Release Phone Number

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());

Run the code

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

Prerequisites

Setting up

Create a new Python application

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 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)

Install the package

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

Authenticate the Phone Numbers Client

The PhoneNumbersClient is enabled to use Azure Active Directory Authentication. Using the DefaultAzureCredential object is the easiest way to get started with Azure Active Directory 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 Azure AD 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)

Functions

Once the PhoneNumbersClient has been authenticated, we can start working on the different functions it can do.

Search for Available Phone Numbers

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)

Purchase Phone Numbers

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)

Get purchased phone number(s)

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)

Update Phone Number Capabilities

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())

Release Phone Number

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())

Run the code

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

Prerequisites

Prerequisite check

  • In a terminal or command window, run node --version to check that Node.js is installed.

Setting up

Create a new Node.js Application

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();

Install the package

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.

Authenticate the client

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);

Manage phone numbers

Search for available phone numbers

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}`);

Purchase phone number

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}`);

Update phone number capabilities

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.");

Get purchased phone number(s)

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}.`);
}

Release phone number

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.");

Run the code

Use the node command to run the code you added to the phone-numbers-quickstart.js file.

node phone-numbers-quickstart.js

Troubleshooting

Common Questions and Issues:

  • Purchasing phone is supported in the US only. To purchase phone numbers, ensure that:

    • The associated Azure subscription billing address is located in the United States. You cannot move a resource to another subscription at this time.
    • Your Communication Services resource is provisioned in the United States data location. You cannot move a resource to another data location at this time.
  • When a phone number is released, the phone number will not be released or able to be repurchased until the end of the billing cycle.

  • When a Communication Services resource is deleted, the phone numbers associated with that resource will be automatically released at the same time.

Next steps

In this quickstart you learned how to:

  • Purchase a phone number
  • Manage your phone number
  • Release a phone number