diff --git a/site/docs/numbers/hostingNumbers.mdx b/site/docs/numbers/hostingNumbers.mdx index 74e0f4f8c..6f67b4367 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,42 @@ 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. -Line Options feature management is **NOT** available for Phone numbers that have been imported for use with Hosted Messaging. +:::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 +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. +::: -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 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. -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 +77,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 +121,181 @@ 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 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 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 + +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 a subscription. +Please follow the [How to setup Notification Webhook](/docs/numbers/webhooks/orderWebhook) guide for more information. + +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) -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. +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. 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 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. -### Request URL - -POST https://dashboard.bandwidth.com/api/accounts/{accountId}/importTnOrders/{orderId}/loas +:::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. +::: -### Request Parameters +### Examples: -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 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) 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": {