README

📘 Overview

The GradiWapp PHP SDK provides a clean, developer-friendly wrapper around the GradiWapp External API, powering multi-tenant WhatsApp messaging at scale.

It supports:

• All message types (text, image, media, file, location…)
• Webhooks
• Timezone-aware scheduling
• Multi-session messaging
• Laravel 7–12 integration
• Full HMAC authentication

This SDK is production-ready and built with Stripe/Twilio-level documentation quality.

📑 Table of Contents

• Overview
• Features
• Requirements
• Installation
  • Non-Laravel
  • Laravel 7–12
• Configuration
• Quick Start
  • Plain PHP
  • Laravel DI
  • Laravel Facade
• Messaging
  • Text
  • Image
  • Media
  • Location
  • Link
  • File
  • Contact
  • Reply
  • Combined
• Scheduling
• Message Status
• Webhooks
• Error Handling
• Advanced Usage
• Response Format
• Versioning
• Contributing
• License

🚀 Features

• ✔ Framework-agnostic (PHP 7.4+)
• ✔ First-class Laravel 7–12 integration
• ✔ Fully typed methods + PHPDoc
• ✔ Timezone-aware scheduling (ISO8601 + IANA)
• ✔ Webhook creation + signature verification
• ✔ All message types supported
• ✔ Clean exceptions & error classes
• ✔ Internal base URL (cannot be changed)
• ✔ Production-ready architecture

🧩 Requirements

📥 Installation

Non-Laravel Installation

composer require gradiwapp/gradiwapp-php-sdk

Before publishing on Packagist:

{
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/ahmednaserdev/gradiwapp-php-sdk.git"
    }
  ],
  "require": {
    "gradiwapp/gradiwapp-php-sdk": "dev-main"
  }
}

Laravel Installation

composer require gradiwapp/gradiwapp-php-sdk

Publish config:

php artisan vendor:publish --provider="GradiWapp\Sdk\Laravel\GradiWappServiceProvider" --tag=config

This generates:

• config/gradiwapp.php

Add environment variables:

GRADIWAPP_API_KEY=your_key
GRADIWAPP_API_SECRET=your_secret
GRADIWAPP_TIMEOUT=30
GRADIWAPP_MAX_RETRIES=1
GRADIWAPP_VERIFY_SSL=true

Note: Base URL is internal and cannot be changed.

⚡ Quick Start

Plain PHP Example

use GradiWapp\Sdk\Client;
use GradiWapp\Sdk\Config;

$config = new Config(
    apiKey: 'your_key',
    apiSecret: 'your_secret'
);

$client = new Client($config);

$response = $client->messages()->sendText(
    to: '+123456',
    body: 'Hello from GradiWapp!'
);

Laravel — Dependency Injection

public function send(GradiWapp\Sdk\Client $client)
{
    return $client->messages()->sendText(
        to: '+123456',
        body: 'Hello!'
    );
}

Laravel — Facade

use GradiWapp\Sdk\Laravel\Facades\GradiWapp;

GradiWapp::messages()->sendText('+123456', 'Hello!');

💬 Messaging

Text Messages

$client->messages()->sendText('+123', 'Hello!');

Image Messages

$client->messages()->sendImage(
    '+123',
    'https://example.com/image.jpg',
    caption: 'Check this out!'
);

Media Messages

$client->messages()->sendMedia('+123', 'https://example.com/video.mp4');

Location Messages

$client->messages()->sendLocation(
    '+123',
    40.7128,
    -74.0060,
    name: 'NYC',
    address: 'New York'
);

File Messages

$client->messages()->sendFile(
    '+123',
    fileUrl: 'https://example.com/doc.pdf',
    filename: 'Invoice.pdf'
);

Contact (vCard)

$client->messages()->sendContact(
    '+123',
    contactsId: 'whatsapp_contact_id'
);

Reply Messages

$client->messages()->sendReply(
    '+123',
    'This is a reply',
    replyToMessageId: '01ABC...'
);

Text + Media Combination

$client->messages()->sendBoth(
    '+123',
    'Hello!',
    mediaUrl: 'https://example.com/pic.jpg',
    caption: 'Nice image'
);

⏰ Timezone-Aware Scheduling

ISO8601 Example

ScheduleOptions::fromIso8601('2025-11-15T08:02:00+03:00');

IANA Timezone

ScheduleOptions::at(
    new DateTimeImmutable('2025-11-15 08:00'),
    'Africa/Cairo'
);

📡 Message Status

$client->messages()->getStatus('01ABC...');

🧩 Webhooks

Create Webhook

$client->webhooks()->create(
    'delivery',
    'https://yourdomain.com/webhooks',
    secret: 'secret'
);

Verify Signature

Webhooks::verifySignature($payload, $signature, $secret);

❗ Error Handling

Built-in typed exceptions:

• AuthenticationException
• ValidationException
• HttpException
• GradiWappException

Example:

try {
    $client->messages()->sendText('+123', 'Hi');
} catch (ValidationException $e) {
    print_r($e->getErrors());
}

🔧 Advanced Usage

Multiple Sessions

$client->messages()->sendText(
    '+123',
    'Hi',
    sessionId: 'session_01'
);

Priority

$client->messages()->sendText('+123', 'Hi', priority: 'high');

📦 Response Format

Your backend returns:

{
  "success": true,
  "message": "Message queued successfully",
  "data": {
    "id": "01ARZ3N...",
    "status": "queued"
  }
}

🧭 Versioning & SDK Stability

This SDK follows Semantic Versioning (SemVer):

• MAJOR → Breaking changes
• MINOR → New features
• PATCH → Bug fixes

🤝 Contributing

Pull Requests are welcome!

📄 License

MIT License.