Inbound SMS to virtual mobile numbers API

Variables

The following variables will be sent to your script via HTTP POST or GET upon a message being delivered to you. If you can design your script to listen out for the variables below:

Name Description
gwNumber The destination number
originator The sender’s number
message The message body
smsTime Time when the sms was sent. Format: YYYY-MM-DD HH:MM:SS
timeZone An integer, indicating time zone (eg: if timeZone is 1 then it means smsTime is GMT + 1)
network Name of the originating network.
Will be replaced with an SMSC reference number if the network is not recognised.
id A unique identifier for the message
time Time the message received by aql (UK time). Format: YYYY-MM-DD HH:MM:SS
coding Message coding 7 (normal), 8 (binary) or 16 (unicode)
status 0 – Normal Message
1 – Concatenated message, sent unconcatenated
2 – Indecipherable UDH (possibly corrupt message)

Please note that we expect the originator ID to be in a numeric format, rather than alphanumeric, however this should not affect the majority of senders.

Technical

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 will be relayed from one of the following subnets. If your application is behind a firewall, we would recommend to whitelist all of the following subnets to avoid any issue. Raising a support case without whitelisting these subnets may lead to delays whilst diagnosing any issues that you are facing.

  • 141.170.8.0/24

  • 141.170.55.0/24

  • 109.239.102.0/24

  • 109.239.103.0/24

  • 194.145.189.0/24

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 />");

%>