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:

NameDescription
gwNumberThe destination number
originatorThe sender’s number
messageThe message body
smsTimeTime when the sms was sent. Format: YYYY-MM-DD HH:MM:SS
timeZoneAn integer, indicating time zone (eg: if timeZone is 1 then it means smsTime is GMT + 1)
networkName of the originating network.
Will be replaced with an SMSC reference number if the network is not recognised.
idA unique identifier for the message
timeTime the message received by aql (UK time). Format: YYYY-MM-DD HH:MM:SS
codingMessage coding 7 (normal), 8 (binary) or 16 (unicode)
status0 – 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:

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

PlaceholderFormat
%unixRcvTime 
%smscTimeYYYY-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 />");

%>