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

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.

.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
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.