README

Direct Meta WhatsApp Cloud API integration for Laravel.

Features

Webhook verification endpoint
Inbound webhook handler
Outbound text message endpoint
Outbound template message endpoint
HMAC validation with X-Hub-Signature-256
Event dispatching for inbound webhook payloads
Publishable config file

Package Structure

src/WhatsAppServiceProvider.php: package bootstrapping
src/Services/MetaWhatsAppClient.php: direct Meta Graph API client
src/Http/Controllers/WhatsAppWebhookController.php: webhook verification and inbound handling
src/Http/Controllers/WhatsAppMessageController.php: outbound message endpoints
src/Events/WhatsAppWebhookReceived.php: event fired for inbound webhook payloads
config/whatsapp.php: package configuration
routes/api.php: package routes

Configuration

Environment variables used by the package:

WHATSAPP_BASE_URL=https://graph.facebook.com
WHATSAPP_GRAPH_VERSION=v24.0
WHATSAPP_ACCESS_TOKEN=
WHATSAPP_PHONE_NUMBER_ID=
WHATSAPP_BUSINESS_ACCOUNT_ID=
WHATSAPP_APP_SECRET=
WHATSAPP_WEBHOOK_VERIFY_TOKEN=
WHATSAPP_ROUTE_PREFIX=whatsapp

You can publish the config into the host Laravel app with:

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

Published config path:

config/whatsapp.php

Routes

By default the package exposes these routes:

GET /api/whatsapp/webhook
POST /api/whatsapp/webhook
POST /api/whatsapp/messages/text
POST /api/whatsapp/messages/template

The whatsapp segment is configurable through WHATSAPP_ROUTE_PREFIX.

Usage

Verify webhook

Meta will call:

GET /api/whatsapp/webhook?hub.mode=subscribe&hub.verify_token=...&hub.challenge=...

The package validates the verify token and returns the challenge string.

Receive inbound webhooks

Meta will send webhook payloads to:

POST /api/whatsapp/webhook

If WHATSAPP_APP_SECRET is configured, the package validates the X-Hub-Signature-256 signature before accepting the request.

The package then dispatches:

SocialMedia\WhatsApp\Events\WhatsAppWebhookReceived

Send a text message

Request:

POST /api/whatsapp/messages/text
{
  "to": "254700000000",
  "body": "Hello from Laravel"
}

Send a template message

Request:

POST /api/whatsapp/messages/template
{
  "to": "254700000000",
  "name": "hello_world",
  "language": "en_US"
}

Extending in the Host App

Listen for the webhook event in your app to process messages, statuses, and delivery updates:

use SocialMedia\WhatsApp\Events\WhatsAppWebhookReceived;

Event::listen(WhatsAppWebhookReceived::class, function (WhatsAppWebhookReceived $event) {
    // Handle $event->payload
});

Meta Setup Checklist

Create a Meta app and enable the WhatsApp product.
Get an access token.
Get your Phone Number ID and WhatsApp Business Account ID.
Set the Meta webhook callback URL to your app's /api/whatsapp/webhook endpoint.
Set Meta's verify token to match WHATSAPP_WEBHOOK_VERIFY_TOKEN.
Subscribe the app to your WABA.

caydeesoft / whatsapp

Maintainers

Package info

Statistics

Security