Messaging + Porting

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.

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"
        }
    ]
}

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"
        },
...
}

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"
        },
...
}

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": []
        },
...
}

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.

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"
        },
...
}

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"
    }
}

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.

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, our Messaging Ops team will be notified and alerted automatically to review and resolve any issues with your porting order. They will likely need to escalate with the losing carrier. This can typically take up to 72 hours to resolve.

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"
        },
...
}

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"
    }
}

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"
        },
...
}

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"
    }
}

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.

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

Another way to avoid downtime is to port SMS to Telnyx prior to porting the phone number in.

To port SMS only, you can submit a Hosted SMS request. Please create a Hosted SMS request at least 4 days prior to the scheduled FOC date/time. You can follow these steps:

1. Create a Hosted SMS request for your phone numbers

2. Create a porting order. Request a FOC date at least 4 business days into the future.

3. If all goes well, the Hosted SMS request should be completed in less than 4 business days. SMS only will port and be active at Telnyx

4. When the scheduled FOC date/time arrives, voice ports in and the phone numbers are fully activated on your Telnyx account. Both voice and SMS are routing through Telnyx, and you should experience no downtime.

For more information on hosted SMS, please check out this support article.

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.

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.

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.

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.

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.

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.