Download the PHP package ashararsi/laravel-whatsapp-cloud without Composer

Laravel WhatsApp Cloud

v1.0.0 — First public stable release.

A production-ready WhatsApp conversation platform for Laravel. Send messages via Meta Cloud API or Twilio WhatsApp using one unified fluent API, with contacts, conversations, campaigns, analytics, AI automation, and a full admin panel.

Features

• Meta Cloud API — Direct Graph API integration with retry, rate-limit handling, and media upload
• Twilio Provider — Unified API for Twilio WhatsApp messaging
• Multi Account Support — Multiple Meta/Twilio accounts with encrypted credentials
• Conversations — Inbox with message timeline and reply form
• Contacts — CRM with notes and tags
• Campaigns — Broadcast messaging with queue support
• Analytics — Dashboard with charts, delivery rate, and cost estimation
• AI Auto Reply — OpenAI-powered automatic responses
• Workflow Engine — Configurable multi-step AI workflows
• Template Sync — Admin UI and CLI to sync Meta templates
• Scheduled Messages — Deferred send via whatsapp:scheduled:send
• Admin Panel — Bootstrap UI for accounts, settings, templates, and system monitoring
• Database Settings — Runtime configuration without .env changes

Requirements

• PHP 8.3+
• Laravel 13.x

Installation

During install you choose single app or multi-tenant mode:

• Single app (default) — no whatsapp_tenants table, no tenant_id columns
• Multi-tenant — creates tenant tables and tenant_id columns on migrate

Non-interactive install:

Set WHATSAPP_TENANT_ENABLED in .env before migrate if you skip the installer prompt.

Configure runtime settings at /admin/whatsapp/settings after migration.

Provider Comparison

Quick Start

Supported Methods

Meta Cloud API Setup

1. Create a Meta App

1. Go to Meta for Developers
2. Create an app with WhatsApp product enabled
3. Add a phone number and generate a permanent access token
4. Copy Phone Number ID and Access Token

2. Create Account (code or admin)

3. Configure Webhook

In Admin → Settings (/admin/whatsapp/settings):

• Set Global App Secret (or store per-account app_secret on whatsapp_accounts — recommended)
• Enable Require Meta Webhook Signature for production

Twilio WhatsApp Setup

1. Enable WhatsApp in Twilio

1. Sign up at Twilio
2. Enable WhatsApp Sandbox or register a WhatsApp sender
3. Copy Account SID, Auth Token, and WhatsApp number

2. Create Twilio Account

3. Configure Twilio Webhooks

Point your Twilio WhatsApp sender to:

Enable Require Twilio Webhook Signature in Admin → Settings (enabled by default).

Twilio signs requests with X-Twilio-Signature using the account Auth Token stored on each WhatsAppAccount.

4. Send via Twilio provider

Provider Architecture

Extend with custom providers

Implement WhatsAppProviderInterface and register in config/whatsapp.php:

Conversation Platform

The package automatically tracks conversations:

• Incoming: stored automatically from Meta and Twilio webhooks
• Outgoing: stored when WhatsApp::send() succeeds
• Message log: all directions stored in whatsapp_messages (direction: incoming / outgoing)
• Reply from inbox: conversation detail page includes a reply form (sync or queued)

Disable with WHATSAPP_CONVERSATIONS_ENABLED=false.

Admin URLs

CRM: Notes & Tags

On the contact detail page you can:

• Add and view internal notes
• Create tags and assign them to contacts
• Remove tags from a contact

Tags are scoped per WhatsApp account.

Template Manager

Manage Meta WhatsApp message templates from the admin panel or CLI.

Categories: UTILITY, AUTHENTICATION, MARKETING

Statuses: APPROVED, PENDING, REJECTED

Sync templates

Requires a Meta account with waba_id (or phone_number_id as fallback) and a valid access token with whatsapp_business_management permission.

Send a template (simple variables)

Maps body placeholders {{1}}, {{2}}, … to an ordered variable list:

Send a template (full Meta components)

For header/button parameters, use the low-level API:

Database table: whatsapp_templates

The dashboard shows approved, pending, and rejected template counts.

Broadcast Campaigns

Create campaigns from /admin/whatsapp/campaigns or run pending drafts:

Enable Queue Campaign Sends in Admin → Settings to queue bulk sends.

AI & Automation (optional)

Set WHATSAPP_OPENAI_API_KEY in .env (secret — not stored in DB). Enable features in Admin → Settings:

• AI Auto Reply
• Audio Transcription
• Keyword Auto Reply
• Process Incoming Messages

• Download Incoming Media

• Auto-reply rules — keyword, first-message, and AI modes (whatsapp_auto_replies table)
• Workflows — whatsapp_ai_workflows with step fallback when OpenAI is unavailable
• Media download — Meta incoming attachments saved to disk (WHATSAPP_MEDIA_DISK in .env)
• Audio transcription — Whisper via OpenAI when enabled

