README

Features

SMS gateway using the open source Android app SMS Gateway - use the generic release

License

This software is distributed under the LGPL-3.0-only license. Please read LICENSE for information on the software availability and distribution.

Installation & loading

SMSGateway is available on Packagist (using semantic versioning), and installation via Composer is the recommended way to install SMSGateway. Just add this line to your composer.json file:

"multiotp/smsgateway": "^1.0"

or run

composer require multiotp/smsgateway

Note that the vendor folder and the vendor/autoload.php script are generated by Composer; they are not part of SMSGateway.

Alternatively, if you're not using Composer, you can download SMSGateway as a zip file, then copy the contents of the SMSGateway folder into one of the include_path directories specified in your PHP configuration and load each class file manually:

<?php
use multiOTP\SMSGateway\SMSGateway;

require 'path/to/SMSGateway/src/SMSGateway.php';

Two simple examples

<?php
//Import SMSGateway classes into the global namespace
//These must be at the top of your script, not inside a function
use multiOTP\SMSGateway\SMSGateway;

//Load Composer's autoloader
require 'vendor/autoload.php';

//Create an instance
$smsgateway = new SMSGateway();

// Set the data folder
$smsgateway->setDataPath(__DIR__ . DIRECTORY_SEPARATOR . 'data' . DIRECTORY_SEPARATOR);

// Set the shared secret
$smsgateway->setSharedSecret("secret");

$device_id   = "demo";
$to = "+1234567890";
$message = "Demo message";
$device_h = $smsgateway->calculateAuthenticationHash($device_id);

$message_id = $smsgateway->sendMessage($device_id, $to, $message);

echo "Full URL for Android app URL: https://......./?id=$device_id&h=$device_h";

<?php
//Import SMSGateway classes into the global namespace
//These must be at the top of your script, not inside a function
use multiOTP\SMSGateway\SMSGateway;

//Load Composer's autoloader
require 'vendor/autoload.php';

// Please note that implementing a new_message_handling callback function
//  will flag the new messages as read when returning from the function.
function new_message_handling($array) {
  // Handling $array of new received messages
  // [["device_id"    => "device id",
  //   "message_id"   => "message id",
  //   "from"         => "from phone number",
  //   "sms_sent"     => "sms_sent timestamp (ms)",
  //   "sms_received" => "sms_received timestamp (ms)",
  //   "content"      => "message content",
  //   "last_update"  => "last update timestamp (ms)",
  //   "status"       => "UNREAD|READ"
  //  ],
  //  [...]
  // ]
}

function update_handling($array) {
  // Handling $array of status updates for sent messages
  // [["device_id"    => "device id",
  //   "message_id"   => "message id",
  //   "to"           => "to phone number",
  //   "content"      => "content",
  //   "last_update"  => "last update timestamp (ms)",
  //   "status"       => "NEW|PUSHED|PENDING|SENT|DELIVERED|FAILED"
  //  ],
  //  [...]
  // ]
}

function timeout_handling($array) {
  // Handling $array of devices not seen during the last "DeviceTimeout" seconds
  // [["device_id"   => "device_id",
  //   "last_update" => "device_last_update"
  //  ],
  //  [...]
  // ]
}

//Create an instance
$smsgateway = new SMSGateway();

// Set the data folder
$smsgateway->setDataPath(__DIR__ . DIRECTORY_SEPARATOR . 'data' . DIRECTORY_SEPARATOR);

// Launch the API server with callback functions definition
$smsgateway->apiServer("secret", "new_message_handling", "update_handling", "timeout_handling");

SMS messages status

Received message

UNREAD: message has never been read on the gateway
READ: message has already been read on the gateway

Sent message

NEW: new created message, not transfered yet to the Android device
PUSHED: message pushed to the Android device
PENDING: message is pending in the Android device
SENT: message has been sent to the gateway's network
DELIVERED: message has been received by the recipient's phone
FAILED: message delivery has failed and will not be retried
MISSING: message with this message id is missing, no state available

Online demo

A full working gateway implementation is available here : Online SMSGateway demo. Click the link and everything is self-explanatory. You will simply have to install and configure the companion open source Android app in order to send and receive SMS messages through this demo gateway (as explained after sending a first SMS message using the online demo gateway).
When sending a message, the following information will be returned in the http header and in the html meta tags:

X-SMSGateway-State: state of the sent message (NEW|FAILED)
X-SMSGateway-State-Url: full url to check the state of the message
X-SMSGateway-Message-Id: message id

Documentation

Example of how to use SMSGateway for a common scenario can be found in the examples folder. If you're looking for a good starting point, we recommend you start with the gateway example.

Android specific parameters

Using adb shell, you should change these two parameters:

sms_outgoing_check_max_count
sms_outgoing_check_interval_ms

Example for a limit of 200 messages per minute:

adb shell
settings put global sms_outgoing_check_max_count 200
settings put global sms_outgoing_check_interval_ms 60000

You need to reboot your Android phone. after these changes

Changelog

See CHANGELOG.

That's it. You should now be ready to use SMSGateway!

multiotp / smsgateway

Maintainers

Details