Hosted SMS

Overview

Hosted SMS allows you to bring your own number onto the Telnyx platform for SMS and MMS use only. The number remains with the current voice provider for voice, but routes all inbound and outbound SMS and MMS messages through the Telnyx network.

This is especially useful for landline numbers that normally would not have messaging capabilities. Telnyx can supplement the voice capabilities of that number by adding messaging capabilities to it without affecting the voice at all.

Hosted numbers must go through a check to ensure that you are the authorized user for that number and that you have the authority to make changes to the number's messaging routing.

In order for us to do the verification, we need two things, a signed Letter of Authorization (LOA) and the most recent bill from your current voice provider clearly showing your information and the number to be hosted with Telnyx.

Note
Hosting numbers with Telnyx is not the same as porting a number, but they both have a similar process.

Note
Not all numbers are capable of being Hosted with Telnyx.

cURL

Setting up your first Hosted SMS number

Check phone number eligibility for hosted messaging

Before creating a hosted SMS order, you can check if your phone numbers are eligible for hosted messaging. Remember to encode the phone numbers in the URL. For example, +13125550001 becomes %2B13125550001.

curl -X GET \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  "https://api.telnyx.com/v2/messaging_hosted_number_orders/eligibility_numbers_check?phone_numbers=%2B13125550001,%2B553125550002"

Example response

{
  "data": {
    "phone_numbers": [
      {
        "detail": "Phone number is eligible for hosted messaging",
        "phone_number": "+13125550001",
        "eligible": true,
        "eligible_status": "eligible"
      },
      {
        "detail": "Phone number is not a valid US number",
        "phone_number": "+553125550002",
        "eligible": false,
        "eligible_status": "number_is_not_a_us_number"
      }
    ]
  }
}

Note
The eligibility check returns a status for each phone number. Only numbers with "eligible": true and "eligible_status": "eligible" can be used for hosted messaging. Possible status values and descriptions are included in the eligibility check table.

Table of eligible statuses for Hosted SMS Order

eligible_status	description
billing_account_check_failed	Billing check failed. Try again or check billing.
billing_account_is_abolished	Account is abolished in billing.
eligible	Number is eligible for creating a Hosted SMS order.
number_can_not_be_active_in_your_account	It does not allow active numbers in your account.
number_can_not_be_in_telnyx	Number already exists on the Telnyx platform. It cannot be hosted.
number_can_not_be_repeated	It does not allow repeated numbers.
number_can_not_be_wireless	It does not allow wireless numbers.
number_can_not_hosted_with_a_telnyx_subscriber	Number is hosted with a Telnyx subscriber. It cannot be hosted.
number_is_not_a_us_number	It does not allow numbers outside the United States.
number_is_not_a_valid_routing_number	Number is not a valid local routing number.
number_is_not_in_e164_format	Number must be in the E.164 format.
numbers_can_not_be_validated	Numbers could not be validated. Try again or contact support.

Create a hosted SMS order

This creates a new hosted sms number order:

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  -d '{"messaging_profile_id":"16fd2706-8baf-433b-82eb-8c7fada847da", "phone_numbers":["+13125550001"]}' \
  "https://api.telnyx.com/v2/messaging_hosted_number_orders"

Example response

{
    "record_type": "messaging_hosted_number_order",
    "id": "7d9b9fdc-d073-4c3d-9c74-bf0622b3830c",
    "messaging_profile_id": "16fd2706-8baf-433b-82eb-8c7fada847da",
    "status": "pending",
    "phone_numbers": [
        {
            "record_type": "messaging_hosted_number",
            "id": "bda67701-2c08-47ba-8242-f6e6b235cca8",
            "phone_number": "+13125550001",
            "status": "pending"
        }
    ]
}

Note
The numbers in this order are created in a pending status. They will remain that way until you validate the phone numbers and submit the necessary authorization documents). Once the Telnyx team reviews and approves your order, the status will change to successful.

If there is a problem with the order request, the error statuses are the same of the eligibility check table. You can check the eligible_status field in the response to see the reason for the error.

Validate phone numbers

Note
This is a pre requirement for Uploading authorization documents.

You need to validate the phone numbers in your order. This is done by sending two requests (API references: 1, 2), one for create the verification codes and the other is to validate the verification codes.

1. Create the verification codes

The first request generates the verification codes for the phone numbers in your order. The verification codes are sent to the respective phone numbers.

Request:

curl --request POST \
  --url https://api.telnyx.com/v2/messaging_hosted_number_orders/5fcf6884-6c1b-45e4-89b8-5fba9e6c60be/verification_codes \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "content-type: application/json" \
  --data '{
  "verification_method": "sms",
  "phone_numbers": ["+15005550108", "+15005550921"]
}'

