Skip to main content

Messaging + Porting

Background​

For local and toll-free phone numbers in the US and Canada, porting voice and porting messaging are two completely separate processes.

A porting order transitioning into a “ported” status indicates that voice has ported over to Telnyx. However, this status change does not take messaging into consideration at all. In some cases, it is possible that after a phone number ports, messaging will continue to route through the losing carrier for a period of time.

To understand this, let's take a step back. A NetNumber ID (NNID) is the identifier for the provider that owns the SMS routing of a telephone number. NetNumber manages NNIDs. A local or toll-free phone number in the US or Canada must always have an NNID assigned before sending and receiving messages.

At the FOC date/time when the phone number ports, the losing carrier is expected to release the NNID, and the phone number should update to the winning carrier’s NNID. As a result, both voice and messaging would be routed through the winning carrier. This is how porting works in the majority of cases.

If the losing carrier fails to release the NNID even after the phone number ports, the losing carrier will continue to send and receive messages for the phone number. There are generally three instances where this could occur:

  1. This may be similar to what is known as a porting "translations" issue. Once the port completes, the losing carrier may have unintentionally failed to release the NNID. It's possible there was an error or bug in the losing carrier’s internal systems. It’s also possible that their internal systems needed some additional time to recognize that the phone number was ported out and release the NNID.
  2. Some carriers have block policies in place such that if a phone number ports, they will be able to retain messaging for a brief period of time. The winning carrier needs to open a support ticket to have the NNID overridden from the losing carrier.
  3. You are planning on hosting your messaging elsewhere and only plan on porting over voice to Telnyx. In this case, the other carrier will reject any attempted NNID overrides.

Telnyx cannot guarantee that the losing carrier will immediately release the NNID when a phone number ports. Instead, Telnyx can provide additional visibility into when messaging successfully ports, and act swiftly when there are any issues with the messaging activation.

How to activate messaging​

1. Determine whether your phone number is messaging capable with Telnyx​

If Telnyx can support SMS for a phone number, then it is considered messaging capable.

To determine whether a phone number is messaging capable, check out the “messaging_capable” attribute in either the portability check, or on the porting order itself.

  • If the response includes “messaging_capable”: true, then Telnyx can support messaging for that phone number.
  • If the response includes “messaging_capable”: false, then Telnyx cannot support messaging for that phone number.

In the portability check:

Request:

curl --location --request POST 'https://api.telnyx.com/v2/portability_checks' \
--header 'Authorization: Bearer [REDACTED]' \
--header 'Content-Type: application/json' \
--data-raw '{
    "phone_numbers": [
        "{e.164 TN}"
    ]
}'

Response:

{
    "data": [
        {
            "carrier_name": "CELLCO PARTNERSHIP DBA VERIZON WIRELESS - MA",
            "fast_portable": true,
            "messaging_capable": true,
            "not_portable_reason": null,
            "phone_number": "{e.164 TN}",
            "phone_number_type": "mobile",
            "portable": true,
            "record_type": "portability_check_result"
        }
    ]
}

Note: After pasting the above content, Kindly check and remove any new line added

And in the porting order itself (most of the response is omitted for brevity):

Request:

curl --location --request GET 'https://api.telnyx.com/v2/porting_orders/{id}' \
--header 'Authorization: Bearer [REDACTED]' \
--header 'Content-Type: application/json' \

Response:

{
    "data": {
...
​​        "messaging": {
            "messaging_capable": true,
            "enable_messaging": null,
            "messaging_port_status": "pending"
        },
...
}

Note: After pasting the above content, Kindly check and remove any new line added

2. Turn on the messaging activation feature​

Porting has added a new (optional) messaging activation feature. How it works is:

  1. You elect to turn on the messaging activation feature for your porting order
  2. When the FOC date/time arrives and the order is ported, Telnyx will validate whether the messaging is with Telnyx or if it is still with the losing carrier.
  3. Telnyx will provide updates (through the api and through notifications) on when messaging has ported to Telnyx.

The feature is only available for orders containing messaging capable phone numbers. To turn it on, pass a PATCH v2/porting_orders/{id} request to update the "enable_messaging" attribute to true. For example:

Request:

curl --location --request PATCH 'https://api.telnyx.com/v2/porting_orders/{id}' \
--header 'Authorization: Bearer [REDACTED]' \
--header 'Content-Type: application/json' \
--data-raw '{
    "messaging": {
        "enable_messaging": true,
    }
}'

Response:

