README

#Hubtel notification channel for Laravel 11+

This package makes it easy to send notifications using Hubtel with Laravel 11+.

Installation
- Setting up the Hubtel service
Usage
- Available Message methods
Testing the Integration
Querying Message Status
Changelog
Testing
Security
Contributing
Credits
License

Installation

To get the latest version of Hubtel Notification channel for Laravel 11+, simply require the project using Composer:

Run from your terminal

$ composer require kwadwokyeremeh/hubtel-laravel-sms

Setting up the Hubtel service

In your Hubtel account go to Applications page. Click on the details of the desired application and copy your apiKey and apiSecret

In your terminal run

$ php artisan vendor:publish --provider="NotificationChannels\Hubtel\HubtelServiceProvider"

This creates a hubtel-sms.php file in your config directory.

Paste your apiCredentials in the config/hubtel.php configuration file. You may copy the example configuration below to get started:

        'api_key' => env('HUBTEL_CLIENT_ID'),
        'api_secret' => env('HUBTEL_CLIENT_SECRET')
        'use_post_method' => env('HUBTEL_SEND_METHOD')

Add the HUBTEL_CLIENT_ID and HUBTEL_CLIENT_SECRET to your .env file

Usage

Now you can use the channel in your via() method inside the notification:

    use Illuminate\Notifications\Notification;
    use NotificationChannels\Hubtel\HubtelChannel;
    use NotificationChannels\Hubtel\HubtelMessage;
    
    class SayHello extends Notification
    {
        public function via($notifiable)
        {
            return [HubtelChannel::class];
        }
    
        public function toSMS($notifiable)
        {
            return (new HubtelMessage)
                        ->from("JabClari")
                        ->to("2331234567890")
                        ->content("Kim Kippo... Sup with you");
        }
    }

In order to let your Notification know which phone number you are sending to, add the routeNotificationForSMS method to your Notifiable model e.g your User Model

public function routeNotificationForSMS()
{
    return $this->phone; // where phone is a cloumn in your users table;
}

Available Message methods

from($from) : set the sender's name or phone number
to($to) : set the recipient's phone number
content($content) : set the message content
registeredDelivery() : set delivery report request
clientReference($reference) : set the client reference number
type($type) :set the message type to be sent
udh($udh) : set the User Data Header of the SMS Message being sent
time($time) : set the time to deliver the message
flashMessage() : sends the message as a flash message

Read more about the available methods on the Hubtel Documentation Page

Testing the Integration

You can test your Hubtel SMS integration using the built-in Artisan command:

php artisan hubtel-sms:test +1234567890 --from="SenderName" --message="Your test message here"

Command Arguments and Options:

to - Required. The recipient phone number
--from - Optional. The sender ID/name (defaults to config value or 'Laravel')
--message - Optional. Custom message content (defaults to a standard test message)

Prerequisites:

Configure Hubtel API credentials in your .env file:

HUBTEL_CLIENT_ID=your_client_id
HUBTEL_CLIENT_SECRET=your_client_secret

Publish the config file (if not already done):

php artisan vendor:publish --tag=hubtel-sms-config

Querying Message Status

The package now supports querying the status of sent messages. You can check the delivery status of a message using the HubtelStatusChecker:

    use NotificationChannels\Hubtel\SMSClients\HubtelStatusChecker; 
    use GuzzleHttp\Client;
    $statusChecker = new HubtelStatusChecker($apiKey, $apiSecret, new Client()); 
    $response = $statusChecker->query('message-id-here');
    if ($response->isDelivered()) { 
    echo "Message was delivered successfully";
     }
    // Access other status information
    $response->getStatus(); 
    $response->getUpdateTime();

You can also check message status using the built-in Artisan command:

php artisan hubtel-sms:status message-id-here

This command will display detailed information about the message including delivery status, recipient, content, and delivery time.

Changelog

Latest Notice

For developers who would want to use this package on VPS hosted applications, if the server location is US for which you have a US IP Address, you may need to seek whitelisting of the US Ip address from hubtel by mailing support@hubtel.com. As i discovered through experience that the package would work fine on local machine because the IP used is a Ghanaian IP address but fails to work on a production server. Note however that this is not a package problem, as the package justorganizes components for sending successful SMS messages within Laravel. It is even more challenging to know the cause of the problem when you are using laravel queues, because the response codes are not logged, the queue just logs Processing failed.Hubtels SMS server responds with a 403 Forbidden, when the same SMS issent directly using Guzzlehttp on the production server (VPS). A 403 HTTP Response according to their website (hubtel) indicates the recipient has not given his/her approval to receive messages which is even more confusing. :)

Please see CHANGELOG for more information what has changed recently.

Testing

$ composer test

To run the live tests, you need to set the required environment variables. Here's how you can do it: First, you need to set the environment variables with your Hubtel API credentials:

export HUBTEL_CLIENT_ID=your-api-key
export HUBTEL_CLIENT_SECRET=your-api-secret
export RUN_LIVE_TESTS=true
export HUBTEL_SEND_METHOD=true // true for POST method, false for GET method
export HUBTEL_SENDER_ID=your-sender-id
export HUBTEL_PHONE_NUMBER=your-phone-number

Then, run the tests:

 vendor/bin/phpunit --group=live --dont-report-useless-tests

Security

If you discover any security related issues, please email norisjibril@gmail.com instead of using the issue tracker.

kwadwokyeremeh / hubtel-laravel-sms

Maintainers

Details