From 64652bd15c87defc9b7b0a51ca455810aa6e37bf Mon Sep 17 00:00:00 2001 From: msafronenko Date: Thu, 29 Sep 2022 16:48:37 +0300 Subject: [PATCH 1/3] How to host phone numbers for messaging --- site/docs/numbers/hostingNumbers.mdx | 381 +++++++++++++-------------- site/specs-temp/numbers.json | 2 +- 2 files changed, 178 insertions(+), 205 deletions(-) diff --git a/site/docs/numbers/hostingNumbers.mdx b/site/docs/numbers/hostingNumbers.mdx index 74e0f4f8c..488b8a03b 100644 --- a/site/docs/numbers/hostingNumbers.mdx +++ b/site/docs/numbers/hostingNumbers.mdx @@ -1,6 +1,6 @@ --- id: hostingNumbers -title: Hosting Numbers +title: How to host phone numbers for messaging slug: /numbers/guides/hostingNumbers description: How to host numbers for messaging using the Bandwidth APIs keywords: @@ -30,34 +30,43 @@ export const Highlight = ({children, color}) => ( ); -This walks through how to programmatically import Phone Numbers to your account for use with Bandwidth's Messaging Products. +In this guide we will show you how to programmatically import Phone Numbers to your account for use with Bandwidth's Messaging Products. +:::info Line Options feature management is **NOT** available for Phone numbers that have been imported for use with Hosted Messaging. +::: -![import_remove_tns](@site/static/img/docs-diagrams/numbers/import-tn-flow.png) +## Check for Importability -## Polling vs. Webhooks +[Check TNs portability API](../../../../apis/numbers#tag/accounts/operation/RetrieveOrder) endpoint validates whether or not Bandwidth +can host the number for messaging. +:::info +Please note that a valid response from this endpoint does not ensure that the +messaging traffic will be routed to Bandwidth—there are many factors with the other carriers that could cause them +to withhold messaging ownership rights on a number. +::: -Hosted Messaging Orders in the Bandwidth Dashboard are asynchronous when creating an "order". The orders are then processed and the order status is updated asynchronously. Bandwidth recommends configuring your account with a subscription instead of polling the order resource for ``. +To check TNs portability, make a POST request to our [Check TNs portability API](../../../../apis/numbers/#tag/Import-Tn/operation/CreateRequestImportTnChecker) endpoint. +This can be done through tools like [Postman](https://github.com/Bandwidth/postman) or in the cURL. -Order processing times can vary and are not guaranteed, so bandwidth does __not__ recommend setting a timeout on waiting for an order to show either `COMPLETE` or `FAILED` status, but instead relying on a webhook from an orders subscription. +### Examples: -## Check for Importability - -The `importTnChecker` endpoint validates whether or not Bandwidth can host the number for messaging. Please note that a valid response from this endpoint does not ensure that the messaging traffic will be routed to Bandwidth—there are many factors with the other carriers that could cause them to withhold messaging ownership rights on a number. + -### Request URL -POST https://dashboard.bandwidth.com/api/accounts/{accountId}/importTnChecker + -### Examples +#### Request URL: -> Request +

POST https://dashboard.bandwidth.com/api/accounts/{accountId}/importTnChecker

```xml -POST https://dashboard.bandwidth.com/api/accounts/{accountId}/importTnChecker HTTP/1.1 -Content-Type: application/xml; charset=utf-8 -Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= - 3032281000 @@ -69,23 +78,41 @@ Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= ``` + + + + +```curl +curl -X POST 'https://dashboard.bandwidth.com/api/accounts/{accountId}/importTnChecker' +-U '{userName}:{password}' +-H 'Content-Type: application/xml' +-d ' + + 3032281000 + 4109235436 + 4104685864 + + 486 + 500025 + ' +``` + + + + > Response ```xml -HTTP 200 OK -Content-Type: application/xml; charset=utf-8 - - - + 3032281000 19006 Bandwidth numbers cannot be imported by this account at this time. - + 4109235436 4104685864 @@ -95,233 +122,179 @@ Content-Type: application/xml; charset=utf-8 ``` -## Create importTnOrder +## Create Import TN Order -After validating the numbers are able to be imported, create a POST request to create the order to import the phone numbers in to your Bandwidth account. +After validating numbers which are able to be imported, you can create the order to import the phone numbers in to your Bandwidth account. To do that you must +make a POST request to our [Create Import TN Order API](../../../../apis/numbers/#tag/Import-Tn/operation/CreateImportTnOrder) endpoint. +This can be done through tools like [Postman](https://github.com/Bandwidth/postman) or in the cURL. -### Request URL -POST https://dashboard.bandwidth.com/api/accounts/{accountId}/importTnOrders +### Examples: -### Request Parameters - -| Parameter | Required | Description | -|:-------------------------|:---------|:------------------------------------------------------------------------------------------------------------------------------------------| -| `` | No | Internal customer order id for tracking the order. Only alphanumeric values, dashes and spaces are allowed. Max length is 40 characters. | -| `` | Yes | Subscriber business / customer name. | -| `` | Yes | Street address number. | -| `` | Yes | Street name. | -| `` | Yes | City. | -| `` | Yes | Two letter state code. | -| `` | Yes | Zip code. | -| `` | Yes | First and last name of person who authorized LOA. | -| `` | Yes | Ten digit phone number with no dots or dashes. One or more is required. Use a PhoneNumber tag for each phone number in the list. | -| `` | Yes | See section on Sites | -| `` | No | See section on SIP Peers | + + -### Examples +#### Request URL: -> Request +

