SIM admin API

Configuring USIMs

Each action has a corresponding command that should be used with the USIM gateway.

Action Command Information
activate activate Two step process
terminate terminate Two step process
suspend suspend Two step process
unsuspend unsuspend Two step process
add service add service Two step process
remove service remove service Two step process
Change ICCID changeiccid Two step process
Change MSISDN changemsisdn Two step process
Blacklist handset blacklist Two step process
Unblacklist handset unblacklist Two step process
Query ICCID queryiccid One step process
Check status checkstatus One step process. Does not perform an action on the sim but is used to query the state of a previous request

In order to configure a USIM using the gateway, you will need to send a command to the following address:

https://mvno.aql.com/mobile/mvno-management.api.php

The gateway accepts both HTTP GET and POST.

One-step process:
The final state of the request is known immediately in the response.
Two-step process:
Due to the complex nature of some of the commands, the final state cannot be determined in real time. It is recommended that you wait at least 30 minutes before issuing the first checkstatus command. These commands must therefore operate in a two-step process:

1. you must issue one of the commands and obtain a request id

2. you should periodically call the ‘checkstatus’ command to determine if your request was successful or if it failed.


Activate

Verification with variable

You can set a verification variable to protect your script from spamming.
You can use this to check whether the inbound data was sent to your virtual mobile number.

Our example script assumes that you have set a variable verify=aql in your destination URL, e.g. your virtual mobile number points to http://192.168.1.100/script.php?verify=aql

Failover with multiple destinations

You can set multiple destinations to your virtual mobile number.
This can be used to failover and ensure the inbound data will reach your script.

For example, if you have set two destinations http://192.168.1.100/script1.php and http://192.168.200/script2.php our system will first try to HTTP POST/GET request to script1.php and failing that the data will be delivered to script2.php

Placeholders

If no GET variables are specified we will pass the following:

Variable Placeholder Format
status %stat  
gwNumber %dest  
originator %orig  
message %msg  
time %time  
smsTime %smsTime  
timeZone %smsTimeZone  
network %netw  
coding %code  
id %id  

OR can pass some of the above and those below to your own parameter names depending on your requirements.

Placeholder Format
%unixRcvTime  
%smscTime YYYY-MM-DD HH:MM:SS
%smscTimeZone  
%origTon  
%origNpi  
%destTon  
%destNpi  
%smscRef  
%pid  
%addInfo  
%udh  
%dcs  

e.g. http://192.168.1.100/script.php?originator=%orig&timezone=%smsTimeZone

Relay IP addresses

MO messages to these numbers are relayed from these IPs:

  • 194.145.189.162

  • 194.145.189.163

Example code

PHP

//include the database handling class include("mysqlclass.php");

//Assign POSTED variables

$destination = $_POST['gwNumber'];
$originator = $_POST['originator'];
$message = $_POST['message'];
$smsTime = $_POST['smsTime'];
$timeZone = $_POST['timeZone'];
$network = $_POST['network'];
$id = $_POST['id'];
$status = $_POST['status'];

//Create a new instance of the mysql class and write data to database $mysql = New mysql(0);

$sql = "
INSERT INTO
  inbound
  (varOriginator, varDestination, varMessage, dtTime, varUnixTime, varUDH, intId)
  VALUES
  ('$originator', '$destination', '$message', '$time', '$unixTime', '$udh', '$id')";

  $mysql->query($sql);

ASP




$destination = $_POST['gwNumber'];
$originator = $_POST['originator'];

<%
Dim dest, org, msg, time, timezone, network, id, status

  dest = Request.QueryString("gwNumber");
  org = Request.QueryString("originator");
  msg = Request.QueryString("message");
  time = Request.QueryString("smsTime");
  timezone = Request.QueryString("timeZone");
  network = Request.QueryString("network");
  id = Request.QueryString("id");
  status = Request.QueryString("status");

  Response.Write ("Destination: " & dest & "<br />");
  Response.Write ("Originator: " & org & "<br />");
  Response.Write ("Message: " & msg & "<br />");
  Response.Write ("Time: " & time & "<br />");
  Response.Write ("Time Zone: " & timezone & "<br />");
  Response.Write ("Network: " & network & "<br />");
  Response.Write ("ID: " & id & "<br />");
  Response.Write ("Status: " & status & "<br />");

%>