This is the API V2 documentation. To switch out of beta revert back to our API V1.

Open SidemenuDocs
Docs
Close Sidemenu

Network Preferencesnetwork-preferences

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

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 Networksselect-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/mobile_operator_networksAPI 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 Cardsfind-your-sim-cards

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

Use the GET /v2/sim_cardsAPI 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 Preferencesdefining-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 mobile_operator_networks_preferences parameter and it consists of the following structure:

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

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 mobile_operator_network_id key. It's important to note that the priority needs to be ordered correctly starting with 0.

The PUT /v2/sim_cards/{id}/network_preferencesAPI 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 Preferenceschecking-your-network-preferences

You can check your SIM network preferences using the GET /v2/sim_cards/{id}/network_preferencesAPI 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_updatesAPI

Removing Your Custom Network Preferencesremoving-your-custom-network-preferences

In case you don't want or don't need the defined preferences anymore, you can use the DELETE /v2/sim_cards/{id}/network_preferencesAPI 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.

Was this page helpful?was-this-page-helpful