Network Preferences

| API | Portal |

API

Although Telnyx Wireless SIM cards are configured to connect to the best available network across the globe, it is possible that the SIM will not connect to the network that you are expecting it to connect to. If this is the case, it is often times quite a time consuming task to manually configure your modem to preference the network of your choice. The most common way to do this is via AT commands. AT commands can be difficult to work with and especially difficult to use when communicating with a SIM remotely.

The SIM card network preferences feature allows you to define the networks that your SIM card should prioritize during connection. The reasons you might want to this are varied, to mention a few:

  • SIM cards need to connect to the lowest latency network.
  • SIM cards need to connect to the cheapest network.
  • SIM cards need to connect to a mobile operator that has a better signal.

To give you full control over the priority order of networks on your Telnyx SIM, Telnyx provides an interface for updating the networks preference list on your SIM via OTA (over-the-air) updates. OTA updates are often times used by network providers to update the configrations on their SIMs remotely. Telnyx provides resources so you can make similar updates to your SIMs using our APIs while abstracting some of the complexities that require specific understanding of the SIM card architecture. You can view the API specifications for this API here.

Below we detail how to manage your SIM card network preferences via the OTA updates API:

  1. Select your mobile operator networks
  2. Find your SIM cards
  3. Defining SIM card network preferences
  4. Checking your network preferences
  5. Removing your custom network preferences

Select Your Networks

Telnyx has a set of available networks that can be preferred over others. This list is managed by Telnyx and may change over time to support more networks. The mobile operator networks list can be accessed via API using the GET /v2/mobileoperatornetworks endpoint.

Once you find the mobile operator networks that you would like to prioritize be sure to save their IDs. We'll need them later.

Find Your SIM Cards

Next we'll need to get the SIM cards that we'd like to update.

Use the GET /v2/sim_cards endpoint to search and find the SIM cards you want to configure and store their IDs as well. You can filter this endpoint by ICCIDs, SIM card groups ids, and by other filter parameters.

Defining SIM Card Network Preferences

Before we apply the network preferences to our SIMs here are a few noteworthy tips:

  • You don't need to set these configs to make your SIMs connect to the network, these are custom configurations.
  • The operations here are asynchronous and may take up to 10 minutes to apply.
  • The OTA update will only be applied if the SIM cards are connected to a network, we won't be able to reach them otherwise.
  • If a prioritized network is not available, the SIM will attempt to connect to the next prioritized network. If the SIM cannot connect to any of the prioritized networks, it will connect to whichever network has the strongest signal.
  • The maximum number of networks that can be prioritized per SIM is 30.
  • New network preferences can only be issued when the SIM card doesn't have any in-progress OTA updates.

The object used to update a SIM's network preferences is called the mobileoperatornetworks_preferences parameter and it consists of the following structure:

Copy
Copied
{
    "mobile_operator_networks_preferences": [
        {
            "mobile_operator_network_id": "<id>",
            "priority": 0
        },
        {
            "mobile_operator_network_id": "<id>",
            "priority": 1
        },
        {
            "mobile_operator_network_id": "<id>",
            "priority": 2
        }
    ]
}

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

Every network operator ID you've selected in stage number one of this walkthrough should get injected into the above object as the value for the mobileoperatornetwork_id key. It's important to note that the priority needs to be ordered correctly starting with 0.

The PUT /v2/simcards/{id}/networkpreferences endpoint is what we will use to update the network preferences on your SIMs. That's an upsert API and it will either create new configs or update the existing ones on your SIM card.

This API response will return the current state of the preferences and also returns the latest OTA update resource issued so that you can keep track of it.

Checking Your Network Preferences

You can check your SIM network preferences using the GET /v2/simcards/{id}/networkpreferences endpoint. This API, as mentioned before, will give you the current state of your SIM, but it also allows you to check the latest OTA updates related to it. This way you can check if there's an OTA update in-progress for the related SIM card.

You can also search and check OTA updates using the OTA API: GET /v2/ota_updates

Removing Your Custom Network Preferences

In case you don't want or don't need the defined preferences anymore, you can use the DELETE /v2/simcards/{id}/networkpreferences API to remove them. This will also generate an OTA update that will delete the network preferences resource from your SIM.

But don't worry, your SIM will still be able to connect to the network by using its own default definitions.

Portal

This guide will walk you through setting your network preferences by using our portal UI.

  1. To start, insert the SIM card into a known-working device and sign into your portal account here .
  2. Select the “Wireless” tab located on the left side of your screen.

Wireless Tab

  1. Select the “SIM Groups” tab. Here, you will see a list of SIM card groups tied to your account.

SIM Groups Tab

  1. Click the "SIM Cards" tab, place a checkmark next to the SIM card ICCID number that you want to work with, and click “Manage SIM cards."

SIM Cards

  1. Use the “Mobile Network Operator Preferences” dropdown menu to select the carrier you want to use for SIM card to use. Click “Apply.”

Network Preferences

  1. You can check the status of the OTA update by clicking on the ICCID ID of the SIM card.

OTA Updates