You will receive a 201 without content if everything is ok and the verification codes are sent to the phone numbers. In this example, SMS codes will be sent +15005550108 and +15005550921.

2. Validate the verification codes

The second request validates the verification codes for the phone numbers in your order. The validation codes must be created in step 1.. They will be sent to the phone numbers given the verification method.

Request:

curl --request POST \
  --url https://api.telnyx.com/v2/messaging_hosted_number_orders/5fcf6884-6c1b-45e4-89b8-5fba9e6c60be/validation_codes \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "content-type: application/json" \
  --data '{
  "verification_codes": [
    {"phone_number": "+15005550108", "code": "87643"}, {"phone_number": "+15005550921", "code": "98276"}
  ]
}'

Response:

{
  "phone_numbers": [
    {
      "phone_number": "+15005550108",
      "status": "verified"
    },
    {
      "phone_number": "+15005550921",
      "status": "verified"
    }
  ],
  "order_id": "5fcf6884-6c1b-45e4-89b8-5fba9e6c60be"
}

You can receive either verified or rejected status for each phone number. If you receive a rejected status, please check the phone number and the verification code. If everything is correct, the status of your phone numbers are now in the ownership_successful.

Uploading authorization documents

Note
Validate phone numbers is pre requirement for this.

You need to upload two documents in PDF format:

Letter of Authorization
The most recent bill from your voice provider

curl -X POST \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --form "loa=@/path/to/loa" \
  --form "bill=@/path/to/bill" \
  "https://api.telnyx.com/v2/messaging_hosted_number_orders/{id}/actions/file_upload"

Example response

{
    "record_type": "messaging_hosted_number_order",
    "id": "7d9b9fdc-d073-4c3d-9c74-bf0622b3830c",
    "messaging_profile_id": "16fd2706-8baf-433b-82eb-8c7fada847da",
    "status": "pending"
}

Now that your order request has all the information needed, our team will review and activate the number(s) for you on the Telnyx platform.

Note
Right now, these numbers will not be visible in the Telnyx Portal. They will however be visible when using the Telnyx API.

.NET

Setting up your first Hosted SMS number

Create a hosted SMS order

This creates a new hosted sms number order:

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  -d '{"messaging_profile_id":"16fd2706-8baf-433b-82eb-8c7fada847da", "phone_numbers":["+13125550001"]}' \
  "https://api.telnyx.com/v2/messaging_hosted_number_orders"

Example response

{
    "record_type": "messaging_hosted_number_order",
    "id": "7d9b9fdc-d073-4c3d-9c74-bf0622b3830c",
    "messaging_profile_id": "16fd2706-8baf-433b-82eb-8c7fada847da",
    "status": "pending",
    "phone_numbers": [
        {
            "record_type": "messaging_hosted_number",
            "id": "bda67701-2c08-47ba-8242-f6e6b235cca8",
            "phone_number": "+13125550001",
            "status": "pending"
        }
    ]
}

Note
The numbers in this order are created in a pending status. They will remain that way until you submit the necessary authorization documents. Once the Telnyx team reviews your order and approves it, the status will change to successful.

Uploading authorization documents

You need to upload two documents in PDF format:

Letter of Authorization
The most recent bill from your voice provider

curl -X POST \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --form "loa=@/path/to/loa" \
  --form "bill=@/path/to/bill" \
  "https://api.telnyx.com/v2/messaging_hosted_number_orders/{id}/actions/file_upload"

Example response

{
    "record_type": "messaging_hosted_number_order",
    "id": "7d9b9fdc-d073-4c3d-9c74-bf0622b3830c",
    "messaging_profile_id": "16fd2706-8baf-433b-82eb-8c7fada847da",
    "status": "pending"
}

Now that your order request has all the information needed, our team will review and activate the number(s) for you on the Telnyx platform.

Note
Right now, these numbers will not be visible in the Telnyx Portal. They will however be visible when using the Telnyx API.

On the Mission Control Portal, click on to Numbers.
Navigate to Hosted SMS
Click on Add New Order

new hosted sms order

Enter the number(s) you wish to host with Telnyx in +E.164 format
The system will automatically check the eligibility of the entered phone numbers. Only eligible numbers can be used for hosted messaging.
Choose the Message Profile you'd like to add to the number(s)
Click on Create Order. You will automatically route to the next page where you need to upload your Authorization Documentation.

create hosted sms order

Upload your LOA
Upload your Bill
Click on Submit

upload files hosted sms order

Now that your order request has all the information needed, our team will review and activate the number(s) for you on the Telnyx platform.

Note
Right now, these numbers will not be visible in the Telnyx Portal. They will however be visible when using the Telnyx API.