Azure Communication Administration client library for .NET
Server Version: Identity client: 2020-07-20-preview2
Phone number administration client: 2020-07-20-preview1
Azure Communication Administration is managing tokens and phone numbers for Azure Communication Services.
Source code | Package (NuGet) | Product documentation
Getting started
Install the package
Install the Azure Communication Administration client library for .NET with NuGet:
dotnet add package Azure.Communication.Administration --version 1.0.0-beta.1
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 or the .NET management client library.
Authenticate the client
Administration 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 CommunicationIdentityClient(connectionString);
Key concepts
CommunicationIdentityClient
provides the functionalities to manage user access tokens: creating new ones, renewing and revoking them.
Examples
Create a new identity
Response<CommunicationUser> userResponse = await client.CreateUserAsync();
CommunicationUser user = userResponse.Value;
Console.WriteLine($"User id: {user.Id}");
Issuing or Refreshing a token for an existing identity
Response<CommunicationUserToken> tokenResponse = await client.IssueTokenAsync(user, scopes: new[] { CommunicationTokenScope.Chat });
string token = tokenResponse.Value.Token;
DateTimeOffset expiresOn = tokenResponse.Value.ExpiresOn;
Console.WriteLine($"Token: {token}");
Console.WriteLine($"Expires On: {expiresOn}");
Revoking a user's tokens
In case a user's tokens are compromised or need to be revoked:
Response revokeResponse = client.RevokeTokens(
user,
issuedBefore: DateTimeOffset.UtcNow.AddDays(-1) /* optional */);
Deleting a user
Response deleteResponse = client.DeleteUser(user);
Troubleshooting
All User token service operations will throw a RequestFailedException on failure.
// Get a connection string to our Azure Communication resource.
var connectionString = "<connection_string>";
var client = new CommunicationIdentityClient(connectionString);
try
{
Response<CommunicationUser> response = await client.CreateUserAsync();
}
catch (RequestFailedException ex)
{
Console.WriteLine(ex.Message);
}
Phone plans overview
Phone plans 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 and acquiring numbers
Phone numbers search can be performed through the search creation API by providing a phone plan id, an area code and quantity of phone numbers. The provided quantity of phone numbers will be reserved for ten minutes. This search of phone numbers can either be cancelled or purchased. If the search is cancelled, then the phone numbers will become available to others. If the search is purchased, then the phone numbers are acquired for the Azure resources.
Configuring / Assigning numbers
Phone numbers can be assigned to a callback URL via the configure number API. As part of the configuration, you will need an acquired phone number, callback URL and application id.
Examples
Get list of the countries that are supported by the service
string connectionString = "<connection_string>";
PhoneNumberAdministrationClient client = new PhoneNumberAdministrationClient(connectionString);
Pageable<PhoneNumberCountry> countries = client.GetAllSupportedCountries();
foreach (var country in countries)
{
Console.WriteLine($"Country code {country.CountryCode}, Country name: {country.LocalizedName}");
}
Get phone plan groups
Phone plan groups come in two types, Geographic and Toll-Free.
var phonePlanGroups = client.GetPhonePlanGroups(countryCode);
foreach (var group in phonePlanGroups)
{
Console.WriteLine($"PhonePlanGroupId {group.PhonePlanGroupId}, Name: {group.LocalizedName}, PhoneNumberType: {group.PhoneNumberType}");
}
Get phone plans
Unlike Toll-Free phone plans, area codes for Geographic Phone Plans are empty. Area codes are found in the Area Codes API.
var phonePlans = client.GetPhonePlans(countryCode, planGroupId);
foreach (var plan in phonePlans)
{
Console.WriteLine($"PhonePlanId {plan.PhonePlanId}, Name: {plan.LocalizedName}");
Console.WriteLine("Top 10 area codes");
foreach (var areaCode in plan.AreaCodes.Take(10).ToList())
{
Console.WriteLine($"Area code: {areaCode}");
}
}
Get location options
For Geographic phone plans, you can query the available geographic locations. The locations options are structured like the geographic hierarchy of a country. For example, the US has states and within each state are cities.
var locationOptionsResponse = client.GetPhonePlanLocationOptions(countryCode, phonePlanGroupId, phonePlanId);
var locationOprions = locationOptionsResponse.Value.LocationOptions;
Console.WriteLine($"LabelId: {locationOprions.LabelId}, LabelName: {locationOprions.LabelName}");
foreach(var locationOption in locationOprions.Options)
{
Console.WriteLine($"Name: {locationOption.Name}, Value: {locationOption.Value}");
}
Get area codes
Fetching area codes for geographic phone plans will require the the location options queries set. You must include the chain of geographic locations traversing down the location options object returned by the GetLocationOptions API.
var areaCodesResponse = client.GetAllAreaCodes(locationType, countryCode, planId, locationOptionsQueries);
var areaCodes = areaCodesResponse.Value;
foreach(var primaryAreaCode in areaCodes.PrimaryAreaCodes)
{
Console.WriteLine("Primary area code" + primaryAreaCode);
}
foreach (var secondaryAreaCode in areaCodes.SecondaryAreaCodes)
{
Console.WriteLine("Secondary area code" + secondaryAreaCode);
}
Create search
var searchOptions = new CreateSearchOptions(displayName, description, plans, areaCode) { Quantity = 1 };
var createSearchResponse = client.CreateSearch(searchOptions);
Console.WriteLine($"Search result: SearchId: {createSearchResponse.Value.SearchId}");
Purchase search
client.PurchaseSearch(searchId);
Configure phone number
var pstnConfiguration = new PstnConfiguration("<url>");
var phoneNumber = new PhoneNumber("<phone_number>");
client.ConfigureNumber(pstnConfiguration, phoneNumber);
Next steps
Read more about Communication user access tokens
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.