README

Laravel package to send WhatsApp messages through TawHub API.

Features

• Send plain text messages
• Send text messages with file URL
• Send template messages with dynamic variables
• Works via Facade or Dependency Injection
• Input validation for phone number and file extension
• Configurable retries/backoff and request logging

Installation

composer require tawhub/laravel-sdk

Publish package config:

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

Configuration

Set values in .env:

TAWHUB_BASE_URL=https://tawhub.com/api/create-message
TAWHUB_APP_KEY=your_app_key
TAWHUB_AUTH_KEY=your_auth_key
TAWHUB_SANDBOX=false
TAWHUB_TIMEOUT=30
TAWHUB_RETRY_TIMES=2
TAWHUB_RETRY_SLEEP_MS=250
TAWHUB_RETRY_BACKOFF=fixed
TAWHUB_LOGGING_ENABLED=false
TAWHUB_LOG_CHANNEL=stack
TAWHUB_LOG_INCLUDE_PAYLOAD=false

Config file: config/tawhub.php

Retry and Logging

• TAWHUB_RETRY_TIMES: number of retries after first failed attempt.
• TAWHUB_RETRY_SLEEP_MS: delay in milliseconds before retry.
• TAWHUB_RETRY_BACKOFF: fixed or exponential.
• TAWHUB_LOGGING_ENABLED: enable request lifecycle logs.
• TAWHUB_LOG_CHANNEL: log channel name from Laravel logging config.
• TAWHUB_LOG_INCLUDE_PAYLOAD: include masked payload in logs.

Usage

1) Text Message

use Tawhub\Laravel\Facades\Tawhub;

$response = Tawhub::send_text('201001112223', 'Welcome from Laravel');

2) Text Message + File

$response = Tawhub::send_text_with_file(
    '201001112223',
    'Invoice attached',
    'https://example.com/invoice.pdf'
);

3) Template Message

$response = Tawhub::send_template('201001112223', 'WELCOME_01', [
    'name' => 'Essam',
    'order_id' => '5566',
]);

4) Dependency Injection (recommended)

use Tawhub\Laravel\Contracts\TawhubClientInterface;

public function send(TawhubClientInterface $tawhub): void
{
    $tawhub->send_text('201001112223', 'Hello!');
}

API Response Example

{
  "message_status": "Success",
  "data": {
    "from": "SENDER_NUMBER",
    "to": "RECEIVER_NUMBER",
    "status_code": 200
  }
}

Error Handling

The package throws:

• Tawhub\\Laravel\\Exceptions\\InvalidPayloadException
• Tawhub\\Laravel\\Exceptions\\RequestFailedException

Example:

try {
    $response = Tawhub::send_text('201001112223', 'Hello');
} catch (\Tawhub\Laravel\Exceptions\TawhubException $exception) {
    report($exception);
}

Testing

composer install
composer test

Laravel App Integration Example

Ready-to-copy sample is available in examples/laravel-integration/:

• examples/laravel-integration/app/Http/Controllers/TawhubDemoController.php
• examples/laravel-integration/app/Jobs/SendTawhubMessageJob.php
• examples/laravel-integration/routes/web.php

The flow validates request input in the controller, dispatches a queue job, then sends text/template/file message based on payload.

Release

• Current release: v1.0.0
• Changelog: CHANGELOG.md

Notes

• to must be full WhatsApp number with country code, digits only.
• Allowed file extensions: jpg, jpeg, png, webp, pdf, docx, xlsx, csv, txt.
• sandbox is sent as true or false string to match TawHub API examples.