README

A complete, production-ready Laravel package for implementing ZegoCloud audio and video calling with mobile app support. Just install, configure credentials, and you're ready to go!

Features

✅ Zero Configuration Setup - Just add your ZegoCloud credentials to .env ✅ Audio & Video Calling - Full support for both audio and video calls ✅ Web & Mobile Support - Works seamlessly across web browsers and mobile apps ✅ Real-time Communication - WebSocket broadcasting for call state synchronization ✅ Push Notifications - FCM (Android) and APNs (iOS) support for incoming calls ✅ Call History - Track and manage call records ✅ Laravel 10-12+ Compatible - Supports Laravel 10, 11, 12 and future versions ✅ Auto-Discovery - Service provider auto-registration ✅ Customizable UI - Beautiful, responsive call interface out of the box ✅ Mobile API - RESTful API endpoints for mobile app integration

Requirements
Installation
Configuration
Usage
- Web Integration
- API Integration
Mobile App Integration
Customization
Broadcasting Setup
Testing
Troubleshooting
Contributing
License

Requirements

PHP 8.1 or higher
Laravel 10.0 or higher
ZegoCloud account (Get one here)
Laravel Sanctum (for API authentication)
Laravel Echo & Pusher (for real-time broadcasting)

Installation

Step 1: Install via Composer

composer require mainul12501/zego-audio-video-calling

Step 2: Publish Package Assets

php artisan vendor:publish --provider="ZegoAudioVideoCalling\ZegoAudioVideoCallingServiceProvider"

Or publish individually:

# Publish configuration
php artisan vendor:publish --tag=zego-calling-config

# Publish migrations
php artisan vendor:publish --tag=zego-calling-migrations

# Publish views (optional, for customization)
php artisan vendor:publish --tag=zego-calling-views

# Publish assets (CSS/JS)
php artisan vendor:publish --tag=zego-calling-assets

Step 3: Run Migrations

php artisan migrate

This will create:

calls table - Stores call records
Add device-related columns to users table (device_token, device_platform, is_online, last_seen)

Configuration

Step 1: Add ZegoCloud Credentials to `.env`

# ZegoCloud Configuration
ZEGOCLOUD_APP_ID=your_app_id_here
ZEGOCLOUD_SERVER_SECRET=your_server_secret_here

# Push Notifications (Optional - for mobile apps)
ZEGO_PUSH_NOTIFICATIONS_ENABLED=true

# FCM Configuration (Android)
FCM_SERVER_KEY=your_fcm_server_key

# APNs Configuration (iOS)
APN_KEY_ID=your_apn_key_id
APN_TEAM_ID=your_apple_team_id
APN_BUNDLE_ID=com.yourapp.bundleid
APN_KEY_PATH=/path/to/AuthKey.p8
APN_PRODUCTION=false

# Broadcasting Configuration
BROADCAST_DRIVER=pusher
PUSHER_APP_ID=your_pusher_app_id
PUSHER_APP_KEY=your_pusher_key
PUSHER_APP_SECRET=your_pusher_secret
PUSHER_APP_CLUSTER=your_cluster

# Optional Settings
ZEGO_MAX_CALL_DURATION=3600
ZEGO_AUTO_END_MISSED_CALLS=true
ZEGO_MISSED_CALL_TIMEOUT=60

Step 2: Get Your ZegoCloud Credentials

Go to ZegoCloud Console
Create a new project or select existing one
Get your App ID and Server Secret from the project settings

That's it! The package is now ready to use.

Usage

Web Integration

Basic Implementation

Add call buttons to your Blade template:

<!-- In your chat or user profile page -->
@auth
    <div class="call-buttons">
        <button onclick="initiateVideoCall({{ $user->id }})">
            📹 Video Call
        </button>
        <button onclick="initiateAudioCall({{ $user->id }})">
            📞 Audio Call
        </button>
    </div>

    <!-- Include the call initiator script -->
    <script src="{{ asset('vendor/zego-calling/js/call-initiator.js') }}"></script>
    <script>
        const csrfToken = '{{ csrf_token() }}';

        function initiateVideoCall(userId) {
            ZegoCloudCaller.initiateCall(userId, 'video', csrfToken);
        }

        function initiateAudioCall(userId) {
            ZegoCloudCaller.initiateCall(userId, 'audio', csrfToken);
        }
    </script>
