PHPackages                             bassem-shoukry/laravel-chatwoot - 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. bassem-shoukry/laravel-chatwoot

ActiveLibrary[API Development](/categories/api)

bassem-shoukry/laravel-chatwoot
===============================

Typed Chatwoot API client and webhook receiver for Laravel.

v1.0.0(1mo ago)10MITPHPPHP ^8.3CI passing

Since May 6Pushed 1mo agoCompare

[ Source](https://github.com/bassem-shoukry/laravel-chatwoot)[ Packagist](https://packagist.org/packages/bassem-shoukry/laravel-chatwoot)[ Docs](https://github.com/bassem-shoukry/laravel-chatwoot)[ RSS](/packages/bassem-shoukry-laravel-chatwoot/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (16)Versions (2)Used By (0)

Laravel Chatwoot
================

[](#laravel-chatwoot)

[![Latest Version on Packagist](https://camo.githubusercontent.com/6ded834e817f700035cff4b3945ce7f2e4c113b6c9ad187a823cb046ad1d343f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f62617373656d2d73686f756b72792f6c61726176656c2d63686174776f6f742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/bassem-shoukry/laravel-chatwoot)[![Total Downloads](https://camo.githubusercontent.com/5f7084cd294a79fd60746f2d67059b3cf938667e0d21b9043fb1268283ca35a9/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f62617373656d2d73686f756b72792f6c61726176656c2d63686174776f6f742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/bassem-shoukry/laravel-chatwoot)[![License](https://camo.githubusercontent.com/699e09aa4115390678d56d9f364faa5e50e187b66c1449d94184ba17b1e34c4b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f62617373656d2d73686f756b72792f6c61726176656c2d63686174776f6f742e7376673f7374796c653d666c61742d737175617265)](LICENSE.md)

Typed Chatwoot API client and webhook receiver for Laravel.

- Strongly-typed DTOs (`Conversation`, `Message`, `Contact`, `Inbox`, …)
- Resource gateways (`Chatwoot::messages()`, `Chatwoot::conversations()`, …)
- HMAC-verified webhook controller with typed events
- Multi-account, immutable account switching
- SSRF guard, scrubbed request/response logging, automatic retry on `429`/`5xx`
- Built-in `ChatwootFake` for tests
- PHP 8.3 / 8.4 · Laravel 11 / 12 / 13

Install
-------

[](#install)

```
composer require bassem-shoukry/laravel-chatwoot
php artisan vendor:publish --tag=laravel-chatwoot-config
```

Set the env keys:

```
CHATWOOT_URL=https://app.chatwoot.com
CHATWOOT_API_TOKEN=your-user-api-access-token
CHATWOOT_ACCOUNT_ID=1
CHATWOOT_VERIFY_SIGNATURE=true
CHATWOOT_HMAC_SECRET=whsec_your_webhook_signing_secret
```

The `CHATWOOT_API_TOKEN` is a Chatwoot **User Access Token** (Profile → Access Token). Tokens stored in config are decrypted with the application key on read, so you may store them encrypted using `Crypt::encryptString` for defence in depth.

Send messages
-------------

[](#send-messages)

```
use BassamShoukry\LaravelChatwoot\Facades\Chatwoot;

// Plain text
Chatwoot::messages()->send($conversationId, 'Hello there');

// Interactive buttons (mapped to Chatwoot's input_select content type)
Chatwoot::messages()->sendInteractiveButtons($conversationId, 'Pick one', [
    ['title' => 'Yes', 'value' => 'yes'],
    ['title' => 'No',  'value' => 'no'],
]);

// WhatsApp template
Chatwoot::messages()->sendTemplate(
    conversationId: $conversationId,
    name: 'order_update',
    language: 'en',
    components: [/* WhatsApp template components */],
);

// Raw passthrough — escape hatch for advanced WhatsApp payloads (Flows etc.)
Chatwoot::messages()->sendRaw($conversationId, [
    'flow_action' => 'navigate',
    'flow_id'     => 'abc123',
]);
```

Find or create a contact, then a conversation
---------------------------------------------

[](#find-or-create-a-contact-then-a-conversation)

Useful when reacting to an inbound message on a channel keyed by a `source_id`(e.g. WhatsApp's wa\_id):

```
$contact = Chatwoot::contacts()->findOrCreate(
    inboxId: $inboxId,
    sourceId: $waId,
    name: $name,
    phoneNumber: '+'.$waId,
);

$conv = Chatwoot::conversations()->firstOrCreateForContact(
    contactId: $contact->id,
    inboxId: $inboxId,
    sourceId: $waId,
);

Chatwoot::messages()->send($conv->id, 'Welcome 👋');
```

Multi-account
-------------

[](#multi-account)

```
CHATWOOT_ACCOUNT=primary
```

```
'accounts' => [
    'primary' => [
        'url'        => env('CHATWOOT_URL'),
        'token'      => env('CHATWOOT_API_TOKEN'),
        'account_id' => env('CHATWOOT_ACCOUNT_ID'),
    ],
    'eu' => [
        'url'        => env('CHATWOOT_EU_URL'),
        'token'      => env('CHATWOOT_EU_API_TOKEN'),
        'account_id' => env('CHATWOOT_EU_ACCOUNT_ID'),
    ],
],
```

```
Chatwoot::account('eu')->messages()->send($id, 'Hallo');
```

`account()` returns an immutable, scoped manager — it never mutates the shared singleton.

Receive webhooks
----------------

[](#receive-webhooks)

Routes are **opt-in**. Register them where you control the URL prefix and middleware:

```
// routes/api.php
use BassamShoukry\LaravelChatwoot\LaravelChatwootServiceProvider;

LaravelChatwootServiceProvider::routes(
    prefix: 'api/webhooks/chatwoot',
    middleware: ['api'],
);
```

This exposes:

- `POST /api/webhooks/chatwoot` — uses the default account
- `POST /api/webhooks/chatwoot/{account}` — multi-account fan-in

Every payload is verified against `chatwoot.accounts.{account}.webhook.secret`(or the global `chatwoot.webhooks.secret`) using HMAC-SHA256 against the raw body. Verification is **on by default**; set `verify_signature` to `false`explicitly only when you must.

Listen for events:

```
use BassamShoukry\LaravelChatwoot\Events\MessageCreated;

Event::listen(MessageCreated::class, function (MessageCreated $event): void {
    // $event->message is a typed Message DTO
    // $event->accountName is the account that received the webhook
});
```

Available events: `WebhookReceived`, `MessageCreated`, `MessageUpdated`, `ConversationCreated`, `ConversationUpdated`, `ConversationStatusChanged`, `ContactCreated`, `ContactUpdated`.

Tracking (opt-in)
-----------------

[](#tracking-opt-in)

Set `CHATWOOT_TRACKING_ENABLED=true` to enable the package migrations:

- `chatwoot_contacts`
- `chatwoot_conversations`
- `chatwoot_messages`
- `chatwoot_webhook_events`

Then publish + run:

```
php artisan vendor:publish --tag=laravel-chatwoot-migrations
php artisan migrate
```

Persistence itself is **not automatic** — write your own listeners using the provided Eloquent models so you control sync semantics.

Testing
-------

[](#testing)

```
use BassamShoukry\LaravelChatwoot\ChatwootManager;
use BassamShoukry\LaravelChatwoot\Testing\ChatwootFake;

$fake = ChatwootFake::swap();
$fake->stub('POST', 'api/v1/accounts/1/conversations/9/messages', [
    'id' => 7, 'content' => 'hello',
]);

app(ChatwootManager::class)->messages()->send(9, 'hello');

expect($fake->calls)->toHaveCount(1);
```

Or just `Http::fake()` against the Chatwoot endpoints — the package's `ApiClient` is a regular Laravel HTTP client.

Security notes
--------------

[](#security-notes)

- Tokens read from config are decrypted automatically when encrypted with `Crypt::encryptString`.
- `chatwoot.allow_local_urls` is `false` by default. Loopback hosts (localhost, 127.0.0.1, ::1, 0.0.0.0) and non-http(s) schemes are rejected during account resolution to limit SSRF.
- Outgoing logs scrub `Authorization`, `api_access_token`, `hmac_token`, `Cookie` and known sensitive payload keys.
- Webhook signatures are checked with `hash_equals`. Default is **strict**: no signature → 401.

Support
-------

[](#support)

Bug reports and feature requests: [GitHub Issues](https://github.com/bassem-shoukry/laravel-chatwoot/issues). See [CHANGELOG.md](CHANGELOG.md) for release notes.

License
-------

[](#license)

MIT — see [LICENSE.md](LICENSE.md).

###  Health Score

39

—

LowBetter than 84% of packages

Maintenance93

Actively maintained with recent releases

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity48

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

Unknown

Total

1

Last Release

34d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/78b45e64aac2f3ae334f593a79868c28c95c943d4b143ee10165bc718fa6d447?d=identicon)[basem.shoukry](/maintainers/basem.shoukry)

---

Top Contributors

[![bassem-shoukry](https://avatars.githubusercontent.com/u/23497938?v=4)](https://github.com/bassem-shoukry "bassem-shoukry (23 commits)")

---

Tags

laravelmessagingwebhookswhatsappchatwoot

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/bassem-shoukry-laravel-chatwoot/health.svg)

```
[![Health](https://phpackages.com/badges/bassem-shoukry-laravel-chatwoot/health.svg)](https://phpackages.com/packages/bassem-shoukry-laravel-chatwoot)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3325.1M337](/packages/psalm-plugin-laravel)[larastan/larastan

Larastan - Discover bugs in your code without running it. A phpstan/phpstan extension for Laravel

6.4k51.0M7.4k](/packages/larastan-larastan)[defstudio/telegraph

A laravel facade to interact with Telegram Bots

815320.5k3](/packages/defstudio-telegraph)[simplestats-io/laravel-client

Analytics for Laravel. Track visitors, registrations, and payments. Discover which channels actually drive revenue, not just traffic. Server-side, GDPR compliant, ad-blocker proof.

5019.3k](/packages/simplestats-io-laravel-client)[spatie/laravel-health

Monitor the health of a Laravel application

87311.3M149](/packages/spatie-laravel-health)[api-platform/laravel

API Platform support for Laravel

59156.3k10](/packages/api-platform-laravel)

PHPackages © 2026

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