README

Package created to use the Pingram notification service (https://pingram.io) — formerly NotificationAPI — in Laravel applications.

Official Documentation for Pingram: https://docs.pingram.io/

Installation

Require the package via Composer:

composer require agrodata/notificationapi

Or add it directly to your composer.json:

{
    "require": {
        "agrodata/notificationapi": "^1.0"
    }
}

The package supports Laravel package auto-discovery. If you register providers manually in config/app.php:

'providers' => [
    // ...
    Agrodata\NotificationApi\PingramServiceProvider::class,
    // (Legacy Agrodata\NotificationApi\NotificationApiServiceProvider::class is also supported)
]

Configuration

Publish the configuration file (optional):

php artisan vendor:publish --provider="Agrodata\NotificationApi\PingramServiceProvider" --tag="config"

The configuration is automatically registered under services.pingram (and services.notification-api):

// config/services.php
return [
    'pingram' => [
        'key' => env('PINGRAM_API_KEY', env('PINGRAM_KEY', env('NOTIFICATION_API_KEY'))),
        'secret' => env('PINGRAM_SECRET', env('NOTIFICATION_API_SECRET')),
        'base_url' => env('PINGRAM_BASE_URL'),
    ],
    'notification-api' => [
        'key' => env('PINGRAM_API_KEY', env('PINGRAM_KEY', env('NOTIFICATION_API_KEY'))),
        'secret' => env('PINGRAM_SECRET', env('NOTIFICATION_API_SECRET')),
    ],
];

Add your API Key in your .env file:

# .env
PINGRAM_API_KEY=pingram_sk_xxxxxxxxxxxxxxx

(Legacy NOTIFICATION_API_KEY and NOTIFICATION_API_SECRET are also automatically recognized).

Usage

1. In Laravel Notifications

Create a notification using Artisan:

php artisan make:notification OrderShipped

In your notification class, specify 'pingram' (or 'notification-api') in the via method:

namespace App\Notifications;

use Illuminate\Notifications\Notification;

class OrderShipped extends Notification
{
    public function via($notifiable): array
    {
        return ['pingram']; // or ['notification-api']
    }

    public function toPingram($notifiable): array
    {
        return [
            'notification_id' => 'order_shipped',
            'to' => [
                'id' => (string) $notifiable->id,
                'email' => $notifiable->email,
                'number' => $notifiable->phone ?? null,
            ],
            'parameters' => [
                'customerName' => $notifiable->name,
                'orderId' => '12345',
            ],
        ];
    }

    // Legacy method toNotificationApi is also fully supported:
    // public function toNotificationApi($notifiable): array { ... }
}

Send the notification as usual:

$user->notify(new OrderShipped());

// Or using Notification facade:
Notification::send($users, new OrderShipped());

2. Helpers & Direct Service Usage

You can also send notifications directly using the pingram() helper or the PingramService class:

use Agrodata\NotificationApi\PingramService;

$payload = [
    'notification_id' => 'order_tracking',
    'to' => [
        'id' => 'user_123',
        'email' => 'user@example.com',
        'number' => '+15005550006'
    ],
    'parameters' => [
        'item' => 'Solar Panels',
        'orderId' => '1234567890'
    ]
];

// Using helper:
$response = pingram($payload);

// Or using the service directly:
$service = new PingramService();
$response = $service->send($payload);

// Or with SDK Model instance:
use Pingram\Model\SenderPostBody;
$body = new SenderPostBody([...]);
$response = $service->send($body);

Backward Compatibility

Existing code using the previous NotificationAPI syntax continues to work without modifications:

• Channels: both 'pingram' and 'notification-api' are registered.
• Methods: both toPingram() and toNotificationApi() are recognized.
• Payload fields: both notificationId / mergeTags / user and notification_id / parameters / to are accepted and automatically normalized.
• Helpers & Classes: notification_api() and NotificationApiService remain fully functional and route to the new Pingram backend.