Skip to main content

API for interacting with Telstra's mobile services via cellular modem

Project description

Telstra Mobile API for Python

A potentially vain attempt at creating an API to interact with some of Telstra’s services for mobile. At present, this library handles:

  • Majority of key functionality for USSD via hardware modem
  • Some web-based prepaid account interrogation

Other Telstra services can be added later into the top-level telstra. namespace, potentially by other developers.


Install this library with pip install, make sure you have a supported 3G modem plugged in with a Telstra SIM card installed. See Install section later for full details.

An example is worth a thousand words, so let’s just jump straight into it.

from import autodetect_account
account = autodetect_account()
account = autodetect_account('0412345678')

# Detected via the network

# Access a session to #100#
ussd = account.main_menu()

# So something wacky manually
ussd = account.modem.sendUssd('#100*2*2#')

This provides an interface with Telstra’s USSD (Unstructured Supplementary Service Data) services. You may also know this as the #100# or #125# service.

So, now, you have an account that gives you access to common cellular commands that you’d normally be able to manually perform with USSD. A variety of operations are automated, such as balance & expiry checking.

This library allows auto-detection either without a phone number, being the first available physical modem that responds, or with a phone number, and the modem/account must conform to the given number.

If you’re already got a pre-existing python-gsmmodem modem instance available to you, then you can re-use this by passing it directly during manual initialisation of an account.

from import Prepaid
modem = ... #pre-existing python-gsmmodem instance
prepaid = Prepaid(modem)


This library provides a Python-based API that can communicate with these services via a connected cellular modem. So, you can easily auto-detect an account (and modem) based upon the underlying account’s phone number. This, whilst helpful, is entirely Telstra specific.

The initital implementation features an API for working with Telstra Prepaid, as this is what I can test against primarily. To a lesser extent, I have been able to abstract some parts of the code to work with Telstra Postpaid as well.


  • USB or serial-based cellular modem that works with python-gsmmodem. A USB 3G dongle or stick like the ZTE 3571-Z works fantastically for all known functionality.
  • Telstra SIM card, prepaid or postpaid


  1. Obtain materials, insert SIM into modem, connect modem to computer.

  2. Ensure you can communicate with your modem via its serial port, for example by using Hyperterminal (Windows), or screen or cu (Linux). This may require driver installation.

  3. Install this library. All dependencies will automatically be satisfied:

    pip install

    or, if you like Buildout:

    parts = telstra
    receipe = zc.recipe.egg
    eggs =
    interpreter = py
  4. Start using this library. The recommendation is to use the autodetection functionality, as this will automatically find the correct serial port to connect to. See Quickstart above.


  • bin/send-credit - sends credit to a nominated Telstra prepaid phone number by utilising the relevant USSD menus and options. This script can automatically run based on a number of conditions when called (such as target account balance and expiry).


David Beitey, Author


0.1 (2015-06-05)

  • Add option to either responsively or immediately send credit to send credit script. [davidjb]
  • Improve send credit script with web API calls. [davidjb]
  • Add web based prepaid metadata API. [davidjb]
  • Fix issue with autodetection probing all modems when the first one works. [davidjb]
  • Add ability to initialise modem and account with PIN. [davidjb]
  • Add ability for send credit script to detect modem phone number. [davidjb]
  • Send credit script does not save data by default (runs unless told otherwise). [davidjb]
  • Add call credit balance detection. [davidjb]
  • Handle situation when accessing the modem immediately after initialisation. [davidjb]
  • Cancel various USSD sessions to prevent later errors. [davidjb]
  • Improve handling of credit transfer for insufficient balances. [davidjb]
  • Improve amount parsing for prepaid accounts. [davidjb]
  • Use improved logging formatting for module. [davidjb]
  • Add send credit script to allow scripting of sending credit. [davidjb]
  • Package created using templer [davidjb]

Project details

Release history Release notifications

This version


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for, version 0.1
Filename, size File type Python version Upload date Hashes
Filename, size (24.1 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page