README

Laravel client for the Hellio Messaging API v1: SMS, OTP (SMS / voice / WhatsApp / email), Voice broadcasts, Number Lookup (HLR), Email Verification, Webhooks, plus a Laravel notification channel and a validation rule.

Install

composer require helliosolutions/helliosms

Publish the config (optional):

php artisan vendor:publish --tag=helliomessaging

Configure

Generate a token in your dashboard → Settings → API → Generate API token, then set:

HELLIO_BASE_URL=https://api.helliomessaging.com/v1
HELLIO_API_TOKEN=your-token-here
HELLIO_DEFAULT_SENDER=HellioSMS

Usage

Resolve the client from the container or use the HellioMessaging facade.

use Hellio\HellioMessaging\Facades\HellioMessaging;

// Account
HellioMessaging::balance();            // ['data' => ['balance' => '195.0000', 'available' => '194.65', ...]]
HellioMessaging::pricing('GH');        // optional ISO-2 country filter

// SMS (recipients: string, comma list, or array)
HellioMessaging::sms('233241234567', 'Hello!');
HellioMessaging::sms(['233241234567', '233201234567'], 'Hi all', 'HellioSMS');
HellioMessaging::message(1024);        // delivery status
HellioMessaging::campaign(1024);       // campaign summary

// OTP — sender (Sender ID) is REQUIRED for sms/voice and must be approved on your account.
// Optional length (4–10 digits) and expiry (minutes). Returns status "queued".
HellioMessaging::otp('233241234567', 'HellioSMS');                          // SMS
HellioMessaging::otp('233241234567', 'HellioSMS', 'voice');                 // Voice (TTS reads the code)
HellioMessaging::otp('233241234567', channel: 'whatsapp');                  // WhatsApp (no sender)
HellioMessaging::otp('233241234567', 'HellioSMS', length: 6, expiry: 10);   // custom length / expiry
HellioMessaging::otp('user@example.com', channel: 'email');                 // Email (no sender)
HellioMessaging::verify('233241234567', '123456');                          // bool
HellioMessaging::verifyOtp('user@example.com', '123456', 'email');          // full response

// Voice broadcast — text (we TTS it) or a hosted audio_url
HellioMessaging::voice('233241234567', 'HELLIO', text: 'Your code is 1 2 3 4');
HellioMessaging::voice(['233241234567'], 'HELLIO', audioUrl: 'https://cdn.example.com/promo.mp3');

// Number lookup (HLR) — async; poll results
HellioMessaging::lookup(['233241234567']);
HellioMessaging::lookups();
HellioMessaging::lookupResult(5);

// Email verification
HellioMessaging::verifyEmail(['user@gmail.com', 'bad@nodomain.invalid']);

// Webhooks (receive delivery reports)
HellioMessaging::createWebhook('https://your-app.com/hooks/hellio', ['message.delivered', 'message.failed']);
HellioMessaging::webhooks();
HellioMessaging::deleteWebhook(1);

Notification channel

use Hellio\HellioMessaging\Message\HellioMessagingSms;

class OrderShipped extends \Illuminate\Notifications\Notification
{
    public function via($notifiable): array { return ['helliomessaging']; }

    public function toHellioMessaging($notifiable): HellioMessagingSms
    {
        return (new HellioMessagingSms())
            ->message('Your order has shipped!')
            ->sender('HellioSMS');
    }
}

Route it on the notifiable:

public function routeNotificationForHelliomessaging($notification) { return $this->phone; }

Validation rule

Verify an OTP a user typed (defaults to the mobile_number field):

$request->validate([
    'mobile_number' => 'required',
    'otp' => 'required|hellio_otp:mobile_number',
]);

Error handling

Non-2xx responses throw typed exceptions (all extend HellioException):

Exception	Status
`InvalidApiTokenException`	401
`InsufficientBalanceException`	402
`ValidationException` (`->response['errors']`)	422
`RateLimitException`	429
`HellioException`	other

use Hellio\HellioMessaging\Exceptions\InsufficientBalanceException;

try {
    HellioMessaging::sms('233241234567', 'Hi');
} catch (InsufficientBalanceException $e) {
    // top up
}

Rate limit: 120 requests/minute per token.

License

MIT

helliosolutions / helliosms

Maintainers

Package info

Statistics

Security