@endauth

Using Helper Methods

Or use the built-in button creators:

<script src="{{ asset('vendor/zego-calling/js/call-initiator.js') }}"></script>
<div id="call-buttons"></div>

<script>
    const csrfToken = '{{ csrf_token() }}';
    const userId = {{ $user->id }};
    const callButtons = document.getElementById('call-buttons');

    // Add video call button
    callButtons.appendChild(
        ZegoCloudCaller.createVideoCallButton(userId, csrfToken)
    );

    // Add audio call button
    callButtons.appendChild(
        ZegoCloudCaller.createAudioCallButton(userId, csrfToken)
    );
</script>

Programmatic Call Initiation

You can also initiate calls programmatically via AJAX:

// Initiate video call
fetch('/call/initiate', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'X-CSRF-TOKEN': csrfToken
    },
    body: JSON.stringify({
        receiver_id: userId,
        call_type: 'video'
    })
})
.then(response => response.json())
.then(data => {
    if (data.success) {
        window.location.href = data.room_url;
    }
});

API Integration

The package provides RESTful API endpoints for both web and mobile applications.

Web API Endpoints

Base URL: /api/call (requires authentication via Sanctum)

POST   /api/call/initiate            # Initiate a new call
POST   /api/call/{call}/accept       # Accept an incoming call
POST   /api/call/{call}/reject       # Reject an incoming call
POST   /api/call/{call}/end          # End an active call
GET    /api/call/{call}/details      # Get call details
POST   /api/call/generate-token      # Generate ZegoCloud token

Mobile API Endpoints

Base URL: /api/mobile/call (requires authentication via Sanctum)

POST   /api/mobile/call/register-device                # Register device for push notifications
POST   /api/mobile/call/update-online-status           # Update user online status
POST   /api/mobile/call/initiate                       # Initiate a call
POST   /api/mobile/call/{callId}/accept                # Accept a call
POST   /api/mobile/call/{callId}/reject                # Reject a call
POST   /api/mobile/call/{callId}/end                   # End a call
GET    /api/mobile/call/active-calls                   # Get active calls
GET    /api/mobile/call/call-history                   # Get call history
GET    /api/mobile/call/{callId}/details               # Get call details
GET    /api/mobile/call/user/{userId}/availability     # Check user availability
POST   /api/mobile/call/generate-token                 # Generate token

Example: Initiate Call (API)

// Request
POST /api/call/initiate
Content-Type: application/json
Authorization: Bearer {token}

{
    "receiver_id": 2,
    "call_type": "video"
}

// Response
{
    "success": true,
    "call": {
        "id": 123,
        "caller_id": 1,
        "receiver_id": 2,
        "room_id": "room_xyz123_1638475647",
        "call_type": "video",
        "status": "initiated",
        "created_at": "2024-01-15T10:30:00Z"
    },
    "room_url": "/call/call-page?roomID=room_xyz123_1638475647&type=video&chatWith=2"
}

Mobile App Integration

For mobile app integration (iOS/Android), see the comprehensive guide:

📱 Mobile Integration Guide

The mobile integration guide includes:

Complete Android (Kotlin) implementation
Complete iOS (Swift) implementation
Push notification setup for both platforms
WebSocket integration for real-time updates
ZegoCloud SDK integration
Code examples and best practices

Quick Start for Mobile Developers

Register Device:

POST /api/mobile/call/register-device
{
    "device_token": "fcm_or_apn_device_token",
    "device_platform": "android" // or "ios"
}

Listen for Incoming Calls via:
- Push notifications (when app is in background)
- WebSocket events (when app is active)
Accept/Reject Calls:

POST /api/mobile/call/{callId}/accept
POST /api/mobile/call/{callId}/reject

Join ZegoCloud Room using the provided configuration in the response

Customization

