README

Send SMS notifications in Laravel powered by Apex Messaging. This package provides an easy-to-use notification channel for Laravel that integrates with the Apex Messaging API.

Installation

You can install the package via composer:

composer require saythanks/laravel-apex

The package will automatically register its service provider.

Configuration

You can publish the config file with:

php artisan vendor:publish --tag="laravel-apex-config"

Environment Variables

Add the following variables to your .env file:

# Required Settings
APEX_API_TOKEN=your_api_token_here        # Your Apex API token
APEX_SOURCE_ADDRESS=YOUR_SENDER_ID        # Sender ID/From name

# Optional Settings with defaults
APEX_HOST=https://papi.apex-messaging.com/        # API endpoint (default shown)
APEX_MESSAGE_TYPE=1                               # 1=Promotional, 2=Transactional, 3=OTP (default: 1)
APEX_MESSAGE_ENCODING=0                           # 0=GSM, 1=ASCII, 8=UCS2 (Unicode) (default: 0)
APEX_CALLBACK_URL=https://your-domain.com/webhook # URL for delivery reports
APEX_DELIVERY_ENABLED=true                        # Enable/disable delivery reports
APEX_STORE_CACHE_ENABLED=false                    # Store message details in cache
APEX_STORE_CACHE_TTL=86400                        # Cache TTL in seconds (24 hours)

Usage

Setting up your Notifiable Model

Add a routeNotificationForApex method to your notifiable class:

public function routeNotificationForApex($notification)
{
    return $this->phone_number; // Return the phone number to receive SMS
}

If you don't implement this method, the package will fall back to routeNotificationForSms.

Creating Notifications

<?php

namespace App\Notifications;

use Illuminate\Notifications\Notification;
use LaravelApex\Messages\ApexMessage;
use LaravelApex\Enums\MessageType;

class AccountActivated extends Notification
{
    public function via($notifiable)
    {
        return ['apex']; // Use the Apex channel
    }

    public function toApex($notifiable)
    {
        return (new ApexMessage("This is an example message!"))
            ->messageType(MessageType::TRANSACTIONAL)
            ->userReferenceId('account-'.$notifiable->id);
    }
}

Available Message Methods

content($text): Set the message content
messageType($type): Set the message type (1=Promotional, 2=Transactional, 3=OTP)
messageEncoding($encoding): Set the message encoding (0=GSM, 1=ASCII, etc.)
callbackUrl($url): Set a callback URL for delivery reports
userReferenceId($id): Set a custom reference ID for tracking

Integration with Website Project

Setup as a Channel Option

To use Apex in your main application:

Publish the config file to your project:

php artisan vendor:publish --tag="laravel-apex-config"

Add the required environment variables to your .env file (see Environment Variables section above).
Configure your notifiable models and create your notifications. ], ],

Tracking Delivery Reports

The application using this package should implement its own webhook handling for delivery reports. Configure the callback URL in your environment settings:

APEX_CALLBACK_URL=https://your-domain.com/api/webhooks/apex/delivery-report

Implement a controller in your application to process the delivery reports and update your database accordingly.

Data Encoding Values

Code	Encoding
0	Default (GSM)
1	ASCII
2	Octet
3	Latin1
4	Octet Unspecified
6	Cyrillic
7	Latin Hebrew
8	UCS2

Message Types

Code	Type
1	Promotional
2	Transactional
3	OTP

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

License

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

TODO

Should I add HLR functionality? - Probably should just so it's available

saythanks / laravel-apex

Maintainers

Details