POSThttps://dashboard.bandwidth.com/api/accounts/{accountId}/importTnOrders

```xml -POST https://dashboard.bandwidth.com/api/accounts/{accountId}/importTnOrders HTTP/1.1 -Content-Type: application/xml; charset=utf-8 -Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= - - marktestorders - 14413 - 521952 - - ABC Inc. - - 11235 - Back - Denver - CO - 27541 - Canyon - - - markmacc - - 3032281000 - 3032280004 - - -``` - -> Response - -```xml -HTTP/1.1 201 Created -Content-Type: application/xml; charset=utf-8 -Location: https://dashboard.bandwidth.com/api/accounts/{accountId}/importTnOrders/{orderId} - - - - - marktestorders - 2018-01-20T02:59:54.000Z - 9900012 - {username} - b05de7e6-0cab-4c83-81bb-9379cba8efd0 - 2018-01-20T02:59:54.000Z - 202 - 520565 - + marktestorders + 14413 + 521952 + ABC Inc. - 11235 - Back - Denver - CO - 27541 - Canyon + 11235 + Back + Denver + CO + 27541 + Canyon - - markmacc - + + markmacc + 3032281000 3032280004 - - PROCESSING - - - + + ``` -## Fetching importTnOrders Information - -A GET request to an existing importTnOrder will return it's status as well as any information originally used to create the order. - -### Request URL -GET https://dashboard.bandwidth.com/api/accounts/{accountId}/importTnOrders/{orderId} - -### Examples - - - + -ImportTnOrder Status Webhook -:::info -This is a webhook that bandwidth sends to _your_ server upon order completion/failure - there is no need to poll the resource if using this recommended method. -::: - -```xml -POST your_url.com/webhookService HTTP/1.1 -Content-Type: application/xml; charset=utf-8 - - - - ... - importtnorders - b05de7e6-0cab-4c83-81bb-9379cba8efd0 - ... - COMPLETE - Import TN order processing has started. - ... - + + +```curl +curl -X POST 'https://dashboard.bandwidth.com/api/accounts/{accountId}/importTnOrders' +-U '{userName}:{password}' +-H 'Content-Type: application/xml' +-d ' + marktestorders + 14413 + 521952 + + ABC Inc. + + 11235 + Back + Denver + CO + 27541 + Canyon + + + markmacc + + 3032281000 + 3032280004 + + ' ``` - - -Poll Order Information -> Request - -```http -GET https://dashboard.bandwidth.com/api/accounts/{accountId}/importTnOrders/b05de7e6-0cab-4c83-81bb-9379cba8efd0 HTTP/1.1 -Content-Type: application/xml; charset=utf-8 -Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= -``` + > Response ```xml -HTTP 200 OK -Content-Type: application/xml; charset=utf-8 - - - - 2019-08-28T13:09:11.192Z - 9900674 - mmacchioni - b05de7e6-0cab-4c83-81bb-9379cba8efd0 - 2019-08-28T13:09:26.295Z - 14419 - - BANDWDITH - - 900 - Main Campus Dr. - Raleigh - NC - 27606 - Wake - United States - Service - - - Mark Macchioni - - 9195041533 - - COMPLETE - - 521967 - + + + marktestorders + 2018-01-20T02:59:54.000Z + 9900012 + {username} + b05de7e6-0cab-4c83-81bb-9379cba8efd0 + 2018-01-20T02:59:54.000Z + 202 + 520565 + + ABC Inc. + + 11235 + Back + Denver + CO + 27541 + Canyon + + + markmacc + + 3032281000 + 3032280004 + + PROCESSING + + + ``` - - +## Fetch Order Status -## Upload Letter of Authorization (LOA) +Since the Import TN order is asynchronous, Bandwidth recommends configuring your account with a subscription instead of polling the order resource for `OrderStatus`. +Order processing times can vary and are not guaranteed, so bandwidth does __not__ recommend setting a timeout on waiting for an order to show either `COMPLETE` or `FAILED` status, but instead relying on a webhook from an orders subscription. +Please follow the [How to setup Notification Webhook](/docs/numbers/webhooks/orderWebhook) guide for more information. -For **completed** orders, Bandwidth requires a completed Subscriber "Letter of Authorization" (LOA) from the phone number user. The LOA file is used in the case there is a dispute to ensure the phone number had permission to be enabled for hosted messaging for Bandwidth. +Otherwise, you can make GET request to [Fetch Import TN Order status API](../../../../apis/numbers/#tag/Import-Tn/operation/ReadImportTnOrder) endpoint to poll the order status. -You are able to keep the LOA file within your own system, or upload the file to Bandwidth as part of the `importTnOrder` path. +## Upload Letter of Authorization (LOA) -### Request URL +For **completed** orders, Bandwidth requires a completed Subscriber "Letter of Authorization" (LOA) from the phone number user. +The LOA file is used in the case there is a dispute to ensure the phone number had permission to be enabled for hosted messaging for Bandwidth. -POST https://dashboard.bandwidth.com/api/accounts/{accountId}/importTnOrders/{orderId}/loas +You are able to keep the LOA file within your own system, or upload the file to Bandwidth as part of the `importTnOrder` path. +To upload load file, make a POST request to [Import TN Order loas API](../../../../../apis/numbers/#tag/Import-Tn/operation/CreateImportTnOrderLoas) endpoint. +This can be done through tools like [Postman](https://github.com/Bandwidth/postman) or in the cURL. -### Request Parameters +:::info +The key attribute to a successful upload is to ensure that the headers are set correctly to support the **type** of the file upload. +::: -A POST request to the /loas resource will upload the file. The key attribute to a successful upload is to ensure that the headers are set correctly to support the _type_ of the file upload. +#### Request URL -### Examples +POST https://dashboard.bandwidth.com/api/accounts/{accountId}/importTnOrders/{orderId}/loas -> Request + -```http -POST https://dashboard.../{accountId}/importTnOrders/{orderId}/loas HTTP/1.1 -Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= -Accept: / -Accept-Encoding: gzip, deflate -Content-Type: application/pdf + -[file-content-as-body] +```curl +curl -X POST 'https://dashboard.bandwidth.com/api/accounts/{accountId}/importTnOrders/{orderId}/loas' +-U '{userName}:{password}' +-H 'Content-Type: application/pdf' +-H 'Accept-Encoding: gzip, deflate' +-H 'Accept: /' +-d [file-content-as-body] ``` + + > Response ```xml -HTTP/1.1 201 Created -Content-Type: application/xml; charset=utf-8 - - 63097af1-37ae-432f-8a0d-9b0e6517a35b-1429550165581.pdf 0 LOA file uploaded successfully for order 63097af1-37ae-432f-8a0d-9b0e6517a35b ``` + +## Where to next? +Now that you have learned how to search and order numbers, check out some of the other available actions in our guides: +- [How to search your numbers](/docs/numbers/guides/manage-inventory/searchingNumbers) diff --git a/site/specs-temp/numbers.json b/site/specs-temp/numbers.json index 41be21765..b4ef444d0 100644 --- a/site/specs-temp/numbers.json +++ b/site/specs-temp/numbers.json @@ -6494,7 +6494,7 @@ "application/xml": { "examples": { "example": { - "value": "\n\n\t 2\n\t \n\t\t 14\n\t\t 1\n\t\t CustomerOrderId\n\t\t systemUser\n\t\t 2019-01-24T11:08:09.770Z\n\t\t 2019-01-24T11:08:09.770Z\n\t\t import_tn_orders\n\t\t COMPLETE\n\t\t 211a103c-5f9c-4117-8833-c574bdc390fd\n\t \n\t \n\t\t 14\n\t\t 2\n\t\t CustomerOrderId\n\t\t systemUser\n\t\t 2019-01-24T10:43:16.934Z\n\t\t 2019-01-24T10:43:16.934Z\n\t\t import_tn_orders\n\t\t PARTIAL\n\t\t 8dc32f09-2329-4c73-b702-526f46b02712\n\t \n \n" + "value": "\n\n 2\n \n 14\n 1\n CustomerOrderId\n systemUser\n 2019-01-24T11:08:09.770Z\n 2019-01-24T11:08:09.770Z\n import_tn_orders\n COMPLETE\n 211a103c-5f9c-4117-8833-c574bdc390fd\n \n \n 14\n 2\n CustomerOrderId\n systemUser\n 2019-01-24T10:43:16.934Z\n 2019-01-24T10:43:16.934Z\n import_tn_orders\n PARTIAL\n 8dc32f09-2329-4c73-b702-526f46b02712\n \n" } }, "schema": { From d6dcaedbd5bb225c0441bd130790a648f37eacae Mon Sep 17 00:00:00 2001 From: msafronenko Date: Fri, 30 Sep 2022 13:08:06 +0300 Subject: [PATCH 2/3] How to host phone numbers for messaging requested comments --- site/docs/numbers/hostingNumbers.mdx | 29 ++++++++++++++-------------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/site/docs/numbers/hostingNumbers.mdx b/site/docs/numbers/hostingNumbers.mdx index 488b8a03b..ad623096f 100644 --- a/site/docs/numbers/hostingNumbers.mdx +++ b/site/docs/numbers/hostingNumbers.mdx @@ -30,24 +30,23 @@ export const Highlight = ({children, color}) => ( ); -In this guide we will show you how to programmatically import Phone Numbers to your account for use with Bandwidth's Messaging Products. +In this guide we will show you how to programmatically import phone numbers to your account for use with Bandwidth's Messaging Products. :::info -Line Options feature management is **NOT** available for Phone numbers that have been imported for use with Hosted Messaging. +Line options feature management is **NOT** available for phone numbers that have been imported for use with hosted messaging. ::: ## Check for Importability -[Check TNs portability API](../../../../apis/numbers#tag/accounts/operation/RetrieveOrder) endpoint validates whether or not Bandwidth -can host the number for messaging. +In order to determine whether or not Bandwidth can host a number for messaging, you must first check if they can be imported. :::info Please note that a valid response from this endpoint does not ensure that the messaging traffic will be routed to Bandwidth—there are many factors with the other carriers that could cause them to withhold messaging ownership rights on a number. ::: -To check TNs portability, make a POST request to our [Check TNs portability API](../../../../apis/numbers/#tag/Import-Tn/operation/CreateRequestImportTnChecker) endpoint. -This can be done through tools like [Postman](https://github.com/Bandwidth/postman) or in the cURL. +To check if your numbers can be imported for hosted messaging, make a POST request to our [Import TN Checker API](../../../../apis/numbers/#tag/Import-Tn/operation/CreateRequestImportTnChecker) endpoint. +This can be done through tools like [Postman](https://github.com/Bandwidth/postman) or cURL. ### Examples: @@ -124,9 +123,9 @@ curl -X POST 'https://dashboard.bandwidth.com/api/accounts/{accountId}/importTnC ## Create Import TN Order -After validating numbers which are able to be imported, you can create the order to import the phone numbers in to your Bandwidth account. To do that you must +After validating that your numbers are able to be imported, you can create the order to import the phone numbers into your Bandwidth account. To do that, you must make a POST request to our [Create Import TN Order API](../../../../apis/numbers/#tag/Import-Tn/operation/CreateImportTnOrder) endpoint. -This can be done through tools like [Postman](https://github.com/Bandwidth/postman) or in the cURL. +This can be done through tools like [Postman](https://github.com/Bandwidth/postman) or cURL. ### Examples: @@ -242,10 +241,10 @@ curl -X POST 'https://dashboard.bandwidth.com/api/accounts/{accountId}/importTnO ## Fetch Order Status Since the Import TN order is asynchronous, Bandwidth recommends configuring your account with a subscription instead of polling the order resource for `OrderStatus`. -Order processing times can vary and are not guaranteed, so bandwidth does __not__ recommend setting a timeout on waiting for an order to show either `COMPLETE` or `FAILED` status, but instead relying on a webhook from an orders subscription. +Order processing times can vary and are not guaranteed, so Bandwidth does __not__ recommend setting a timeout on waiting for an order to show either `COMPLETE` or `FAILED` status, but instead relying on a webhook from a subscription. Please follow the [How to setup Notification Webhook](/docs/numbers/webhooks/orderWebhook) guide for more information. -Otherwise, you can make GET request to [Fetch Import TN Order status API](../../../../apis/numbers/#tag/Import-Tn/operation/ReadImportTnOrder) endpoint to poll the order status. +Otherwise, you can make a GET request to [Fetch Import TN Order status API](../../../../apis/numbers/#tag/Import-Tn/operation/ReadImportTnOrder) endpoint to poll the order status. ## Upload Letter of Authorization (LOA) @@ -253,13 +252,15 @@ For **completed** orders, Bandwidth requires a completed Subscriber "Letter of A The LOA file is used in the case there is a dispute to ensure the phone number had permission to be enabled for hosted messaging for Bandwidth. You are able to keep the LOA file within your own system, or upload the file to Bandwidth as part of the `importTnOrder` path. -To upload load file, make a POST request to [Import TN Order loas API](../../../../../apis/numbers/#tag/Import-Tn/operation/CreateImportTnOrderLoas) endpoint. -This can be done through tools like [Postman](https://github.com/Bandwidth/postman) or in the cURL. +To upload load file, make a POST request to [Import TN Order LOAs API](../../../../../apis/numbers/#tag/Import-Tn/operation/CreateImportTnOrderLoas) endpoint. +This can be done through tools like [Postman](https://github.com/Bandwidth/postman) or cURL. :::info -The key attribute to a successful upload is to ensure that the headers are set correctly to support the **type** of the file upload. +The key attribute to a successful upload is to ensure that the headers: **Content-Type**, **Accept-Encoding** and **Accept** are set correctly to support the **type** of the file upload. ::: +### Examples: + #### Request URL POST https://dashboard.bandwidth.com/api/accounts/{accountId}/importTnOrders/{orderId}/loas @@ -296,5 +297,5 @@ curl -X POST 'https://dashboard.bandwidth.com/api/accounts/{accountId}/importTnO ``` ## Where to next? -Now that you have learned how to search and order numbers, check out some of the other available actions in our guides: +Now that you have learned how to host phone numbers for messaging, check out some of the other available actions in our guides: - [How to search your numbers](/docs/numbers/guides/manage-inventory/searchingNumbers) From 18e67ab2e3681f4efc05220277f6494ccbadae64 Mon Sep 17 00:00:00 2001 From: msafronenko Date: Mon, 3 Oct 2022 11:33:42 +0300 Subject: [PATCH 3/3] How to host phone numbers for messaging requested comments --- site/docs/numbers/hostingNumbers.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/site/docs/numbers/hostingNumbers.mdx b/site/docs/numbers/hostingNumbers.mdx index ad623096f..6f67b4367 100644 --- a/site/docs/numbers/hostingNumbers.mdx +++ b/site/docs/numbers/hostingNumbers.mdx @@ -30,7 +30,7 @@ export const Highlight = ({children, color}) => ( ); -In this guide we will show you how to programmatically import phone numbers to your account for use with Bandwidth's Messaging Products. +In this guide, we will show you how to programmatically import phone numbers to your account for use with Bandwidth's Messaging Products. :::info Line options feature management is **NOT** available for phone numbers that have been imported for use with hosted messaging. @@ -252,11 +252,11 @@ For **completed** orders, Bandwidth requires a completed Subscriber "Letter of A The LOA file is used in the case there is a dispute to ensure the phone number had permission to be enabled for hosted messaging for Bandwidth. You are able to keep the LOA file within your own system, or upload the file to Bandwidth as part of the `importTnOrder` path. -To upload load file, make a POST request to [Import TN Order LOAs API](../../../../../apis/numbers/#tag/Import-Tn/operation/CreateImportTnOrderLoas) endpoint. +To upload a LOA file, make a POST request to [Import TN Order LOAs API](../../../../../apis/numbers/#tag/Import-Tn/operation/CreateImportTnOrderLoas) endpoint. This can be done through tools like [Postman](https://github.com/Bandwidth/postman) or cURL. :::info -The key attribute to a successful upload is to ensure that the headers: **Content-Type**, **Accept-Encoding** and **Accept** are set correctly to support the **type** of the file upload. +The key attribute to a successful upload is to ensure that the headers, **Content-Type**, **Accept-Encoding** and **Accept**, are set correctly to support the **type** of the file upload. ::: ### Examples: