# Azure Communication Phone Numbers Package client library for Python
Azure Communication Phone Numbers client package is used to administer Phone Numbers.
## _Disclaimer_
_Azure SDK Python packages support for Python 2.7 has ended 01 January 2022. For more information and questions, please refer to https://github.com/Azure/azure-sdk-for-python/issues/20691_
# Getting started
### Prerequisites
- Python 3.7 or later is required to use this package.
- You must have an [Azure subscription](https://azure.microsoft.com/free/)
- A deployed Communication Services resource. You can use the [Azure Portal](https://docs.microsoft.com/azure/communication-services/quickstarts/create-communication-resource?tabs=windows&pivots=platform-azp) or the [Azure PowerShell](https://docs.microsoft.com/powershell/module/az.communication/new-azcommunicationservice) to set it up.
### Install the package
Install the Azure Communication Phone Numbers client library for Python with [pip](https://pypi.org/project/pip/):
```bash
pip install azure-communication-phonenumbers
```
## 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.
### Initializing Client
Client can be initialized using the AAD authentication.
```python
import os
from azure.communication.phonenumbers import PhoneNumbersClient
from azure.identity import DefaultAzureCredential
endpoint = "https://<RESOURCE_NAME>.communication.azure.com"
# To use Azure Active Directory Authentication (DefaultAzureCredential) make sure to have your
# AZURE_TENANT_ID, AZURE_CLIENT_ID and AZURE_CLIENT_SECRET as env variables.
phone_numbers_client = PhoneNumbersClient(endpoint, DefaultAzureCredential())
```
```python
import os
from azure.communication.phonenumbers.siprouting import SipRoutingClient
from azure.identity import DefaultAzureCredential
endpoint = "https://<RESOURCE_NAME>.communication.azure.com"
# To use Azure Active Directory Authentication (DefaultAzureCredential) make sure to have your
# AZURE_TENANT_ID, AZURE_CLIENT_ID and AZURE_CLIENT_SECRET as env variables.
sip_routing_client = SipRoutingClient(endpoint, DefaultAzureCredential())
```
Another option is to initialize the client using connection string of the resource.
```python
# You can find your connection string from your resource in the Azure Portal
import os
from azure.communication.phonenumbers import PhoneNumbersClient
connection_str = "endpoint=ENDPOINT;accessKey=KEY"
phone_numbers_client = PhoneNumbersClient.from_connection_string(connection_str)
```
```python
# You can find your connection string from your resource in the Azure Portal
import os
from azure.communication.phonenumbers.siprouting import SipRoutingClient
connection_str = "endpoint=ENDPOINT;accessKey=KEY"
sip_routing_client = SipRoutingClient.from_connection_string(connection_str)
```
### Phone numbers client
#### Phone number types overview
Phone numbers come in two types; Geographic and Toll-Free. Geographic phone numbers are phone numbers associated with a location, whose area codes are associated with the area code of a geographic location. Toll-Free phone numbers are phone numbers with no associated location. For example, in the US, toll-free numbers can come with area codes such as 800 or 888.
#### Searching and Purchasing and Releasing 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, 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.
## Examples
### PhoneNumbersClient
#### Get All Purchased Phone Numbers
Lists all of your purchased phone numbers
```python
purchased_phone_numbers = phone_numbers_client.list_purchased_phone_numbers()
for acquired_phone_number in purchased_phone_numbers:
print(acquired_phone_number.phone_number)
```
#### Get Purchased Phone Number
Gets the information from the specified phone number
```python
result = phone_numbers_client.get_purchased_phone_number("<phone number>")
print(result.country_code)
print(result.phone_number)
```
### Long Running Operations
The Phone Number Client supports a variety of long running operations that allow indefinite polling time to the functions listed down below.
#### Search for Available Phone Number
You can search for available phone numbers by providing the capabilities of the phone you want to acquire, the phone number type, the assignment type, and the country code. It's worth mentioning that for the toll-free phone number type, proving the area code is optional.
The result of the search can then be used to purchase the number in the corresponding API.
```python
capabilities = PhoneNumberCapabilities(
calling = PhoneNumberCapabilityType.INBOUND,
sms = PhoneNumberCapabilityType.INBOUND_OUTBOUND
)
poller = phone_numbers_client.begin_search_available_phone_numbers(
"US",
PhoneNumberType.TOLL_FREE,
PhoneNumberAssignmentType.APPLICATION,
capabilities,
area_code ="833", # Area code is optional for toll-free numbers
quantity = 2, # Quantity is optional. If not set, default is 1
polling = True
)
search_result = poller.result()
```
#### Purchase Phone Numbers
The result of your search can be used to purchase the specified phone numbers. This can be done by passing the `search_id` from the search response to the purchase phone number API.
```python
purchase_poller = phone_numbers_client.begin_purchase_phone_numbers(
search_result.search_id,
polling=True
)
```
#### Release Phone Number
Releases an acquired phone number.
```python
poller = self.phone_number_client.begin_release_phone_number(
"<phone number>",
polling = True
)
```
#### Updating Phone Number Capabilities
Updates the specified phone number capabilities for Calling and SMS to one of:
- `PhoneNumberCapabilityType.NONE`
- `PhoneNumberCapabilityType.INBOUND`
- `PhoneNumberCapabilityType.OUTBOUND`
- `PhoneNumberCapabilityType.INBOUND_OUTBOUND`
```python
poller = self.phone_number_client.begin_update_phone_number_capabilities(
"<phone number>",
PhoneNumberCapabilityType.OUTBOUND,
PhoneNumberCapabilityType.INBOUND_OUTBOUND,
polling = True
)
```
### SipRoutingClient
#### Retrieve SIP trunks and routes
Get the list of currently configured trunks or routes.
```python
trunks = sip_routing_client.list_trunks()
for trunk in trunks:
print(trunk.fqdn)
print(trunk.sip_signaling_port)
routes = sip_routing_client.list_routes()
for route in routes:
print(route.name)
print(route.description)
print(route.number_pattern)
for trunk_fqdn in route.trunks:
print(trunk_fqdn)
```
#### Replace SIP trunks and routes
Replace the list of currently configured trunks or routes with new values.
```python
new_trunks = [SipTrunk(fqdn="sbs1.contoso.com", sip_signaling_port=1122), SipTrunk(fqdn="sbs2.contoso.com", sip_signaling_port=1123)]
new_routes = [SipTrunkRoute(name="First rule", description="Handle numbers starting with '+123'", number_pattern="\+123[0-9]+", trunks=["sbs1.sipconfigtest.com"])]
sip_routing_client.set_trunks(new_trunks)
sip_routing_client.set_routes(new_routes)
```
#### Retrieve single trunk
```python
trunk = sip_routing_client.get_trunk("sbs1.contoso.com")
```
#### Set single trunk
```python
# Set function will either modify existing item or add new item to the collection.
# The trunk is matched based on it's FQDN.
new_trunk = SipTrunk(fqdn="sbs3.contoso.com", sip_signaling_port=5555)
sip_routing_client.set_trunk(new_trunk)
```
#### Delete single trunk
```python
sip_routing_client.delete_trunk("sbs1.contoso.com")
```
# Troubleshooting
The Phone Numbers Administration client will raise exceptions defined in [Azure Core][azure_core].
# Next steps
## More sample code
Please take a look at the [samples](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/communication/azure-communication-phonenumbers/samples) directory for detailed examples of how to use this library.
## Provide Feedback
If you encounter any bugs or have suggestions, please file an issue in the [Issues](https://github.com/Azure/azure-sdk-for-python/issues) section of the project
# 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 https://cla.microsoft.com.
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the
PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
<!-- LINKS -->
[azure_core]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/core/azure-core/README.md
Raw data
{
"_id": null,
"home_page": "https://github.com/Azure/azure-sdk-for-python",
"name": "azure-communication-phonenumbers",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "",
"author": "Microsoft Corporation",
"author_email": "azuresdkengsysadmins@microsoft.com",
"download_url": "https://files.pythonhosted.org/packages/19/6b/7e8f06bc56c385866c69b736bfcef7748af748783c8434ec38d643339a4b/azure-communication-phonenumbers-1.1.0.zip",
"platform": null,
"description": "# Azure Communication Phone Numbers Package client library for Python\n\nAzure Communication Phone Numbers client package is used to administer Phone Numbers.\n\n## _Disclaimer_\n\n_Azure SDK Python packages support for Python 2.7 has ended 01 January 2022. For more information and questions, please refer to https://github.com/Azure/azure-sdk-for-python/issues/20691_\n\n# Getting started\n### Prerequisites\n- Python 3.7 or later is required to use this package.\n- You must have an [Azure subscription](https://azure.microsoft.com/free/)\n- A deployed Communication Services resource. You can use the [Azure Portal](https://docs.microsoft.com/azure/communication-services/quickstarts/create-communication-resource?tabs=windows&pivots=platform-azp) or the [Azure PowerShell](https://docs.microsoft.com/powershell/module/az.communication/new-azcommunicationservice) to set it up.\n### Install the package\nInstall the Azure Communication Phone Numbers client library for Python with [pip](https://pypi.org/project/pip/):\n\n```bash\npip install azure-communication-phonenumbers\n```\n\n## Key concepts\n\nThis SDK provides functionality to easily manage `direct offer` and `direct routing` numbers.\n\nThe `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.\nThey are managed using the `PhoneNumbersClient`\n\nThe `direct routing` feature enables connecting your existing telephony infrastructure to ACS.\nThe 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.\n\n### Initializing Client\nClient can be initialized using the AAD authentication.\n\n```python\nimport os\nfrom azure.communication.phonenumbers import PhoneNumbersClient\nfrom azure.identity import DefaultAzureCredential\n\nendpoint = \"https://<RESOURCE_NAME>.communication.azure.com\"\n# To use Azure Active Directory Authentication (DefaultAzureCredential) make sure to have your\n# AZURE_TENANT_ID, AZURE_CLIENT_ID and AZURE_CLIENT_SECRET as env variables.\nphone_numbers_client = PhoneNumbersClient(endpoint, DefaultAzureCredential())\n```\n\n```python\nimport os\nfrom azure.communication.phonenumbers.siprouting import SipRoutingClient\nfrom azure.identity import DefaultAzureCredential\n\nendpoint = \"https://<RESOURCE_NAME>.communication.azure.com\"\n# To use Azure Active Directory Authentication (DefaultAzureCredential) make sure to have your\n# AZURE_TENANT_ID, AZURE_CLIENT_ID and AZURE_CLIENT_SECRET as env variables.\nsip_routing_client = SipRoutingClient(endpoint, DefaultAzureCredential())\n```\n\nAnother option is to initialize the client using connection string of the resource.\n\n```python\n# You can find your connection string from your resource in the Azure Portal\nimport os\nfrom azure.communication.phonenumbers import PhoneNumbersClient\n\nconnection_str = \"endpoint=ENDPOINT;accessKey=KEY\"\nphone_numbers_client = PhoneNumbersClient.from_connection_string(connection_str)\n```\n\n```python\n# You can find your connection string from your resource in the Azure Portal\nimport os\nfrom azure.communication.phonenumbers.siprouting import SipRoutingClient\n\nconnection_str = \"endpoint=ENDPOINT;accessKey=KEY\"\nsip_routing_client = SipRoutingClient.from_connection_string(connection_str)\n```\n\n### Phone numbers client\n\n#### Phone number types overview\n\nPhone numbers come in two types; Geographic and Toll-Free. Geographic phone numbers are phone numbers associated with a location, whose area codes are associated with the area code of a geographic location. Toll-Free phone numbers are phone numbers with no associated location. For example, in the US, toll-free numbers can come with area codes such as 800 or 888.\n\n#### Searching and Purchasing and Releasing numbers\n\nPhone 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.\n\nPhone numbers can also be released using the release API.\n\n### SIP routing client\n\nDirect 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.\n\nWhen a call is made, 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.\nOnce 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.\n\n## Examples\n\n### PhoneNumbersClient\n\n#### Get All Purchased Phone Numbers\n\nLists all of your purchased phone numbers\n\n```python\npurchased_phone_numbers = phone_numbers_client.list_purchased_phone_numbers()\nfor acquired_phone_number in purchased_phone_numbers:\n print(acquired_phone_number.phone_number)\n```\n\n#### Get Purchased Phone Number\n\nGets the information from the specified phone number\n\n```python\nresult = phone_numbers_client.get_purchased_phone_number(\"<phone number>\")\nprint(result.country_code)\nprint(result.phone_number)\n```\n\n### Long Running Operations\n\nThe Phone Number Client supports a variety of long running operations that allow indefinite polling time to the functions listed down below.\n\n#### Search for Available Phone Number\n\nYou can search for available phone numbers by providing the capabilities of the phone you want to acquire, the phone number type, the assignment type, and the country code. It's worth mentioning that for the toll-free phone number type, proving the area code is optional.\nThe result of the search can then be used to purchase the number in the corresponding API.\n\n```python\ncapabilities = PhoneNumberCapabilities(\n calling = PhoneNumberCapabilityType.INBOUND,\n sms = PhoneNumberCapabilityType.INBOUND_OUTBOUND\n )\npoller = phone_numbers_client.begin_search_available_phone_numbers(\n \"US\",\n PhoneNumberType.TOLL_FREE,\n PhoneNumberAssignmentType.APPLICATION,\n capabilities,\n area_code =\"833\", # Area code is optional for toll-free numbers\n quantity = 2, # Quantity is optional. If not set, default is 1\n polling = True\n)\nsearch_result = poller.result()\n```\n\n#### Purchase Phone Numbers\n\nThe result of your search can be used to purchase the specified phone numbers. This can be done by passing the `search_id` from the search response to the purchase phone number API.\n\n```python\npurchase_poller = phone_numbers_client.begin_purchase_phone_numbers(\n search_result.search_id,\n polling=True\n)\n```\n\n#### Release Phone Number\n\nReleases an acquired phone number.\n\n```python\npoller = self.phone_number_client.begin_release_phone_number(\n \"<phone number>\",\n polling = True\n)\n```\n\n#### Updating Phone Number Capabilities\n\nUpdates the specified phone number capabilities for Calling and SMS to one of:\n\n- `PhoneNumberCapabilityType.NONE`\n- `PhoneNumberCapabilityType.INBOUND`\n- `PhoneNumberCapabilityType.OUTBOUND`\n- `PhoneNumberCapabilityType.INBOUND_OUTBOUND`\n\n```python\npoller = self.phone_number_client.begin_update_phone_number_capabilities(\n \"<phone number>\",\n PhoneNumberCapabilityType.OUTBOUND,\n PhoneNumberCapabilityType.INBOUND_OUTBOUND,\n polling = True\n)\n```\n\n### SipRoutingClient\n\n#### Retrieve SIP trunks and routes\n\nGet the list of currently configured trunks or routes.\n\n```python\ntrunks = sip_routing_client.list_trunks()\nfor trunk in trunks:\n print(trunk.fqdn)\n print(trunk.sip_signaling_port)\nroutes = sip_routing_client.list_routes()\nfor route in routes:\n print(route.name)\n print(route.description)\n print(route.number_pattern)\n for trunk_fqdn in route.trunks:\n print(trunk_fqdn)\n```\n\n#### Replace SIP trunks and routes\n\nReplace the list of currently configured trunks or routes with new values.\n\n```python\nnew_trunks = [SipTrunk(fqdn=\"sbs1.contoso.com\", sip_signaling_port=1122), SipTrunk(fqdn=\"sbs2.contoso.com\", sip_signaling_port=1123)]\nnew_routes = [SipTrunkRoute(name=\"First rule\", description=\"Handle numbers starting with '+123'\", number_pattern=\"\\+123[0-9]+\", trunks=[\"sbs1.sipconfigtest.com\"])]\nsip_routing_client.set_trunks(new_trunks)\nsip_routing_client.set_routes(new_routes)\n```\n\n#### Retrieve single trunk\n\n```python\ntrunk = sip_routing_client.get_trunk(\"sbs1.contoso.com\")\n```\n\n#### Set single trunk\n\n```python\n# Set function will either modify existing item or add new item to the collection.\n# The trunk is matched based on it's FQDN.\nnew_trunk = SipTrunk(fqdn=\"sbs3.contoso.com\", sip_signaling_port=5555)\nsip_routing_client.set_trunk(new_trunk)\n```\n\n#### Delete single trunk\n\n```python\nsip_routing_client.delete_trunk(\"sbs1.contoso.com\")\n```\n\n# Troubleshooting\nThe Phone Numbers Administration client will raise exceptions defined in [Azure Core][azure_core].\n\n# Next steps\n## More sample code\n\nPlease take a look at the [samples](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/communication/azure-communication-phonenumbers/samples) directory for detailed examples of how to use this library.\n\n## Provide Feedback\n\nIf you encounter any bugs or have suggestions, please file an issue in the [Issues](https://github.com/Azure/azure-sdk-for-python/issues) section of the project\n\n# Contributing\nThis project welcomes contributions and suggestions. Most contributions require you to agree to a\nContributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.\n\nWhen you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the\nPR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.\n\nThis project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).\nFor more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.\n\n<!-- LINKS -->\n[azure_core]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/core/azure-core/README.md\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Microsoft Azure Communication Phone Numbers Client Library for Python",
"version": "1.1.0",
"project_urls": {
"Bug Reports": "https://github.com/Azure/azure-sdk-for-python/issues",
"Homepage": "https://github.com/Azure/azure-sdk-for-python",
"Source": "https://github.com/Azure/azure-sdk-for-python"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0db94c45e531d4e611570503e86274c6fe84325546b66aee78b709011929da3e",
"md5": "683af4a729d6bfc4296c2231f71b880e",
"sha256": "029e4bdc3bb0dfab1ee7f44e76cdcd55d1f7be266afd9c424ca4516553f3df9e"
},
"downloads": -1,
"filename": "azure_communication_phonenumbers-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "683af4a729d6bfc4296c2231f71b880e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 119954,
"upload_time": "2023-03-28T21:36:46",
"upload_time_iso_8601": "2023-03-28T21:36:46.989772Z",
"url": "https://files.pythonhosted.org/packages/0d/b9/4c45e531d4e611570503e86274c6fe84325546b66aee78b709011929da3e/azure_communication_phonenumbers-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "196b7e8f06bc56c385866c69b736bfcef7748af748783c8434ec38d643339a4b",
"md5": "cbff4664cbcbdad7dfbda10d0c8d53a6",
"sha256": "b6e22e7078d0a929cd10148de95bc33af356181f7697dd60303c1f701da333af"
},
"downloads": -1,
"filename": "azure-communication-phonenumbers-1.1.0.zip",
"has_sig": false,
"md5_digest": "cbff4664cbcbdad7dfbda10d0c8d53a6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 172587,
"upload_time": "2023-03-28T21:36:49",
"upload_time_iso_8601": "2023-03-28T21:36:49.283614Z",
"url": "https://files.pythonhosted.org/packages/19/6b/7e8f06bc56c385866c69b736bfcef7748af748783c8434ec38d643339a4b/azure-communication-phonenumbers-1.1.0.zip",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-03-28 21:36:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Azure",
"github_project": "azure-sdk-for-python",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "azure-communication-phonenumbers"
}
JSON
