helliosolutions/helliosms

Laravel integration for the Hellio Messaging array of services.

dev-main 2022-08-10 23:57 UTC

Requires

• php: ^7.0|^7.3|^8.0|^8.1
• ext-json: *
• guzzlehttp/guzzle: ^7.2
• illuminate/notifications: 5.*|^6.0|^7.0|^8.0|^9.0
• illuminate/support: 5.*|^6.0|^7.0|^8.0|^9.0

Requires (Dev)

• orchestra/testbench: ^6.4|^v7.5.0
• phpunit/phpunit: ^9.5.21

MIT

• Albert ninyeh

• laravel sms
• hellio messaging
• bulk sms in Ghana
• laravel integration sms
• sms laravel package
• laravel otp package
• laravel notification package
• laravel channel notification package
• laravel voice sms package

README

About

Official Laravel package that integrates with Hellio Messaging's fleets of APIs nicely with Laravel 5+ adding support for SMS, Notification, Voice SMS, OTP Codes, OTP Validation, Email Validator Service & Laravel Validator as well.

Registration

Sign up for Hellio Messaging and get the auth key from your account. You can find the client_id and application_secret from Profile Settings > API Keys & Webhooks key after signing in.

Installation

composer require helliosolutions/helliosms

Laravel < 5.5

Once the package is installed, open your app/config/app.php configuration file and locate the providers key. Add the following line to the end:

\Hellio\HellioMessaging\HellioMessagingServiceProvider::class

Next, locate the aliases key and add the following line:

'HellioMessaging' => \Hellio\HellioMessaging\Facades\HellioMessaging::class,

Configuration

Put the credentials and preferences in ENV with the keys:

HELLIO_MESSAGING_CLIENT_ID
HELLIO_MESSAGING_APPLICATION_SECRET
HELLIO_MESSAGING_DEFAULT_SENDER
HELLIO_MESSAGING_API_VERSION

If you want to customize this, publish the default configuration which will create a config file config/helliomessaging.php.

### Configuration Structure
The configuration looks like this:
<?php

return [

    /**
     * Live API url
     *
     */
    'baseUrl' => 'https://api.helliomessaging.com/',

    /**
     * Client Id
     *
     */
    'clientId' => getenv('HELLIO_MESSAGING_CLIENT_ID'),

    /**
     * Application Secret
     *
     */
    'applicationSecret' => getenv('HELLIO_MESSAGING_APPLICATION_SECRET'),


    /**
     * Default Sender Id
     *
     */
    'defaultSender' => getenv('HELLIO_MESSAGING_DEFAULT_SENDER'),


    /**
     * Default API version
     *
     */

    'apiVersion' => getenv('HELLIO_MESSAGING_API_VERSION'),

    /**
     * Default username
     *
     */
    'username' => getenv('HELLIO_MESSAGING_USERNAME'),


    /**
     * Default password
     *
     */

    'password' => getenv('HELLIO_MESSAGING_PASSWORD'),

];

Publish Service provider:

$ php artisan vendor:publish --provider="Hellio\HellioMessaging\HellioMessagingServiceProvider" --tag=helliomessaging

Usage:

Open your .env file and add your api key like so:

HELLIO_MESSAGING_CLIENT_ID=xxxxxxxx
HELLIO_MESSAGING_APPLICATION_SECRET=xxxxxxxx
HELLIO_MESSAGING_DEFAULT_SENDER=YourSenderName //Max of 11 characters
HELLIO_MESSAGING_API_VERSION= // From v1 to v3. Kindly check the documentation for the appropriate version you wish to use

Basic

• Send an SMS to one or more mobile numbers.

<?php

//The first call assumes that you've already set a default sender_id in the helliomessaging.php config file.
$response = HellioMessaging::sms('233242813656', 'Hello there!');

$response = HellioMessaging::sms('233242813656', 'Hello there!', 'HellioSMS');

$response = HellioMessaging::sms(null, [
    ['mobile_number' => ['233242813656', '233591451609'], 'message' => 'Hello there!'],
    ['mobile_number' => ['233203555816'], 'message' => 'Come here!'],
], 'HellioSMS');

