Fortumo - Free SMS-gateway & SMS-billing

Fortumo Premium SMS-connectivity technical specification

Premium SMS-connectivity is the most flexible service type in Fortumo. It allows you to create practically any SMS service, that you could think of, but it requires some programming skills and a web-server where you could host your program (for example as a PHP-script).
When your service receives a message, Fortumo will make an HTTP GET request to the URL that you have specified in the service configuration (for example http://yourdomain.com/sms.php). The content that Fortumo receives from your URL (or actually the first 120 characters of it) is then sent back to the user as a reply message. The parameters of that HTTP GET request specify the sender's phone number, message content etc. So you can use all that information to generate the reply message.

Parameters

message

Message content minus keywords. Thus if the message was TXT KEY 123, then this parameter is 123. The parameter is empty if there was only the keyword and no additional text in the message.

sender

Message sender's phone number in international format without the plus sign. For example, 4560123456 or 358401234567.

country

The country code of the sender's mobile operator. Two character codes are used according to ISO 3166-1 standard (SE for Sweden, FI - Finland, NO - Norway, LT - Lithuania, LV - Latvia, EE - Estonia etc). Please also note that this is NOT necessarily the actual location of the sender. For example the sender with a Swedish phone, could be sending a message while being roaming in Norway, and you would still have SE in the country field.

price

The end user price of the message in the local currency, including VAT.

currency

The local currency symbol according to ISO 4217 (EUR, SEK, NOK, DKK, LTL, LVL, EEK, USD, GBP etc).

service_id

A string that identifies this Fortumo service. For example f7fa12b381d290e268f99e382578d64a. If you have many services with the same URL, then you can use this field to determine which service the message is for.

message_id

A string that is unique for each message that your service receives.

keyword

The keyword part of the message. Thus if the message was TXT KEY 123, then this parameter is TXT KEY.

shortcode

The short code that the message was sent to.

sig

Request signature that you may check, to make sure the request is originating from Fortumo. See below under Security to find out how.

People usually need only message and perhaps sender parameters, but for more advanced uses we have also added others.

Security
It is important to make sure that the service script is called by Fortumo and not someone else. There are several security measures, that satisfy most of the service providers:
1. Check whether the IP address of the server making the request belongs to one of Fortumo's servers. Our current IP addresses are 81.20.151.38 and 81.20.148.122. We will let you know by e-mail when they change. In PHP you can check this with $_SERVER["REMOTE_ADDR"] variable.
2. Choose not so obvious name for your directory or script. For example http://yourdomain.com/sms.php is not as good as http://yourdomain.com/go850g3oigjrtog/sms.php.
3. Check that the attached signature matches. All the requests are signed with the shared secret only known to you and Fortumo. You can see the secret from the service settings page. The signature is added as sig parameter and is calculated as md5 checksum of the request parameters and secret concatenated together. You can make the same calculation and check whether the sig parameter in the request matches the one that you calculated. See the PHP example below to find out exactly how the calculation is made.

Sample sms.php

<?php
  // check that the request comes from Fortumo server
  if(!in_array($_SERVER['REMOTE_ADDR'],
      array('81.20.151.38', '81.20.148.122'))) {
    die("Error: Unknown IP");
  }

  // check the signature
  $secret = ''; // insert your secret between ''
  if(!empty($secret) && !check_signature($_GET, $secret)) {
    die("Error: Invalid signature");
  }

  $sender = $_GET['sender'];
  $message = $_GET['message'];

  // do something with $sender and $message
  $reply = "Thank you $sender for sending $message";

  // print out the reply
  echo($reply);


  function check_signature($params_array, $secret) {
    ksort($params_array);

    $str = '';
    foreach ($params_array as $k=>$v) {
      if($k != 'sig') {
        $str .= "$k=$v";
      }
    }
    $str .= $secret;
    $signature = md5($str);

    return ($params_array['sig'] == $signature);
  }
?>

Copy to clipboard

START

BACK

Fortumo Premium SMS-connectivity technical specification

Parameters

Security

Sample sms.php