{
    "data": {
...
​​        "messaging": {
            "messaging_capable": true,
            "enable_messaging": true,
            "messaging_port_status": "pending"
        },
...
}

Note: After pasting the above content, Kindly check and remove any new line added

By enabling the feature, you will also be required to assign a messaging profile ID to the porting order. In doing so, every phone number on the order will have the messaging profile ID assigned to it upon porting.

To add a messaging profile ID to a porting order, you can pass the same PATCH v2/porting_orders/{id} and include the messaging_profile_id in the body of the request. For example:

Request:

curl --location --request PATCH 'https://api.telnyx.com/v2/porting_orders/{id}' \
--header 'Authorization: Bearer [REDACTED]' \
--header 'Content-Type: application/json' \
--data '{
    "phone_number_configuration": {
        "messaging_profile_id": "40017ca4-664e-48fa-a48b-dc64ab906c5d"
    }
}'

Response:

{
    "data": {
...
        "phone_number_configuration": {
            "connection_id": null,
            "messaging_profile_id": "40017ca4-664e-48fa-a48b-dc64ab906c5d",
            "tags": []
        },
...
}

Note: After pasting the above content, Kindly check and remove any new line added

3. API behavior prior to porting in​

Prior to the FOC date/time and the porting order transitioning into a “ported” status, the order will reflect "messaging_port_status": "pending".

Once the FOC date/time arrives and the porting order transitions into a “ported” status, the order will reflect "messaging_port_status": "activating". The order will remain in this state until Telnyx can verify that the messaging for all phone numbers on the order have ported.

4. Happy path: messaging ports to Telnyx at the FOC date/time​

In most cases, the losing carrier should release the NNID at the FOC date/time. In doing so, Telnyx can apply its own NNID and start to route your messages.

When this occurs, your porting order will update to reflect "messaging_port_status": ported, as shown in the example below:

Request:

curl --location --request GET 'https://api.telnyx.com/v2/porting_orders/{id}' \
--header 'Authorization: Bearer [REDACTED]' \
--header 'Content-Type: application/json' \

Response:

{
    "data": {
...
​​        "messaging": {
            "messaging_capable": true,
            "enable_messaging": true,
            "messaging_port_status": "ported"
        },
...
}

Note: After pasting the above content, Kindly check and remove any new line added

You will also receive a webhook notification (assuming you have webhook notifications turned on for port in events). See below for an example:

{
    "data": {
        "event_type": "porting_order.messaging_changed",
        "id": "af094e33-aa2b-4681-b28d-f26eb2318425",
        "occurred_at": "2023-09-15T18:53:59Z",
        "payload": {
            "customer_reference": "1234",
            "id": "8b616fef-5a92-4baf-b1ea-aa936a2c4032",
            "messaging": {
                "enable_messaging": true,
                "messaging_capable": true,
                "messaging_port_completed": true,
                "messaging_port_status": "ported"
            },
            "support_key": "sr_6ffeab"
        },
        "record_type": "event"
    },
    "meta": {
        "attempt": 1,
        "delivered_to": "https://webhook.site/8dd13307-8ea1-4efa-b5ff-a4b971dfcf32"
    }
}

Note: After pasting the above content, Kindly check and remove any new line added

And that’s it! At this point, both messaging and voice ported for your phone number(s). If you have any further issues, please reach out to customer support.

5. Sad path: messaging does not port to Telnyx at FOC date/time​

Your order transitioned into a “ported” status, and calls are successfully routing through Telnyx. However, the losing carrier failed to release messaging on one or more phone numbers.

When this occurs, your order will update to reflect "messaging_port_status": exception:

Request:

curl --location --request GET 'https://api.telnyx.com/v2/porting_orders/{id}' \
--header 'Authorization: Bearer [REDACTED]' \
--header 'Content-Type: application/json' \

Response:

{
    "data": {
...
​​        "messaging": {
            "messaging_capable": true,
            "enable_messaging": true,
            "messaging_port_status": "exception"
        },
...
}

Note: After pasting the above content, Kindly check and remove any new line added

And you will receive an accompanying webhook notification. See below for an example:

{
    "data": {
        "event_type": "porting_order.messaging_changed",
        "id": "af094e33-aa2b-4681-b28d-f26eb2318425",
        "occurred_at": "2023-09-15T18:53:59Z",
        "payload": {
            "customer_reference": "1234",
            "id": "8b616fef-5a92-4baf-b1ea-aa936a2c4032",
            "messaging": {
                "enable_messaging": true,
                "messaging_capable": true,
                "messaging_port_completed": true,
                "messaging_port_status": "exception"
            },
            "support_key": "sr_6ffeab"
        },
        "record_type": "event"
    },
    "meta": {
        "attempt": 1,
        "delivered_to": "https://webhook.site/8dd13307-8ea1-4efa-b5ff-a4b971dfcf32"
    }
}

Note: After pasting the above content, Kindly check and remove any new line added

Our Messaging Ops team will be alerted to review and resolve any issues with your porting order. They will likely need to escalate with the losing carrier.

When the issue is resolved and messaging for all phone numbers on the order is updated to a Telnyx NNID, the order will update to "messaging_port_status": "ported". See below for an example:

Request:

curl --location --request GET 'https://api.telnyx.com/v2/porting_orders/{id}' \
--header 'Authorization: Bearer [REDACTED]' \
--header 'Content-Type: application/json' \

Response:

{
    "data": {
...
​​        "messaging": {
            "messaging_capable": true,
            "enable_messaging": true,
            "messaging_port_status": "ported"
        },
...
}

Note: After pasting the above content, Kindly check and remove any new line added

And you will receive a webhook notification as well. See below for an example:

{
    "data": {
        "event_type": "porting_order.messaging_changed",
        "id": "af094e33-aa2b-4681-b28d-f26eb2318425",
        "occurred_at": "2023-09-15T18:53:59Z",
        "payload": {
            "customer_reference": "1234",
            "id": "8b616fef-5a92-4baf-b1ea-aa936a2c4032",
            "messaging": {
                "enable_messaging": true,
                "messaging_capable": true,
                "messaging_port_completed": true,
                "messaging_port_status": "ported"
            },
            "support_key": "sr_6ffeab"
        },
        "record_type": "event"
    },
    "meta": {
        "attempt": 1,
        "delivered_to": "https://webhook.site/8dd13307-8ea1-4efa-b5ff-a4b971dfcf32"
    }
}

Note: After pasting the above content, Kindly check and remove any new line added

And that’s it! At this point, both messaging and voice should have ported for your phone number(s). If you have any further issues, please reach out to customer support.

Edge case: partial messaging ports​

While a port order is in a "messaging_port_status": "exception" state, it is possible that only some phone numbers on the order failed to port.

In other words, lets say that you have a port order with 100 phone numbers. It is possible that 90 of the phone numbers ported messaging successfully at the FOC date/time, but the other 10 phone numbers failed to port messaging. This would be a partial SMS port. Since not every phone number on the order had SMS port successfully, the order will transition into a "messaging_port_status": "exception" state.

To check each individual phone number on an order, you can use the GET https://api.telnyx.com/v2/porting_phone_numbers request. There will be a "messaging_port_status" attribute for each listed phone number. Looking at the API response to the GET https://api.telnyx.com/v2/porting_phone_numbers request:

  • "messaging_port_status": "exception" indicates that the phone number failed to port messaging
  • "messaging_port_status": "ported" indicates that the phone number did port SMS successfully. Even if the port order itself is in a "messaging_port_status": "exception" state

Frequently Asked Questions (FAQ)​

FAQ: What if I plan on hosting messaging elsewhere? And I only want to port in voice to Telnyx?​

Do not update the porting order to reflect "enable_messaging": true. Leave the order as "enable_messaging": null. Additionally, do not associate a messaging profile ID to the porting order.

In doing so, Telnyx will ignore the messaging activation of the phone number. Telnyx will not attempt to override the NNID, or perform any other troubleshooting actions. The feature will remain turned off and the ”messaging” object will contain "messaging_port_status": “not_applicable” indefinitely.

If you decide later on that you no longer wish to host messaging elsewhere, check out this support article to see how to activate messaging.

FAQ: What if I am porting in a phone number that is not a US/CA local or US/CA toll-free phone number?​

You have nothing to worry about! If you are porting in a messaging capable phone number that is not a US/CA local or US/CA toll-free phone number, it is safe to assume that both voice and messaging have ported over when the order transitions into a “ported” status.

If you wish, for all ”messaging_capable” porting orders, you can still enable the feature by updating the order to reflect "enable_messaging": true. You will receive status updates with the “messaging_port_status” attribute, and any accompanying webhooks.

FAQ: My order indicates “messaging_port_status”: “exception”. What should I do?​

This indicates that one or more of the phone numbers on your port order are still routing SMS through the losing carrier. Telnyx is also aware of the issue and is escalating with the losing carrier. If possible, continue to route your messaging with the losing carrier until you receive a notification that messaging has ported over.

FAQ: How much time does it normally take before I receive confirmation that messaging is ported over?​

For US/CA local phone numbers, roughly 90% of port orders have messaging activated within 10 minutes of a phone number porting. The remaining 10% of phone numbers usually finish messaging port within 1-2 business days.

For US/CA toll-free phone numbers, messaging will usually port within 10 minutes of a phone number porting. However if it doesn’t activate within that 10 minute window, it may take 4-5 business days before messaging ports over.

For all other phone numbers, it is expected that messaging will port at the same time as voice.

FAQ: My order says that the messaging ported, but my numbers are failing to deliver messages. What is the issue?​

Please confirm that you have a working messaging profile ID associated with the phone number. If you do and you are still experiencing issues, please cut a support ticket for our team to investigate.

FAQ: Why can’t I update my order to turn on the messaging feature?​

Please confirm that the porting order shows "messaging_capable": true, and that the order is either in a draft, in-process or exception status. If those conditions are met and you are still unable to update the porting order, please reach out to our support team for further assistance.

On this page​