PHPackages                             mg-techlegend/laravel-beem-africa - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. mg-techlegend/laravel-beem-africa

ActiveLibrary[API Development](/categories/api)

mg-techlegend/laravel-beem-africa
=================================

A comprehensive Laravel package for integrating with Beem Africa's API services including SMS, OTP, Airtime, USSD, Voice, and Insights. Provides a clean, expressive interface with Laravel Notifications support, typed responses, and robust error handling.

v3.0.0(1mo ago)129[4 PRs](https://github.com/mg-techlegend/laravel-beem-africa/pulls)MITPHPPHP ^8.4CI passing

Since May 21Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/mg-techlegend/laravel-beem-africa)[ Packagist](https://packagist.org/packages/mg-techlegend/laravel-beem-africa)[ Docs](https://github.com/mg-techlegend/laravel-beem-africa)[ GitHub Sponsors](https://github.com/TechLegend)[ RSS](/packages/mg-techlegend-laravel-beem-africa/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (8)Dependencies (22)Versions (15)Used By (0)

Laravel Beem Africa
===================

[](#laravel-beem-africa)

[![Latest Version on Packagist](https://camo.githubusercontent.com/a2974ac07dd27cb37443d718f7512578748fff6f4afe74caa5adf28f46b50eae/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6d672d746563686c6567656e642f6c61726176656c2d6265656d2d6166726963612e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/mg-techlegend/laravel-beem-africa)[![GitHub Tests Action Status](https://camo.githubusercontent.com/3b6e91bb12384f8972bd05e4fcb8ad3ef48afb03c091457ac271a25b4310e46c/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6d672d746563686c6567656e642f6c61726176656c2d6265656d2d6166726963612f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/mg-techlegend/laravel-beem-africa/actions?query=workflow%3Arun-tests+branch%3Amain)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/795a3415cfcf51cd28bf23bc71dbc0edf5d6b59ffca3eb31a2755f630861178c/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6d672d746563686c6567656e642f6c61726176656c2d6265656d2d6166726963612f6669782d7068702d636f64652d7374796c652d6973737565732e796d6c3f6272616e63683d6d61696e266c6162656c3d636f64652532307374796c65267374796c653d666c61742d737175617265)](https://github.com/mg-techlegend/laravel-beem-africa/actions?query=workflow%3A%22Fix+PHP+code+style+issues%22+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/7f510627f23e9baeca806175e4ec22a5f237f9e64a418ed7e00afec461ca6e90/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6d672d746563686c6567656e642f6c61726176656c2d6265656d2d6166726963612e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/mg-techlegend/laravel-beem-africa)

**A comprehensive Laravel package to integrate with Beem Africa's API services.**

This package provides a simple, elegant way to use [Beem Africa](https://beem.africa)'s API services in your Laravel applications. It integrates seamlessly with Laravel's native notification system and provides easy access to all Beem services including SMS, OTP, Airtime, USSD, Voice, and Insights.

---

📦 Installation
--------------

[](#-installation)

You can install the package via Composer:

```
composer require mg-techlegend/laravel-beem-africa
```

Then, publish the config file:

```
php artisan vendor:publish --tag="laravel-beem-africa-config"
```

Update your `.env` file with your Beem credentials:

```
BEEM_API_KEY=your-api-key
BEEM_SECRET_KEY=your-secret
BEEM_SENDER_NAME=your-sender-name

# Optional: Custom endpoints (if needed)
BEEM_SMS_ENDPOINT=https://apisms.beem.africa/v1/send
BEEM_OTP_ENDPOINT=https://apisms.beem.africa/v1/otp
BEEM_AIRTIME_ENDPOINT=https://apisms.beem.africa/v1/airtime
BEEM_USSD_ENDPOINT=https://apisms.beem.africa/v1/ussd
BEEM_VOICE_ENDPOINT=https://apisms.beem.africa/v1/voice
BEEM_INSIGHTS_ENDPOINT=https://apisms.beem.africa/v1/insights

# Webhook settings (optional)
BEEM_WEBHOOKS_ENABLED=true
BEEM_WEBHOOK_SECRET=your-webhook-secret
BEEM_WEBHOOK_ENDPOINT=https://your-app.com/webhooks/beem
```

---

🛠 Configuration
---------------

[](#-configuration)

The config file `config/beem.php` contains comprehensive settings:

```
return [
    'api_key' => env('BEEM_API_KEY'),
    'secret_key' => env('BEEM_SECRET_KEY'),
    'sender_name' => env('BEEM_SENDER_NAME', 'INFO'),

    // API Endpoints
    'endpoints' => [
        'sms' => env('BEEM_SMS_ENDPOINT', 'https://apisms.beem.africa/v1/send'),
        'otp' => env('BEEM_OTP_ENDPOINT', 'https://apisms.beem.africa/v1/otp'),
        'airtime' => env('BEEM_AIRTIME_ENDPOINT', 'https://apisms.beem.africa/v1/airtime'),
        'ussd' => env('BEEM_USSD_ENDPOINT', 'https://apisms.beem.africa/v1/ussd'),
        'voice' => env('BEEM_VOICE_ENDPOINT', 'https://apisms.beem.africa/v1/voice'),
        'insights' => env('BEEM_INSIGHTS_ENDPOINT', 'https://apisms.beem.africa/v1/insights'),
    ],

    // Default settings for different services
    'defaults' => [
        'sms' => [
            'encoding' => 0, // 0 for GSM7, 1 for UCS2
        ],
        'otp' => [
            'length' => 6,
            'expiry' => 300, // 5 minutes in seconds
            'type' => 'numeric', // numeric, alphanumeric
        ],
        'airtime' => [
            'currency' => 'TZS',
        ],
        'voice' => [
            'language' => 'en',
            'voice_id' => 1,
        ],
    ],

    // Webhook settings
    'webhooks' => [
        'enabled' => env('BEEM_WEBHOOKS_ENABLED', false),
        'secret' => env('BEEM_WEBHOOK_SECRET'),
        'endpoint' => env('BEEM_WEBHOOK_ENDPOINT'),
    ],
];
```

---

🚀 Usage
-------

[](#-usage)

### 1. SMS Service

[](#1-sms-service)

#### Using the Facade (Quick Methods)

[](#using-the-facade-quick-methods)

```
use TechLegend\LaravelBeemAfrica\BeemFacade;

// Simple SMS send
$result = BeemFacade::sendSms('255700000001', 'Hello from Beem!', 'MyApp');
```

#### Using the SMS Service Directly

[](#using-the-sms-service-directly)

```
use TechLegend\LaravelBeemAfrica\SMS\BeemMessage;

$smsService = BeemFacade::sms();
$message = BeemMessage::create('Your order has been shipped!')
    ->sender('MyStore')
    ->encoding(0); // GSM7 encoding

$recipients = [
    ['recipient_id' => 0, 'dest_addr' => '255700000001'],
    ['recipient_id' => 1, 'dest_addr' => '255700000002'],
];

$result = $smsService->sendMessage($message, $recipients);
```

#### Laravel Notifications

[](#laravel-notifications)

```
use Illuminate\Notifications\Notification;
use TechLegend\LaravelBeemAfrica\SMS\BeemMessage;

class OrderShippedNotification extends Notification
{
    public function via($notifiable): array
    {
        return ['beem'];
    }

    public function toBeem($notifiable): BeemMessage
    {
        return BeemMessage::create('Your order has been shipped!')
            ->sender('MyStore')
            ->encoding(0);
    }
}

// Use in your model
$user->notify(new OrderShippedNotification());
```

### 2. OTP Service

[](#2-otp-service)

```
// Generate OTP
$otpResult = BeemFacade::generateOtp('255700000001', [
    'length' => 6,
    'expiry' => 300, // 5 minutes
    'type' => 'numeric',
    'message' => 'Your verification code is: {code}',
]);

// Verify OTP
$verifyResult = BeemFacade::verifyOtp('255700000001', '123456', $otpResult['request_id']);

// Resend OTP
$resendResult = BeemFacade::otp()->resendOtp('255700000001', $otpResult['request_id']);
```

### 3. Airtime Service

[](#3-airtime-service)

```
// Send airtime
$airtimeResult = BeemFacade::sendAirtime('255700000001', 1000.00, [
    'currency' => 'TZS',
    'message' => 'Airtime sent successfully',
]);

// Get airtime balance
$balanceResult = BeemFacade::airtime()->getAirtimeBalance();

// Get transaction history
$historyResult = BeemFacade::airtime()->getTransactionHistory([
    'start_date' => '2024-01-01',
    'end_date' => '2024-12-31',
    'phone_number' => '255700000001',
]);

// Get transaction status
$statusResult = BeemFacade::airtime()->getTransactionStatus($airtimeResult['transaction_id']);
```

### 4. USSD Service

[](#4-ussd-service)

```
// Create USSD menu
$menuData = [
    'menu_name' => 'My Service Menu',
    'menu_items' => [
        [
            'id' => 1,
            'text' => 'Check Balance',
            'action' => 'check_balance',
        ],
        [
            'id' => 2,
            'text' => 'Send Money',
            'action' => 'send_money',
        ],
    ],
    'welcome_message' => 'Welcome to My Service',
    'goodbye_message' => 'Thank you for using our service',
];

$menuResult = BeemFacade::ussd()->createMenu($menuData);

// Get menu details
$menuDetails = BeemFacade::ussd()->getMenu($menuResult['menu_id']);

// List all menus
$menus = BeemFacade::ussd()->listMenus(['page' => 1, 'limit' => 10]);

// Update menu
$updateResult = BeemFacade::ussd()->updateMenu($menuResult['menu_id'], [
    'welcome_message' => 'Updated welcome message',
]);

// Delete menu
$deleteResult = BeemFacade::ussd()->deleteMenu($menuResult['menu_id']);
```

### 5. Voice Service

[](#5-voice-service)

```
// Make voice call
$callResult = BeemFacade::makeCall('255700000001', 'Hello, this is a voice message', [
    'language' => 'en',
    'voice_id' => 1,
    'repeat_count' => 2,
]);

// Get call status
$callStatus = BeemFacade::voice()->getCallStatus($callResult['call_id']);

// Get call history
$callHistory = BeemFacade::voice()->getCallHistory([
    'start_date' => '2024-01-01',
    'end_date' => '2024-12-31',
    'phone_number' => '255700000001',
    'status' => 'completed',
]);

// Cancel call
$cancelResult = BeemFacade::voice()->cancelCall($callResult['call_id']);

// Get available voices
$voices = BeemFacade::voice()->getAvailableVoices();
```

### 6. Insights Service

[](#6-insights-service)

```
// Get account balance
$accountBalance = BeemFacade::getBalance();

// Get message delivery report
$deliveryReport = BeemFacade::insights()->getMessageDeliveryReport($result['request_id']);

// Get message statistics
$statistics = BeemFacade::insights()->getMessageStatistics([
    'start_date' => '2024-01-01',
    'end_date' => '2024-12-31',
    'sender_name' => 'MyApp',
]);

// Get message history
$messageHistory = BeemFacade::insights()->getMessageHistory([
    'start_date' => '2024-01-01',
    'end_date' => '2024-12-31',
    'phone_number' => '255700000001',
    'status' => 'delivered',
    'page' => 1,
    'limit' => 20,
]);

// Get failed messages
$failedMessages = BeemFacade::insights()->getFailedMessages([
    'start_date' => '2024-01-01',
    'end_date' => '2024-12-31',
    'error_code' => 'INVALID_NUMBER',
]);

// Get error codes
$errorCodes = BeemFacade::insights()->getErrorCodes();
```

### 7. Webhooks

[](#7-webhooks)

```
// In your webhook controller
use Illuminate\Http\Request;

public function handleWebhook(Request $request)
{
    $result = BeemFacade::webhooks()->handle($request);

    if ($result['successful']) {
        $eventType = $result['event_type'];
        $data = $result['data'];

        switch ($eventType) {
            case 'delivery_report':
                $processed = BeemFacade::webhooks()->processDeliveryReport($data);
                break;
            case 'otp_verification':
                $processed = BeemFacade::webhooks()->processOtpVerification($data);
                break;
            case 'airtime_transaction':
                $processed = BeemFacade::webhooks()->processAirtimeTransaction($data);
                break;
        }

        return response()->json(['status' => 'success'], 200);
    }

    return response()->json(['status' => 'error'], 400);
}
```

### 8. Dependency Injection

[](#8-dependency-injection)

```
use TechLegend\LaravelBeemAfrica\Beem;

class NotificationController
{
    public function __construct(private Beem $beem)
    {
    }

    public function sendNotification()
    {
        // Send SMS
        $smsResult = $this->beem->sendSms('255700000001', 'Hello!');

        // Generate OTP
        $otpResult = $this->beem->generateOtp('255700000001');

        // Send airtime
        $airtimeResult = $this->beem->sendAirtime('255700000001', 500.00);

        // Make voice call
        $callResult = $this->beem->makeCall('255700000001', 'Important message');

        return response()->json([
            'sms' => $smsResult,
            'otp' => $otpResult,
            'airtime' => $airtimeResult,
            'call' => $callResult,
        ]);
    }
}
```

### 9. Error Handling

[](#9-error-handling)

```
try {
    $result = BeemFacade::sendSms('255700000001', 'Test message');

    if (!$result['successful']) {
        // Handle error
        Log::error('SMS sending failed', [
            'error' => $result['message'],
            'status_code' => $result['status_code'],
        ]);

        // You can also check for specific error types
        if (isset($result['error'])) {
            // Handle specific error
        }
    }
} catch (\Exception $e) {
    Log::error('Beem service exception', [
        'message' => $e->getMessage(),
        'trace' => $e->getTraceAsString(),
    ]);
}
```

---

📋 Available Services
--------------------

[](#-available-services)

ServiceDescriptionMethods**SMS**Send SMS messages`sendSms()`, `sendMessage()`**OTP**Generate and verify OTP codes`generateOtp()`, `verifyOtp()`, `resendOtp()`**Airtime**Send airtime and manage transactions`sendAirtime()`, `getAirtimeBalance()`, `getTransactionHistory()`**USSD**Create and manage USSD menus`createMenu()`, `getMenu()`, `updateMenu()`, `deleteMenu()`**Voice**Make voice calls`makeCall()`, `getCallStatus()`, `getCallHistory()`**Insights**Analytics and reporting`getBalance()`, `getMessageStatistics()`, `getMessageHistory()`**Webhooks**Handle incoming webhooks`handle()`, `processDeliveryReport()`---

✅ Testing
---------

[](#-testing)

```
composer test
```

Tests are written using [Pest](https://pestphp.com/) and run automatically via GitHub Actions on every push.

---

📄 Changelog
-----------

[](#-changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

---

🤝 Contributing
--------------

[](#-contributing)

Contributions are welcome! Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

---

🔒 Security
----------

[](#-security)

If you discover any security issues, please review [our security policy](../../security/policy) to report them.

---

👨‍💻 Credits
-----------

[](#‍-credits)

- [Thomson Maguru](https://github.com/tomsgad)
- [TechLegend](https://github.com/mg-techlegend)
- [All Contributors](../../contributors)

---

📜 License
---------

[](#-license)

The MIT License (MIT). Please see the [LICENSE](LICENSE.md) file for more information.

###  Health Score

46

—

FairBetter than 93% of packages

Maintenance92

Actively maintained with recent releases

Popularity9

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity62

Established project with proven stability

 Bus Factor1

Top contributor holds 89.6% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~35 days

Recently: every ~78 days

Total

10

Last Release

38d ago

Major Versions

1.2.1 → 2.0.0-beta2025-08-30

v2.x-dev → v3.0.02026-04-05

### Community

Maintainers

![](https://www.gravatar.com/avatar/56c4789bdb51c177e35cc83e021eee7eab4d0316e03f1a652fa0eab181bd2844?d=identicon)[tomsgad](/maintainers/tomsgad)

---

Top Contributors

[![tomsgad](https://avatars.githubusercontent.com/u/2600024?v=4)](https://github.com/tomsgad "tomsgad (43 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (3 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (2 commits)")

---

Tags

beemlaraveltechlegendlaravelotpsmsInsightswebhooksvoiceairtimeussdbeem-africaTechLegendlaravel-beem-africa

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/mg-techlegend-laravel-beem-africa/health.svg)

```
[![Health](https://phpackages.com/badges/mg-techlegend-laravel-beem-africa/health.svg)](https://phpackages.com/packages/mg-techlegend-laravel-beem-africa)
```

###  Alternatives

[africastalking/africastalking

Official Africa's Talking PHP SDK

122557.6k10](/packages/africastalking-africastalking)[ryangjchandler/bearer

Minimalistic token-based authentication for Laravel API endpoints.

8129.8k](/packages/ryangjchandler-bearer)[stechstudio/laravel-hubspot

A Laravel SDK for the HubSpot CRM Api

2971.0k](/packages/stechstudio-laravel-hubspot)[simplestats-io/laravel-client

Client for SimpleStats!

4515.5k](/packages/simplestats-io-laravel-client)[scalar/laravel

Render your OpenAPI-based API reference

6183.9k2](/packages/scalar-laravel)[combindma/laravel-facebook-pixel

Meta pixel integration for Laravel

4956.9k](/packages/combindma-laravel-facebook-pixel)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)