Multi-Tenant Mode (Optional)

Choose multi-tenant during php artisan whatsapp:install, or set manually:

Single-app mode (default) skips whatsapp_tenants and all tenant_id columns entirely.

Implement TenantResolverInterface in your app:

Register the resolver in a service provider:

When tenant mode is enabled:

• Admin routes automatically run ResolveWhatsAppTenant middleware (disable with WHATSAPP_TENANT_ADMIN_MIDDLEWARE=false)
• Queries are scoped to the active tenant once TenantContext is set
• Webhooks and CLI commands still work globally (no tenant scope until you set one)
• tenant_id is auto-filled on create from the active tenant or related account

Run code for a specific tenant without middleware:

Scope note: Filament admin resources are not included. The package ships a Bootstrap admin panel; publish views to integrate with your own layout.

Admin Panel

/admin/whatsapp/accounts — create accounts with provider-specific fields:

• Meta: Phone Number ID, Access Token, App Secret, Webhook Verify Token
• Twilio: Account SID, Auth Token, WhatsApp Number

Customizing Admin Views & Theme

All admin UI lives in the package. Your Laravel app does not need to create CRUD views manually.

Where views live

Package views are loaded with the whatsapp:: namespace:

Laravel uses published views first. If a file exists in resources/views/vendor/whatsapp/, it overrides the package copy.

Publish views to your project

Published structure:

Re-publish after package updates (overwrites your copies):

Back up customized files before using --force.

Option 1 — Enhance the package master layout

Edit the published master layout:

This file controls:

• Sidebar / top navigation
• Active menu state
• Flash messages (success, error)
• Page wrapper around @yield('content')
• @yield('title') for the page heading

Child pages only fill the content section. Example account list:

Add your CSS, JS, fonts, or branding inside admin.blade.php (or link your existing admin assets).

Option 2 — Use your app's main admin theme (recommended)

If your project already has a layout (Filament, AdminLTE, custom layouts.app, etc.), point package pages to your layout instead of the package default.

Step 1. Publish views:

Step 2. Change @extends in published admin pages. Example for accounts index:

Step 3. Move package navigation into your sidebar. Reuse the same routes:

Step 4. Optionally replace only the master layout by making your layout extend the package structure, or delete sidebar from layouts/admin.blade.php and @include your global header/sidebar.

Option 3 — Override a single page

You do not need to publish everything. Publish once, then edit only the pages you care about:

Unpublished pages still load from the package automatically.

View resolution order

After customization

Tips

• Keep @section('content') and @section('title') when overriding child views.
• Do not rename route names (whatsapp.admin.*); controllers depend on them.
• For provider fields (Meta / Twilio), customize admin/accounts/_form.blade.php.
• For conversation bubbles styling, see CSS classes timeline-incoming and timeline-outgoing in the master layout.

Incoming Messages

Every webhook delivery is logged to whatsapp_messages when Log Outgoing Messages is enabled in Admin → Settings:

Duplicate webhook deliveries are ignored via unique whatsapp_message_id constraints.

Doctor Command

Run a full health check before production:

Checks database tables, queues, routes, webhook secrets, Meta/Twilio credentials, storage, and cache. Output levels: PASS, WARNING, ERROR.

Runtime Settings (Database)

Operational settings are stored in the whatsapp_settings table and managed from the admin panel. No .env variables are required for these — changes apply at runtime without redeploying.

Admin URL: /admin/whatsapp/settings

After php artisan migrate, defaults are seeded automatically.

Environment Variables (infrastructure only)

Use .env only for host-app infrastructure and secrets — not runtime feature toggles:

Notifications

Webhooks

Meta

Per-account app_secret on whatsapp_accounts is used for X-Hub-Signature-256 verification. Falls back to the Global App Secret from Admin → Settings when the account secret is empty.

Twilio

Supports inbound text, media, and location payloads plus status callbacks: queued, sent, delivered, failed, undelivered.

Testing & Quality

Security Recommendations

1. Enable Require Meta Webhook Signature in Admin → Settings for production.
2. Store a unique app_secret per Meta account when running multiple apps.
3. Keep Require Twilio Webhook Signature enabled (default) for Twilio webhooks.
4. Never commit access tokens or auth tokens — they are encrypted on whatsapp_accounts.
5. Keep Require Admin Authorization enabled and protect admin routes with your gate.
6. Run php artisan whatsapp:doctor after deploy to verify configuration.

See UPGRADE.md.

Screenshots

Placeholder — add screenshots of the admin dashboard, conversation inbox, and account management UI here before release.

License

This project is licensed under the MIT License.

Copyright (c) 2026 Ashar Arsi