PHP SDK (Laravel)

Official Laravel package for integrating with the CubeConnect WhatsApp Business API.

Requirements

• PHP 8.1+
• Laravel 10, 11, or 12

Installation

composer require cubeconnect/laravel

Publish the configuration file:

php artisan vendor:publish --tag=cubeconnect-config

Configuration

Add your API key to .env:

CUBECONNECT_API_KEY=your_api_key_here

Optional settings:

CUBECONNECT_URL=https://cubeconnect.io
CUBECONNECT_TENANT_ID=
CUBECONNECT_TIMEOUT=30

Sending Messages

Text Message

use CubeConnect\Facades\CubeConnect;

$response = CubeConnect::sendText('+966501234567', 'Hello from Laravel!');

echo $response->status;               // "queued"
echo $response->messageLogId;         // 4521
echo $response->conversationCategory; // "SERVICE"

24-Hour Window

Text messages require the customer to have messaged you within the last 24 hours. For first-time messages, use sendTemplate().

Template Message

$response = CubeConnect::sendTemplate(
    '+966501234567',
    'order_confirmation',
    ['ORD-1234', '500 SAR']
);

Parameters map to 1, 2, etc. in the template body. Templates can be sent anytime.

Template Without Parameters

$response = CubeConnect::sendTemplate('+966501234567', 'welcome_message');

Health Check

$health = CubeConnect::health();

if ($health['status'] === 'healthy') {
    // Platform is operational
}

Response Object

All message methods return a MessageResponse object:

$response = CubeConnect::sendText('+966501234567', 'Hello!');

$response->status;               // "queued"
$response->messageLogId;         // 4521
$response->conversationCategory; // "SERVICE"
$response->cost;                 // 0.0
$response->queued();             // true
$response->toArray();            // Array representation

Property	Type	Description
status	string	Always queued on success
messageLogId	int	Unique tracking ID
conversationCategory	string	SERVICE, MARKETING, UTILITY, or AUTHENTICATION
cost	float	Message cost

Error Handling

All exceptions include an errorCode property matching the API error codes:

use CubeConnect\Facades\CubeConnect;
use CubeConnect\Exceptions\AuthenticationException;
use CubeConnect\Exceptions\ValidationException;
use CubeConnect\Exceptions\RateLimitException;
use CubeConnect\Exceptions\NotFoundException;
use CubeConnect\Exceptions\CubeConnectException;

try {
    CubeConnect::sendText('+966501234567', 'Hello!');
} catch (AuthenticationException $e) {
    // 401 — Invalid or missing API key
    // 403 — Insufficient permissions or tenant issues
    echo $e->errorCode;  // "INVALID_API_KEY", "AUTHENTICATION_REQUIRED",
                          // "API_KEY_NO_TENANT", "TENANT_NOT_FOUND", "FORBIDDEN"
    echo $e->statusCode; // 401 or 403
} catch (ValidationException $e) {
    // 422 — Invalid request data
    echo $e->errorCode;  // "VALIDATION_ERROR", "NO_ACTIVE_ACCOUNT",
                          // "MISSING_ACCESS_TOKEN", "INVALID_PHONE_NUMBER"
    print_r($e->errors);
    // ['phone' => ['The phone field is required.']]
} catch (NotFoundException $e) {
    // 404 — Resource not found
    echo $e->errorCode; // "NOT_FOUND", "TEMPLATE_NOT_FOUND"
} catch (RateLimitException $e) {
    // 429 — Rate limit or plan limit exceeded
    echo $e->errorCode; // "RATE_LIMIT_EXCEEDED", "PLAN_LIMIT_REACHED",
                         // "SUBSCRIPTION_EXPIRED"
    // Implement backoff and retry
} catch (CubeConnectException $e) {
    // 5xx or network errors
    echo $e->errorCode;  // "INTERNAL_ERROR", "MESSAGE_SEND_FAILED", "CONNECTION_FAILED"
    echo $e->statusCode;
}

Dependency Injection

You can inject the Messaging contract instead of using the facade:

use CubeConnect\Contracts\Messaging;

class OrderController extends Controller
{
    public function shipped(Order $order, Messaging $messaging)
    {
        $messaging->sendTemplate(
            $order->customer_phone,
            'order_shipped',
            [$order->id, $order->tracking_number]
        );
    }
}

Real-World Examples

E-Commerce Order Confirmation

// In your OrderController or Observer
use CubeConnect\Facades\CubeConnect;

public function store(Request $request)
{
    $order = Order::create($request->validated());

    CubeConnect::sendTemplate(
        $order->customer->phone,
        'order_confirmation',
        [$order->reference, $order->total . ' SAR']
    );

    return redirect()->route('orders.show', $order);
}

OTP Verification

$code = str_pad(random_int(0, 999999), 6, '0', STR_PAD_LEFT);
cache()->put("otp:{$phone}", $code, now()->addMinutes(5));

CubeConnect::sendTemplate($phone, 'verification_code', [$code]);

Scheduled Notifications

// In a scheduled command or job
$expiringOrders = Order::where('expires_at', '<', now()->addDay())->get();

foreach ($expiringOrders as $order) {
    try {
        CubeConnect::sendTemplate(
            $order->customer->phone,
            'order_expiring',
            [$order->reference, $order->expires_at->format('Y-m-d')]
        );
    } catch (RateLimitException $e) {
        // Re-queue for later
        SendWhatsAppNotification::dispatch($order)->delay(now()->addMinute());
        break;
    }
}

Source Code

GitHub: github.com/cubeconnect/laravel