Customizing Routes

Edit config/zego-calling.php:

'routes' => [
    'web' => [
        'enabled' => true,
        'prefix' => 'call',                    // Change route prefix
        'middleware' => ['web', 'auth'],       // Add custom middleware
    ],
    'mobile' => [
        'enabled' => true,
        'prefix' => 'api/mobile/call',
        'middleware' => ['api', 'auth:sanctum'],
    ],
],

Customizing the UI

Publish the views:

php artisan vendor:publish --tag=zego-calling-views

Then edit the views in resources/views/vendor/zego-calling/.

Customizing the User Model

In config/zego-calling.php:

'user_model' => App\Models\User::class,

Call Settings

'call_settings' => [
    'max_call_duration' => 3600,              // Maximum call duration in seconds
    'auto_end_missed_calls' => true,          // Auto-end missed calls
    'missed_call_timeout' => 60,              // Missed call timeout in seconds
    'enable_call_history' => true,            // Enable call history tracking
],

Broadcasting Setup

The package uses Laravel Broadcasting for real-time call state synchronization. You need to configure broadcasting in your Laravel application.

Step 1: Install Laravel Echo and Pusher

npm install --save-dev laravel-echo pusher-js

Step 2: Configure Broadcasting

In resources/js/bootstrap.js:

import Echo from 'laravel-echo';
import Pusher from 'pusher-js';

window.Pusher = Pusher;

window.Echo = new Echo({
    broadcaster: 'pusher',
    key: import.meta.env.VITE_PUSHER_APP_KEY,
    cluster: import.meta.env.VITE_PUSHER_APP_CLUSTER,
    forceTLS: true
});

Step 3: Listen for Call Events

// Listen for incoming calls
Echo.private(`user.${userId}`)
    .listen('.call.initiated', (e) => {
        console.log('Incoming call from:', e.caller.name);
        // Show incoming call notification
        showIncomingCallNotification(e);
    })
    .listen('.call.accepted', (e) => {
        console.log('Call accepted');
        // Join call room
    })
    .listen('.call.rejected', (e) => {
        console.log('Call rejected');
        // Show rejection message
    })
    .listen('.call.ended', (e) => {
        console.log('Call ended');
        // Close call interface
    });

Testing

Run the package tests:

composer test

Or run specific test suites:

# Test call initiation
php artisan test --filter CallInitiationTest

# Test mobile API
php artisan test --filter MobileApiTest

Troubleshooting

Calls Not Connecting

Check ZegoCloud Credentials: Ensure ZEGOCLOUD_APP_ID and ZEGOCLOUD_SERVER_SECRET are correct in .env
Verify Broadcasting Setup: Make sure Laravel Echo is properly configured
Check Firewall: Ensure WebSocket ports are open

Push Notifications Not Working

FCM (Android):
- Verify FCM_SERVER_KEY in .env
- Check device token registration
- Ensure Firebase is properly configured in your mobile app
APNs (iOS):
- Verify all APN credentials are correct
- Ensure certificates are not expired
- Check bundle ID matches

WebSocket Connection Fails

Check .env broadcasting configuration
Verify Pusher credentials
Ensure Laravel Echo is imported and initialized
Check browser console for connection errors

Video/Audio Not Working

Check Browser Permissions: Ensure camera/microphone access is granted
HTTPS Required: ZegoCloud requires HTTPS in production
Check Device Compatibility: Verify browser supports WebRTC

Upgrade Guide

From 1.x to 2.x

# Backup your database
php artisan backup:run

# Update package
composer update mainul12501/zego-audio-video-calling

# Publish new assets
php artisan vendor:publish --tag=zego-calling-config --force

# Run migrations
php artisan migrate

# Clear cache
php artisan config:clear
php artisan view:clear

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

Security

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

Credits

License

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

Support

📧 Email: mainul12501@gmail.com
🐛 Issues: GitHub Issues
📖 Documentation: Full Documentation
💬 Discussions: GitHub Discussions

Made with ❤️ by Mainul Islam

mainul12501 / zego-audio-video-calling

Maintainers

Details