Azure.Communication.PhoneNumbers 1.1.0

The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org. Prefix Reserved
There is a newer prerelease version of this package available.
See the version list below for details.
dotnet add package Azure.Communication.PhoneNumbers --version 1.1.0
NuGet\Install-Package Azure.Communication.PhoneNumbers -Version 1.1.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Azure.Communication.PhoneNumbers" Version="1.1.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Azure.Communication.PhoneNumbers --version 1.1.0
#r "nuget: Azure.Communication.PhoneNumbers, 1.1.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Azure.Communication.PhoneNumbers as a Cake Addin
#addin nuget:?package=Azure.Communication.PhoneNumbers&version=1.1.0

// Install Azure.Communication.PhoneNumbers as a Cake Tool
#tool nuget:?package=Azure.Communication.PhoneNumbers&version=1.1.0

Azure Communication Phone Numbers client library for .NET

Azure Communication Phone Numbers is managing phone numbers for Azure Communication Services.

Source code | Product documentation | Samples

Getting started

Install the package

Install the Azure Communication Phone Numbers client library for .NET with NuGet:

dotnet add package Azure.Communication.PhoneNumbers

Prerequisites

You need an Azure subscription and a Communication Service Resource to use this package.

To create a new Communication Service, you can use the Azure Portal, the Azure PowerShell, or the .NET management client library.

Key concepts

This SDK provides functionality to easily manage direct offer and direct routing numbers.

The direct offer numbers come in two types: Geographic and Toll-Free. Geographic phone plans are phone plans associated with a location, whose phone numbers' area codes are associated with the area code of a geographic location. Toll-Free phone plans are phone plans not associated location. For example, in the US, toll-free numbers can come with area codes such as 800 or 888. They are managed using the PhoneNumbersClient

The direct routing feature enables connecting your existing telephony infrastructure to ACS. The configuration is managed using the SipRoutingClient, which provides methods for setting up SIP trunks and voice routing rules, in order to properly handle calls for your telephony subnet.

Authenticate the client

Clients can be authenticated using connection string acquired from an Azure Communication Resources in the Azure Portal.

// Get a connection string to our Azure Communication resource.
var connectionString = "<connection_string>";
var client = new PhoneNumbersClient(connectionString);
// Get a connection string to Azure Communication resource.
var connectionString = "<connection_string>";
var client = new SipRoutingClient(connectionString);

Clients also have the option to authenticate with Azure Active Directory Authentication. For more on this topic, see Azure Identity.

// Get an endpoint to our Azure Communication resource.
var endpoint = new Uri("<endpoint_url>");
TokenCredential tokenCredential = new DefaultAzureCredential();
client = new PhoneNumbersClient(endpoint, tokenCredential);
// Get an endpoint to our Azure Communication resource.
var endpoint = new Uri("<endpoint_url>");
TokenCredential tokenCredential = new DefaultAzureCredential();
client = new SipRoutingClient(endpoint, tokenCredential);

Phone numbers client

Phone number types overview

Phone numbers come in two types: Geographic and Toll-Free. Geographic phone plans are phone plans associated with a location, whose phone numbers' area codes are associated with the area code of a geographic location. Toll-Free phone plans are phone plans not associated location. For example, in the US, toll-free numbers can come with area codes such as 800 or 888.

All geographic phone plans within the same country are grouped into a phone plan group with a Geographic phone number type. All Toll-Free phone plans within the same country are grouped into a phone plan group.

Searching, purchasing and releasing phone numbers

Phone numbers can be searched through the search creation API by providing an area code, quantity of phone numbers, application type, phone number type and capabilities. The provided quantity of phone numbers will be reserved for ten minutes and can be purchased within this time. If the search is not purchased, the phone numbers will become available to others after ten minutes. If the search is purchased, then the phone numbers are acquired for the Azure resources.

Phone numbers can also be released using the release API.

SIP routing client

Direct routing feature allows connecting customer-provided telephony infrastructure to Azure Communication Resources. In order to setup routing configuration properly, customer needs to supply the SIP trunk configuration and SIP routing rules for calls. SIP routing client provides the necessary interface for setting this configuration.

When a call is made, the system tries to match the destination number with regex number patterns of defined routes. The first route to match the number will be selected. The order of regex matching is the same as the order of routes in configuration, therefore the order of routes matters. Once a route is matched, the call is routed to the first trunk in the route's trunks list. If the trunk is not available, next trunk in the list is selected.

Thread safety

We guarantee that all client instance methods are thread-safe and independent of each other (guideline). This ensures that the recommendation of reusing client instances is always safe, even across threads.