SMS Responses:

On Success

{
    "success": true,
    "message": "1 sms sent successfully"
}

• Send OTP to a mobile number.

<?php

$response = HellioMessaging::otp('233242813656');

$response = HellioMessaging::otp('233242813656', 'HellioSMS', '4', '10');

$response = HellioMessaging::otp('233242813656', 'HellioSMS', '4', '10', '##OTP## is your OTP, Please dont share it with anyone.');

• Verify OTP sent to a mobile number.

<?php

$response = HellioMessaging::verify('233242813656', 1290); // returns true or false

OTP Responses:

On Success

{
    "success": true,
    "data": {
        "status": true,
        "token": "528830",
        "message": "OTP generated"
    },
    "message": "2FA code sent successfully"
}

Does not exist

{
    "success": true,
    "data": {
        "status": false,
        "message": "OTP does not exist"
    },
}

Not Valid*

{
    "success": true,
    "data": {
        "status": false,
        "message": "OTP is not valid"
    },
}

Expired

{
    "success": true,
    "data": {
        "status": false,
        "message": "OTP Expired"
    },
}

Email Validation

• Validate email addresses to check if they're correct and can recieve emails.

<?php

$response = HellioMessaging::emailvalidator('[e-mail]', 'Marketing leads');

$response = HellioMessaging::emailvalidator(['[e-mail]', '[e-mail]'], 'Marketing leads'); // Validate multiple emails at once

Number Lookup Service

• Check the status of a mobile number before sending your bulk sms campaign. This ensures you're sending messages to numbers that are active and recipients can actually recieve your messages.

<?php

$response = HellioMessaging::numberLookup('233242813656');

$response = HellioMessaging::numberLookup(['233242813656', '233591451609']); // Validate multiple mobile numbers at once

Hellio Account Balance

• Check your Hellio Messaging account balance with ease.

<?php

$response = HellioMessaging::balance();

Notification

Include helliomessaging in your notification's channels:

<?php

/**
 * @param  mixed  $notifiable
 * @return array
 */
public function via($notifiable)
{
    return ['helliomessaging'];
}

Define the toHellioMessaging method:

<?php

use Hellio\HellioMessaging\Message\HellioMessagingSms;

public function toHellioMessaging()
{
    return (new HellioMessagingSms)
        ->message(__('This is just a test message.'))
	    ->sender_id(__('HellioSMS')) // [Optional] - Will pick default sender ID from HELLIO_MESSAGING_DEFAULT_SENDER or if not set, will use the application name.
        ->to('233242813656');
}

Default routeNotificationForHellioMessaging method in your notifiable class:

<?php

public function routeNotificationForHellioMessaging($notification)
{
    return $this->mobile_number;
}

Finally, send the notification:

<?php

$notifiable = /* some class */
$notifiable->notify(new App\Notifications\HellioMessagingTestNotification());

For sending the notification to an arbitrary mobile number, use below syntax:

<?php
use Illuminate\Support\Facades\Notification

Notification::route('helliomessaging', '233242813656')
    ->notify(new App\Notifications\HellioMessagingTestNotification());

OTP Validator

You can validate sent OTPs using provided validation rule named hellio_otp as shown below:

<?php

use Illuminate\Support\Facades\Validator

$data = ['mobile_number' => '233242813656', 'token' => '1234'];

$validator = Validator::make($data, [
    'mobile_number' => ['required', 'digits:10'],
    'token' => ['required', 'digits:4', 'hellio_otp'], // default key for source number is 'mobile_number', you can customize this using 'hellio_otp:key_name'
]);

if ($validator->fails()) {
    // report errors
}

Testing

$ composer test

Security

If you discover any security related issues, please email [e-mail] instead of using the issue tracker.

Contributing

Please see CONTRIBUTING for details.

Credits

• Albert Ninyeh
• Norris Oduro Tei
• All Contributors

License

The MIT License (MIT). Please see License File for more information.