README

📦 Overview

Laravel Grandstream is a clean SDK for integrating Laravel apps with Grandstream UCM PBX devices.
It simplifies REST API communication, including:

Challenge → Token → Cookie authentication flow
Cached login cookies per user/session
Unified API request handling with auto-retry on cookie expiration
Easy integration into Filament dashboards or CRM systems

Ideal for real-time call monitoring, extension management, or PBX-based CRM dashboards.

📖 Official API Reference

The complete Grandstream HTTPS API documentation is available here:
👉 Grandstream UCM6xxx HTTPS API Guide (PDF)

It includes:

Authentication flow (challenge → login)
Voice & call control endpoints (listBridgedChannels, Hangup, CallTransfer, etc.)
CDR & Recording APIs (cdrapi, recapi)
Error codes and result structures

This Laravel package aligns with the same API structure and request schema described in that official document.

⚙️ Installation

Install the package via Composer:

composer require akramghaleb/laravel-grandstream

Then publish the configuration file:

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

🔧 Configuration

A config/grandstream.php file will be created.
Add your device credentials to .env:

UCM_BASE=https://your-ucm-ip
UCM_API_USER=apiuser
UCM_API_PASS=apipassword
UCM_API_VER=1.2
UCM_COOKIE_TTL=9
GRANDSTREAM_WEBHOOK_USER=admin
GRANDSTREAM_WEBHOOK_PASS=password

🚀 Usage

Use the Facade for simple calls:

use AkramGhaleb\LaravelGrandstream\Facades\Grandstream;

// Example: List extensions
$response = Grandstream::getData('listAccount', [
            'options' => 'extension,account_type,fullname,status,addr',
            'page' => 1, 'sidx' => 'extension', 'sord' => 'asc',
        ]);

// Example: Fetch call records (CDR)
$cdr = Grandstream::getData('cdrapi', ["format":"json"]);

The package automatically retries failed requests when cookies expire (-6, -8, -37).

🧩 Example Response

{
    "status": 0,
    "response": {
        "total": 125,
        "cdr": [
            {
            "call_time": "2025-10-18 09:14:23",
            "src": "1001",
            "dst": "1002",
            "duration": "00:00:12",
            "disposition": "ANSWERED"
            }
        ]
    }
}

🧱 Advanced Usage

Inject it directly instead of using the Facade:

use AkramGhaleb\LaravelGrandstream\Grandstream;

class CallController
{
    public function index()
    {
        $calls = Grandstream::getData('listUnBridgedChannels');
        return response()->json($calls);
    }
}

🧪 Testing

composer test

📝 Changelog

See CHANGELOG for details.

🤝 Contributing

Contributions are welcome!
Please read CONTRIBUTING.md before submitting a PR.

🛡️ Security

For security vulnerabilities, please review our security policy.

👨‍💻 Credits

📄 License

This project is open-source software licensed under the MIT License.
See LICENSE for more information.

🌍 Support

If you find this package useful, please ⭐ it on GitHub.
You can also support by sharing feedback, contributing, or improving documentation.

akramghaleb / laravel-grandstream

Maintainers

Details