|
| 1 | +# Azure Communication PhoneNumbers client library for .NET |
| 2 | + |
| 3 | +> Server Version: |
| 4 | +
|
| 5 | +> Phone number client: 2020-07-20-preview1 |
| 6 | +
|
| 7 | +Azure Communication PhoneNumbers is managing phone numbers for Azure Communication Services. |
| 8 | + |
| 9 | +[Source code][source] <!--| [Package (NuGet)][package]--> | [Product documentation][product_docs] | [Samples][source_samples] |
| 10 | + |
| 11 | +## Getting started |
| 12 | + |
| 13 | +### Install the package |
| 14 | + |
| 15 | +Install the Azure Communication PhoneNumbers client library for .NET with [NuGet][nuget]: |
| 16 | + |
| 17 | +```Powershell |
| 18 | +dotnet add package Azure.Communication.PhoneNumbers --version 1.0.0-beta.3 |
| 19 | +``` |
| 20 | + |
| 21 | +### Prerequisites |
| 22 | + |
| 23 | +You need an [Azure subscription][azure_sub] and a [Communication Service Resource][communication_resource_docs] to use this package. |
| 24 | + |
| 25 | +To create a new Communication Service, you can use the [Azure Portal][communication_resource_create_portal], the [Azure PowerShell][communication_resource_create_power_shell], or the [.NET management client library][communication_resource_create_net]. |
| 26 | + |
| 27 | +<!-- |
| 28 | +Here's an example using the Azure CLI: |
| 29 | +
|
| 30 | +```Powershell |
| 31 | +[To be ADDED] |
| 32 | +``` |
| 33 | +--> |
| 34 | + |
| 35 | +### Key concepts |
| 36 | + |
| 37 | +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. |
| 38 | + |
| 39 | +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. |
| 40 | + |
| 41 | +### Authenticate the client |
| 42 | + |
| 43 | +Phone Number clients can be authenticated using connection string acquired from an Azure Communication Resources in the [Azure Portal][azure_portal]. |
| 44 | + |
| 45 | +```C# Snippet:CreatePhoneNumberAdministrationClient |
| 46 | +// Get a connection string to our Azure Communication resource. |
| 47 | +var connectionString = "<connection_string>"; |
| 48 | +var client = new PhoneNumberAdministrationClient(connectionString); |
| 49 | +``` |
| 50 | + |
| 51 | +Phone Number clients also have the option to authenticate with Azure Active Directory Authentication. With this option, |
| 52 | +`AZURE_CLIENT_SECRET`, `AZURE_CLIENT_ID` and `AZURE_TENANT_ID` environment variables need to be set up for authentication. |
| 53 | + |
| 54 | +```C# Snippet:CreatePhoneNumberWithTokenCredential |
| 55 | +var endpoint = "<endpoint_url>"; |
| 56 | +TokenCredential tokenCredential = new DefaultAzureCredential(); |
| 57 | +var client = new PhoneNumberAdministrationClient(new Uri(endpoint), tokenCredential); |
| 58 | +``` |
| 59 | + |
| 60 | +### Reserving and acquiring numbers |
| 61 | + |
| 62 | +Phone numbers reservation can be performed through the reservation 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 reservation of phone numbers can either be cancelled or purchased. If the reservation is cancelled, then the phone numbers will become available to others. If the reservation is purchased, then the phone numbers are acquired for the Azure resources. |
| 63 | + |
| 64 | +### Configuring / Assigning numbers |
| 65 | + |
| 66 | +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. |
| 67 | + |
| 68 | +## Examples |
| 69 | + |
| 70 | +### Get list of the countries that are supported by the service |
| 71 | + |
| 72 | +```C# |
| 73 | +string connectionString = "<connection_string>"; |
| 74 | +PhoneNumberAdministrationClient client = new PhoneNumberAdministrationClient(connectionString); |
| 75 | +Pageable<PhoneNumberCountry> countries = client.GetAllSupportedCountries(); |
| 76 | + |
| 77 | +foreach (var country in countries) |
| 78 | +{ |
| 79 | + Console.WriteLine($"Country code {country.CountryCode}, Country name: {country.LocalizedName}"); |
| 80 | +} |
| 81 | +``` |
| 82 | + |
| 83 | +### Get phone plan groups |
| 84 | + |
| 85 | +Phone plan groups come in two types, Geographic and Toll-Free. |
| 86 | + |
| 87 | +```C# |
| 88 | +var phonePlanGroups = client.GetPhonePlanGroups(countryCode); |
| 89 | + |
| 90 | +foreach (var group in phonePlanGroups) |
| 91 | +{ |
| 92 | + Console.WriteLine($"PhonePlanGroupId {group.PhonePlanGroupId}, Name: {group.LocalizedName}, PhoneNumberType: {group.PhoneNumberType}"); |
| 93 | +} |
| 94 | +``` |
| 95 | + |
| 96 | +### Get phone plans |
| 97 | + |
| 98 | +Unlike Toll-Free phone plans, area codes for Geographic Phone Plans are empty. Area codes are found in the Area Codes API. |
| 99 | + |
| 100 | +```C# |
| 101 | +var phonePlans = client.GetPhonePlans(countryCode, planGroupId); |
| 102 | + |
| 103 | +foreach (var plan in phonePlans) |
| 104 | +{ |
| 105 | + Console.WriteLine($"PhonePlanId {plan.PhonePlanId}, Name: {plan.LocalizedName}"); |
| 106 | + Console.WriteLine("Top 10 area codes"); |
| 107 | + foreach (var areaCode in plan.AreaCodes.Take(10).ToList()) |
| 108 | + { |
| 109 | + Console.WriteLine($"Area code: {areaCode}"); |
| 110 | + } |
| 111 | +} |
| 112 | +``` |
| 113 | + |
| 114 | +### Get location options |
| 115 | + |
| 116 | +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. |
| 117 | + |
| 118 | +```C# |
| 119 | +var locationOptionsResponse = client.GetPhonePlanLocationOptions(countryCode, phonePlanGroupId, phonePlanId); |
| 120 | +var locationOprions = locationOptionsResponse.Value.LocationOptions; |
| 121 | + |
| 122 | +Console.WriteLine($"LabelId: {locationOprions.LabelId}, LabelName: {locationOprions.LabelName}"); |
| 123 | +foreach(var locationOption in locationOprions.Options) |
| 124 | +{ |
| 125 | + Console.WriteLine($"Name: {locationOption.Name}, Value: {locationOption.Value}"); |
| 126 | +} |
| 127 | +``` |
| 128 | + |
| 129 | +### Get area codes |
| 130 | + |
| 131 | +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. |
| 132 | + |
| 133 | +```C# |
| 134 | +var areaCodesResponse = client.GetAllAreaCodes(locationType, countryCode, planId, locationOptionsQueries); |
| 135 | +var areaCodes = areaCodesResponse.Value; |
| 136 | + |
| 137 | +foreach(var primaryAreaCode in areaCodes.PrimaryAreaCodes) |
| 138 | +{ |
| 139 | + Console.WriteLine("Primary area code" + primaryAreaCode); |
| 140 | +} |
| 141 | + |
| 142 | +foreach (var secondaryAreaCode in areaCodes.SecondaryAreaCodes) |
| 143 | +{ |
| 144 | + Console.WriteLine("Secondary area code" + secondaryAreaCode); |
| 145 | +} |
| 146 | +``` |
| 147 | + |
| 148 | +### Create reservation |
| 149 | + |
| 150 | +```C# |
| 151 | +var reservationOptions = new CreateReservationOptions(displayName, description, plans, areaCode) { Quantity = 1 }; |
| 152 | +var reservationOperation = await client.StartReservationAsync(reservationOptions).ConfigureAwait(false); |
| 153 | +var reservationResponse = await reservationOperation.WaitForCompletionAsync().ConfigureAwait(false); |
| 154 | + |
| 155 | +Console.WriteLine($"ReservationId: {reservationResponse.Value.ReservationId}, Status {reservationResponse.Value.Status}"); |
| 156 | +``` |
| 157 | + |
| 158 | +### Purchase reservation |
| 159 | + |
| 160 | +```C# |
| 161 | +var reservationPurchaseOperation = await client.StartPurchaseReservationAsync(reservationId).ConfigureAwait(false); |
| 162 | +await reservationPurchaseOperation.WaitForCompletionAsync().ConfigureAwait(false); |
| 163 | +``` |
| 164 | + |
| 165 | +### Configure phone number |
| 166 | + |
| 167 | +```C# |
| 168 | +var pstnConfiguration = new PstnConfiguration("<url>"); |
| 169 | +var phoneNumber = new PhoneNumber("<phone_number>"); |
| 170 | +client.ConfigureNumber(pstnConfiguration, phoneNumber); |
| 171 | +``` |
| 172 | + |
| 173 | +### Release phone numbers |
| 174 | + |
| 175 | +```C# |
| 176 | +var releasePhoneNumberOperation = await client.StartReleasePhoneNumbersAsync(numbers).ConfigureAwait(false); |
| 177 | +await releasePhoneNumberOperation.WaitForCompletionAsync().ConfigureAwait(false); |
| 178 | + |
| 179 | +Console.WriteLine($"ReleaseId: {releasePhoneNumberOperation.Value.ReleaseId}, Status: {releasePhoneNumberOperation.Value.Status}"); |
| 180 | +``` |
| 181 | +## Troubleshooting |
| 182 | + |
| 183 | +## Next steps |
| 184 | + |
| 185 | +[Read more about Communication user access tokens][user_access_token] |
| 186 | + |
| 187 | +## Contributing |
| 188 | + |
| 189 | +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][cla]. |
| 190 | + |
| 191 | +This project has adopted the [Microsoft Open Source Code of Conduct][coc]. For more information see the [Code of Conduct FAQ][coc_faq] or contact [opencode@microsoft.com][coc_contact] with any additional questions or comments. |
| 192 | + |
| 193 | +<!-- LINKS --> |
| 194 | + |
| 195 | +[azure_sub]: https://azure.microsoft.com/free/ |
| 196 | +[azure_portal]: https://portal.azure.com |
| 197 | +[source]: https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/communication/Azure.Communication.PhoneNumbers/src |
| 198 | +[source_samples]: https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/communication/Azure.Communication.PhoneNumbers/samples |
| 199 | +[cla]: https://cla.microsoft.com |
| 200 | +[coc]: https://opensource.microsoft.com/codeofconduct/ |
| 201 | +[coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/ |
| 202 | +[coc_contact]: mailto:opencode@microsoft.com |
| 203 | +<!--[package]: https://www.nuget.org/packages/Azure.Communication.PhoneNumbers--> |
| 204 | +[product_docs]: https://docs.microsoft.com/azure/communication-services/overview |
| 205 | +[nuget]: https://www.nuget.org/ |
| 206 | +[communication_resource_docs]: https://docs.microsoft.com/azure/communication-services/quickstarts/create-communication-resource?tabs=windows&pivots=platform-azp |
| 207 | +[communication_resource_create_portal]: https://docs.microsoft.com/azure/communication-services/quickstarts/create-communication-resource?tabs=windows&pivots=platform-azp |
| 208 | +[communication_resource_create_power_shell]: https://docs.microsoft.com/powershell/module/az.communication/new-azcommunicationservice |
| 209 | +[communication_resource_create_net]: https://docs.microsoft.com/azure/communication-services/quickstarts/create-communication-resource?tabs=windows&pivots=platform-net |
0 commit comments