PHPackages                             afro-technology/waha-laravel-sdk - 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. afro-technology/waha-laravel-sdk

ActiveLibrary[API Development](/categories/api)

afro-technology/waha-laravel-sdk
================================

Laravel SDK for WAHA with multi-host, optional DB pinning, and OpenAPI generated client

v0.2.1(2mo ago)36[1 PRs](https://github.com/Afro-Technology/waha-laravel-sdk/pulls)MITPHPPHP ^8.1 || ^8.2 || ^8.3 || ^8.4CI passing

Since Feb 25Pushed 1mo agoCompare

[ Source](https://github.com/Afro-Technology/waha-laravel-sdk)[ Packagist](https://packagist.org/packages/afro-technology/waha-laravel-sdk)[ RSS](/packages/afro-technology-waha-laravel-sdk/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (4)Dependencies (7)Versions (6)Used By (0)

[![Latest Version on Packagist](https://camo.githubusercontent.com/1b4c9766cf1b474c3ae20cfb347f9fcfbedee4038a42747ab74ad7769677196b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6166726f2d746563686e6f6c6f67792f776168612d6c61726176656c2d73646b2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/afro-technology/waha-laravel-sdk)[![Total Downloads](https://camo.githubusercontent.com/371826e40bc2dbddb0118f3d8def57977e16350e681479fc9e0881620fdcfe9a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6166726f2d746563686e6f6c6f67792f776168612d6c61726176656c2d73646b2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/afro-technology/waha-laravel-sdk)[![License](https://camo.githubusercontent.com/76d103a771ac9e536329b9a7e765fa2f7a7c1f7562566b9c5abe24ae716d806b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6166726f2d746563686e6f6c6f67792f776168612d6c61726176656c2d73646b2e7376673f7374796c653d666c61742d737175617265)](LICENSE)[![OpenAPI Sync](https://github.com/Afro-Technology/waha-laravel-sdk/actions/workflows/openapi-sync.yml/badge.svg)](https://github.com/Afro-Technology/waha-laravel-sdk/actions/workflows/openapi-sync.yml)

WAHA Laravel SDK
================

[](#waha-laravel-sdk)

Laravel-oriented SDK for **WAHA** (WhatsApp HTTP API / Web WhatsApp gateway).
It provides:

- **Multi-host** support (primary/secondary, etc.)
- Optional **session → host pinning** (Redis/DB/composite)
- **OpenAPI-driven** routing (reads WAHA OpenAPI spec and calls the generated client)
- **Convenience DX layer** (Facade + tag proxies + top-level aliases)
- **IDE autocomplete generation** (PHPDoc for Facade/proxies)
- **Debug tools**: `Waha::lastHttp()` / `Waha::lastHttpCurl()` + scoped debug

> Repository is meant to be installed into Laravel apps via Composer.

---

Contents
--------

[](#contents)

- [Installation](#installation)
- [Configuration](#configuration)
- [Quick Start](#quick-start)
- [Usage](#usage)
    - [Host selection](#host-selection)
    - [Tag proxies](#tag-proxies)
    - [Top-level convenience methods](#top-level-convenience-methods)
    - [Response formats](#response-formats)
    - [Debug & last HTTP](#debug--last-http)
- [Webhooks](#webhooks)
    - [Configuring webhook\_secret](#configuring-webhook_secret)
    - [Verifying signatures (WebhookVerifier)](#verifying-signatures-webhookverifier)
    - [Example route/controller](#example-routecontroller)
- [OpenAPI workflow](#openapi-workflow)
- [IDE Helper](#ide-helper)
- [Testing & CI](#testing--ci)
- [Versioning](#versioning)
- [License](#license)

---

Installation
------------

[](#installation)

### Requirements

[](#requirements)

- PHP **8.1+**
- Laravel **10 / 11 / 12**
- Guzzle **7.5+**

### Composer install

[](#composer-install)

```
composer require afro-technology/waha-laravel-sdk
```

Laravel package discovery is enabled by default.

### Publish config (recommended)

[](#publish-config-recommended)

```
php artisan vendor:publish --provider="Vendor\Waha\WahaServiceProvider" --tag="waha-config"
```

This creates `config/waha.php`.

---

Configuration
-------------

[](#configuration)

Main config: `config/waha.php`

### Minimal `.env`

[](#minimal-env)

```
WAHA_DEFAULT_HOST=primary

WAHA_PRIMARY_URL=https://waha.example.com
WAHA_PRIMARY_ADMIN_KEY=YOUR_ADMIN_API_KEY
WAHA_API_KEY_HEADER=X-Api-Key

WAHA_PRIMARY_DEFAULT_SESSION=default
```

### Hosts

[](#hosts)

Configure one or more hosts under `waha.hosts`:

```
'hosts' => [
  'primary' => [
    'base_url' => env('WAHA_PRIMARY_URL', 'http://localhost:3000'),
    'api_key_header' => env('WAHA_API_KEY_HEADER', 'X-Api-Key'),
    'admin_api_key' => env('WAHA_PRIMARY_ADMIN_KEY'),
    'default_session' => env('WAHA_PRIMARY_DEFAULT_SESSION', 'default'),

    // Used for webhook signature verification (HMAC)
    'webhook_secret' => env('WAHA_PRIMARY_WEBHOOK_SECRET'),

    // admin_fallback | strict_session_key
    'mode' => env('WAHA_PRIMARY_MODE', 'admin_fallback'),

    // Optional: per-session keys (newer WAHA versions)
    'session_keys' => [
      // 'default' => env('WAHA_PRIMARY_DEFAULT_SESSION_KEY'),
    ],
  ],
],
```

### Host authentication: `admin_api_key` vs `session_keys`

[](#host-authentication-admin_api_key-vs-session_keys)

WAHA can be protected either with a **single admin key** (simplest) or with **per-session keys** (safer when you want to scope access).

- **`admin_api_key`**: one key for the whole WAHA instance. The SDK sends it as `X-Api-Key` (or `api_key_header`).
    Use this for typical server-to-server setups where your application fully trusts itself.
- **`session_keys`**: a map of `session => key`. Useful when you run multiple WhatsApp sessions and want to isolate them (e.g., different tenants / orgs) so one leaked key cannot control other sessions.
- **`mode`** controls how the SDK chooses a key:

    - **`admin_fallback`** (default): if a session key exists for the resolved session, use it; otherwise fall back to `admin_api_key`.
    - **`strict_session_key`**: require a session key for the session; if missing, the request fails instead of silently using the admin key.

⚠️ Note: the OpenAPI-generated client currently authenticates with the host’s `admin_api_key` (because the generator config supports one API key).
Per-session keys are used by the internal `WahaHttpClient` / `ApiKeyProvider` layer (useful for custom calls and for future extensions).

### Debug

[](#debug)

```
WAHA_DEBUG=false
WAHA_DEBUG_MAX_BODY_KB=64
WAHA_DEBUG_LOG_CHANNEL=stack
```

- Last call capture (`lastHttp/lastHttpCurl`) is stored regardless of logging.
- When `WAHA_DEBUG=true`, requests/responses are also logged (masked + truncated).

### Registry, routing, and pin store (multi-host / “session → host” mapping)

[](#registry-routing-and-pin-store-multi-host--session--host-mapping)

This SDK can work in a simple **single-host** setup (no routing), but it also supports **multi-host** deployments where a *session* must consistently “stick” to the same WAHA host.

These three config blocks control that behavior:

#### `registry`

[](#registry)

Where host definitions come from.

- `registry.driver=config` (default): hosts are read from `config/waha.php` (`waha.hosts.*`).
- `registry.driver=db`: hosts are stored in package tables (publish + run migrations). Use this if you want to manage hosts from an admin UI or the database.

#### `routing`

[](#routing)

How the SDK chooses a host when you call methods *without* explicitly selecting one.

- `routing.driver=none` (default): no automatic routing. You call `Waha::host('primary')...` or rely on `waha.default_host`.
- `routing.driver=pin`: resolves **session → host** using the pin store. This is the recommended mode if you run **multiple WAHA nodes** and want stable routing.

#### `pin_store`

[](#pin_store)

Where **session → host** mappings are stored (used by `routing.driver=pin`).

- `pin_store.driver=auto` (default): prefers `composite` when possible, else falls back to `redis`, else `db`.
- `pin_store.driver=composite`: write-through **redis + db**, read redis-first then db (best of both worlds).
- `pin_store.driver=redis`: fastest, but you may lose mappings if redis is cleared (unless you persist it).
- `pin_store.driver=db`: durable, but slower.

Other knobs:

- `pin_store.ttl_seconds`: optional TTL for mappings (`0` = no TTL).
- `pin_store.redis_connection`: which Laravel redis connection to use.

> Typical setup for production multi-host:
>
> - `routing.driver=pin`
> - `pin_store.driver=composite` (or `auto`)
> - redis enabled + migrations applied

### Response format

[](#response-format)

```
WAHA_RESPONSE_FORMAT=model   # model|array|json
```

- `model`: generated OpenAPI model objects (default)
- `array`: normalized PHP arrays
- `json`: normalized array then `json_encode`

---

Quick Start
-----------

[](#quick-start)

```
use Vendor\Waha\Facades\Waha;

$msg = Waha::sendText(
    chatId: '905xxxxxxxxx@c.us',
    text: 'Hello from WAHA!'
);
```

Equivalent via tag proxy (tag names come from the OpenAPI spec):

```
$msg = Waha::chatting()->sendText(
    chatId: '905xxxxxxxxx@c.us',
    text: 'Hello via tag proxy!'
);
```

---

Usage
-----

[](#usage)

### Host selection

[](#host-selection)

```
Waha::host('primary')->sendText(chatId: '905...@c.us', text: 'via primary');

Waha::host('secondary')->sendText(chatId: '905...@c.us', text: 'via secondary');
```

If you don’t call `host()`, `waha.default_host` is used.

### Tag proxies

[](#tag-proxies)

Tags are exposed as methods (normalized to lowerCamel). Example:

```
// "chatting" tag
$msg = Waha::chatting()->sendText(chatId: '905...@c.us', text: 'hi');

// "sessions" tag (example)
$status = Waha::sessions()->list();
```

### Top-level convenience methods

[](#top-level-convenience-methods)

Some operations are also exposed at the top level (only when their aliases are unique globally):

```
$msg = Waha::sendText(chatId: '905...@c.us', text: 'Convenience');
```

If an alias is not available at the top level (collision), use the tag:

```
$msg = Waha::chatting()->sendText(...);
```

### Response formats

[](#response-formats)

Global via `.env` (`WAHA_RESPONSE_FORMAT`) or per chain:

```
$arr = Waha::asArray()->sendText(chatId:'905...@c.us', text:'array result');

$json = Waha::asJson()->sendText(chatId:'905...@c.us', text:'json result');

$model = Waha::asModel()->sendText(chatId:'905...@c.us', text:'model result');
```

Works with tag proxies too:

```
$arr = Waha::chatting()->asArray()->sendText(...);
```

### Debug & last HTTP

[](#debug--last-http)

Read the last captured request/response:

```
Waha::sendText(chatId:'905...@c.us', text:'Hello');

$last = Waha::lastHttp();      // array with request/response/error
$curl = Waha::lastHttpCurl();  // curl string (if available)
```

Enable debug only for the next call:

```
Waha::debug()->sendText(chatId:'905...@c.us', text:'debug for this call only');
```

Scoped debug:

```
Waha::withDebug(function () {
    Waha::sendText(chatId:'905...@c.us', text:'debug scope 1');
    Waha::chatting()->sendText(chatId:'905...@c.us', text:'debug scope 2');
});
```

---

Webhooks
--------

[](#webhooks)

WAHA can deliver inbound events (messages, status updates, etc.) to your Laravel app via HTTP webhooks.

### Configuring webhook\_secret

[](#configuring-webhook_secret)

This SDK expects a shared secret per host under:

```
config('waha.hosts..webhook_secret')
```

Example `.env`:

```
WAHA_PRIMARY_WEBHOOK_SECRET=super-long-random-secret
```

**You must configure the same secret in WAHA** (how/where depends on your WAHA deployment).

### Verifying signatures (WebhookVerifier)

[](#verifying-signatures-webhookverifier)

The package ships with:

- `Vendor\Waha\Security\WebhookVerifier`

It verifies an **HMAC signature** of the raw request body using the host’s `webhook_secret`.

Important details:

- The verifier accepts signature formats:
    - `sha256=` (common)
    - `` (raw)
- Header name is WAHA/deployment specific. Many setups use something like `X-Waha-Signature`.

### Example route/controller

[](#example-routecontroller)

**routes/api.php**

```
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;
use Vendor\Waha\Security\WebhookVerifier;

Route::post('/webhooks/waha/{hostKey}', function (Request $request, string $hostKey, WebhookVerifier $verifier) {
    $raw = $request->getContent();

    // Adjust header name to match your WAHA webhook configuration
    $signature = $request->header('X-Waha-Signature');

    if (!$verifier->verify($hostKey, $raw, $signature)) {
        abort(401, 'Invalid webhook signature');
    }

    $payload = $request->json()->all(); // or $request->all()

    // WAHA payload structure depends on your deployment.
    // Inspect once with dd($payload), then branch by event type.
    $event = $payload['event'] ?? null;

    if ($event === 'message') {
        $message = $payload['payload'] ?? $payload;
        // persist message, download media, trigger workflows, etc.
    }

    return response()->json(['ok' => true]);
});
```

**Security note:** always verify signature *before* processing, and treat payload as untrusted input.

---

OpenAPI workflow
----------------

[](#openapi-workflow)

This SDK uses WAHA’s OpenAPI spec to route calls and generate the underlying client.

Common commands (provided by this package):

- Fetch spec:

    ```
    php artisan waha:openapi:fetch
    ```
- Generate OpenAPI client (uses configured generator driver):

    ```
    php artisan waha:openapi:generate
    ```
- Update (fetch + generate + ide helper, depending on your setup):

    ```
    php artisan waha:openapi:update
    ```

Configuration lives under `config/waha.php` → `openapi`.

---

IDE Helper
----------

[](#ide-helper)

This package can generate PHPDoc for:

- Facade (`Waha`)
- Proxies (host chain, tag proxies, top-level operations)

Run:

```
php artisan waha:openapi:ide-helper
```

Then re-index your IDE if autocompletion does not update.

---

Testing & CI
----------------

[](#testing--ci)

Local tests:

```
composer test
```

Recommended additions for public repos:

- Pint (formatting)
- PHPStan (static analysis)
- GitHub Actions workflow running:
    - `composer install`
    - `composer test`
    - `vendor/bin/pint --test`
    - `vendor/bin/phpstan analyse`

(Exact setup depends on your repo preferences.)

---

Versioning
----------

[](#versioning)

Use **SemVer**:

- `MAJOR`: breaking API changes
- `MINOR`: backward-compatible features
- `PATCH`: backward-compatible fixes

Tags are important for Packagist and for stable dependency resolution.

---

License
-------

[](#license)

MIT

###  Health Score

39

—

LowBetter than 86% of packages

Maintenance88

Actively maintained with recent releases

Popularity8

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity45

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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 ~0 days

Total

4

Last Release

77d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/75bf710269b95e1b52a937ba4b806091f6e083d0542d1ba872878fabe02cfd9b?d=identicon)[akozdem](/maintainers/akozdem)

---

Top Contributors

[![akozdem](https://avatars.githubusercontent.com/u/59332767?v=4)](https://github.com/akozdem "akozdem (27 commits)")

---

Tags

laravelsdkopenapiwhatsappwaha

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/afro-technology-waha-laravel-sdk/health.svg)

```
[![Health](https://phpackages.com/badges/afro-technology-waha-laravel-sdk/health.svg)](https://phpackages.com/packages/afro-technology-waha-laravel-sdk)
```

###  Alternatives

[missael-anda/laravel-whatsapp

A Whatsapp Business Cloud API wrapper for Laravel.

677.5k](/packages/missael-anda-laravel-whatsapp)[scriptdevelop/whatsapp-manager

Paquete para manejo de WhatsApp Business API en Laravel

762.6k](/packages/scriptdevelop-whatsapp-manager)

PHPackages © 2026

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