README

The txtNation Gateway PHP Library works with Laravel 5+. It is an extension of Marc O'Leary's txtnation/txtnation-gateway-php.

• Prerequisites
• Installation
• Configuration
• Usage
  • [Free SMS] (#free-sms)
  • [Premium SMS] (#premium-sms)
• Support

Prerequisites

This README assumes you are using the following PHP extensions:

• php-curl
• php-mbstring

Installation

• Use following command to install:

composer require saleemepoch/txtnation

• Add the service provider to your $providers array in config/app.php file like:

'saleemepoch\txtNation\Providers\txtNationServiceProvider' // Laravel 5

saleemepoch\txtNation\Providers\txtNationServiceProvider::class // Laravel 5.1 or greater

• Run the following command to publish configuration:

php artisan vendor:publish

Configuration

• After installation, you will need to add your txtNation settings. Following is the code you will find in config/txtNation.php, which you should update accordingly.

return [
	/* REQUIRED */
	'username' => '',
	'ekey' => '',
	// also known as sender id.
	'title' => '',

	/* OPTIONAL */
	// if set, requests to txtNation will also consists of the supplied shortcode
	'shortcode' => '',

	// required only if sending MT to Bill based on texted keywords
	'keywords' => [
		/*
		 * keywords and their corresponding amounts.
		 *
		 * This will set the value when billing the customer based on the keyword texted by the user
		 *
		 *
		'BILL10' => 10.00,
		'BILL5' => 5.00,
		*/
		'BILL1' => 1.00
	]
];

Usage

• To send a free SMS

$message = new SMSMessage;
$result = $message->msisdn('447459831491')->body('Please reply to this message with keyword PENNY!')->senderId('784645')->send();

if ($result->success()){
    dd('Message sent!');
} else {
    dd('Error sending message! Code: ' . $result->getErrorCode() . ' (' . $result->getErrorMessage() . ')');
}

• MT to Bill a user after opting-in

1. Make sure in config/txtNation.php you have keywords mapped to values the user is to be charged, e.g.

'keywords' => [
		'BILL10' => 10.00,
		'BILL5' => 5.00,
		'BILL1' => 1.00
	]

1. Login to your txtNation account -> APIs -> Gateway and set your responder URL, e.g. http://example.com/txtNationResponse

2. Setup a route in your routes.php:

Route::post('txtNationResponse', 'txtNationController@response');

1. Exclude this route from CSRF protection by adding the URI to the $except property of the VerifyCsrfToken middleware:

protected $except = [
        'txtNationResponse',
    ];

1. Setup a controller like txtNationController for this example and create a method:

public function response(Request $request) {
    
    if ($request->action == 'mpush_ir_message' &&
        (isset($request->billing) && $request->billing == 'MT')) {
         
        $keywords = config('txtNation.keywords');
        
        $message = new SMSMessage;
        $result = $message->msisdn($request->number)
        ->reply(1)
        ->body('Thank you for your business')
        ->id($request->id)
        ->network($request->network)
        ->currency('GBP')
        ->value($keywords[$request->message])
        ->send();
    
    }

}

The above controller method will accept the response from txtNation and if billing is set to MT it will reply back charging the user.