Additional concepts

Client options | Accessing the response | Long-running operations | Handling failures | Diagnostics | Mocking | Client lifetime

Examples

PhoneNumbersClient

Creating a PhoneNumbersClient

To create a new PhoneNumbersClient you need a connection string to the Azure Communication Services resource that you can get from the Azure Portal once you have created the resource.

You can set connectionString based on an environment variable, a configuration setting, or any way that works for your application.

// Get a connection string to our Azure Communication resource.
var connectionString = "<connection_string>";
var client = new PhoneNumbersClient(connectionString);
Search phone numbers

Phone numbers need to be searched before they can be purchased. Search is a long running operation that can be started by StartSearchAvailablePhoneNumbers function that returns an SearchAvailablePhoneNumbersOperation object. SearchAvailablePhoneNumbersOperation can be used to update status of the operation and to check for completeness.

var capabilities = new PhoneNumberCapabilities(calling: PhoneNumberCapabilityType.None, sms: PhoneNumberCapabilityType.Outbound);

var searchOperation = await client.StartSearchAvailablePhoneNumbersAsync(countryCode, PhoneNumberType.TollFree, PhoneNumberAssignmentType.Application, capabilities);
await searchOperation.WaitForCompletionAsync();
Purchase phone numbers

Phone numbers can be acquired through purchasing a search.

var purchaseOperation = await client.StartPurchasePhoneNumbersAsync(searchOperation.Value.SearchId);
await purchaseOperation.WaitForCompletionResponseAsync();
Listing purchased phone numbers

You can list all phone numbers that have been purchased for your resource.

var purchasedPhoneNumbers = client.GetPurchasedPhoneNumbersAsync();

await foreach (var phoneNumber in purchasedPhoneNumbers)
{
    Console.WriteLine($"Phone number: {phoneNumber.PhoneNumber}, monthly cost: {phoneNumber.Cost}");
}
Release phone numbers

If you no longer need a phone number you can release it.

var purchasedPhoneNumber = "<purchased_phone_number>";
var releaseOperation = await client.StartReleasePhoneNumberAsync(purchasedPhoneNumber);
await releaseOperation.WaitForCompletionResponseAsync();
await WaitForCompletionResponseAsync(releaseOperation);

SipRoutingClient

Retrieve SIP trunks and routes

Get the list of currently configured trunks or routes.

var trunksResponse = await client.GetTrunksAsync();
var routesResponse = await client.GetRoutesAsync();
Replace SIP trunks and routes

Replace the list of currently configured trunks or routes.

// The service will not allow trunks that are used in any of the routes to be deleted, therefore first set the routes as empty list, and then update the routes.
var newTrunks = "<new_trunks_list>";
var newRoutes = "<new_routes_list>";
await client.SetRoutesAsync(new List<SipTrunkRoute>());
await client.SetTrunksAsync(newTrunks);
await client.SetRoutesAsync(newRoutes);
Manage single trunk

SIP trunks can be managed separately by using the SipRoutingClient to retrieve, set or delete a single trunk.

Retrieve single trunk
// Get trunk object, based on it's FQDN.
var fqdnToRetrieve = "<fqdn>";
var trunkResponse = await client.GetTrunkAsync(fqdnToRetrieve);
Set single trunk
// Set function will either modify existing item or add new item to the collection.
// The trunk is matched based on it's FQDN.
var trunkToSet = "<trunk_to_set>";
await client.SetTrunkAsync(trunkToSet);
Delete single trunk
// Deletes trunk with supplied FQDN.
var fqdnToDelete = "<fqdn>";
await client.DeleteTrunkAsync(fqdnToDelete);

Troubleshooting

Next steps

Read more about managing phone numbers

Read more about direct routing

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit cla.microsoft.com.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on Azure.Communication.PhoneNumbers:

Package Downloads
RenetConsulting.Sdk.Communication.Azure

Package Description

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.3.0-beta.5 344 3/15/2024
1.3.0-beta.4 102 2/22/2024
1.3.0-beta.3 463 2/2/2024
1.3.0-beta.2 1,279 9/1/2023
1.3.0-beta.1 105 8/29/2023
1.2.0-beta.1 839 8/8/2023
1.1.0 67,190 3/28/2023
1.1.0-beta.3 709 1/10/2023
1.1.0-beta.2 974 3/31/2022
1.1.0-beta.1 484 1/20/2022
1.0.1 60,776 5/25/2021
1.0.0 2,314 4/26/2021
1.0.0-beta.6 868 3/29/2021
1.0.0-beta.5 303 3/10/2021