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

Laravel WhatsApp Cloud API

Laravel-first wrapper for the WhatsApp Cloud API with fluent message builders, webhook handling, WhatsApp Flows support, conversational components, business-scoped user IDs, notifications, and a facade.

Table of Contents

• Official WhatsApp Docs
• Installation
• Configuration
• Sending Messages
• Replying To Messages
• Message Builders
• Laravel Notifications
• Webhooks
• WhatsApp Flows
• Business-Scoped User IDs
• Conversational Components
• Media Endpoints
• Artisan Commands
• Facade Reference
• Quality
• Disclaimer
• Contributing
• Security
• License

Official WhatsApp Docs

This package stays close to the WhatsApp Cloud API. When you need platform-level rules, setup steps, or payload constraints, these are the best references:

• WhatsApp Cloud API overview
• Get started guide
• Send messages guide
• Webhook setup and payloads
• Message templates
• WhatsApp Flows
• Media messages
• Conversational components

Installation

Publish the config file:

This creates config/whatsapp-cloud.php in your application.

Before wiring the package into your app, complete Meta's Get started guide so you have a business app, a phone number ID, an access token, and webhook credentials.

Configuration

At minimum, you need the same credentials described in Meta's Get started guide:

Set your WhatsApp Cloud API credentials in .env:

By default, webhook parsing only processes payloads whose metadata.phone_number_id matches your configured WHATSAPP_PHONE_NUMBER_ID. This helps when one app receives events for multiple numbers.

If you plan to receive real events locally, expose your app over HTTPS and configure the webhook in the Meta app dashboard. Meta's webhook docs cover the verification flow and payload delivery model.

Optional settings

Flow endpoint encryption keys (only needed when using WhatsApp Flows with a custom endpoint):

HTTP client tuning:

• WHATSAPP_NOTIFICATION_PHONE_NUMBER_ID lets notifications use a different default sending number.
• WHATSAPP_STRICT_MODE makes malformed outgoing payloads fail fast.
• WHATSAPP_ENABLE_WELCOME_MESSAGE is used when syncing conversational components.

Sending Messages

For delivery rules, supported conversation windows, and message-type caveats, see Meta's send messages guide.

The package accepts either a plain phone number string or a Recipient instance. Use Recipient::businessScopedUser(...) when you already know you must send through the recipient field instead of to.

For readability, the public API generally exposes both explicit and compact variants where it helps, for example to(...) and toRecipient(...), or id() and identifier().

The facade is the primary way to use the package in application code:

You can still resolve WhatsAppClient directly when you want container injection or lower-level control, but the examples in this README use the facade by default.

Most sections below focus on building the message payload. In application code, pair those builders with WhatsAppCloud::sendMessage(...).

Sending to business-scoped user IDs

Replying To Messages

This package supports WhatsApp message context directly. The examples below use the facade, which is the recommended entry point for application code.

Fluent reply chaining

Use this when you already have a send call and want to attach the reply context clearly at the end:

Reply context on the message builder

Use this when you want the message object itself to carry the reply context:

The lower-level context method is also available:

Replying from webhook events

If you are replying to an inbound webhook, use the convenience routing helper on the inbound user object:

Message Builders

Every builder returns an immutable instance via create() and fluent methods. Call toArray() to inspect the raw payload.

Meta's payload rules still apply. When a message type has setup or platform constraints, the most useful place to confirm them is Meta's documentation.

Use these builders with WhatsAppCloud::sendMessage(...) or WhatsAppMessage::using(...) in notifications.

Text

Media

See Meta's media reference for supported upload and send behavior.

Supported types: audio, document, image, sticker, video.

Template

Template messages require an approved template in WhatsApp Manager. For template approval, categories, and parameter rules, see Meta's message template docs.

Richer template parameters:

Reaction

Reactions target an existing WhatsApp message ID. Meta documents the behavior in the send messages guide.

Location

Location request

Location requests are interactive messages, so client support and rendering still follow Meta's send messages guide.

Contacts

Interactive reply buttons

Interactive message rendering can vary by WhatsApp client. Meta's send messages guide is the best place to confirm current limits.

Interactive list

Call to action URL

Flow message

Before sending flow messages, make sure the flow is created and published in Meta. See the official WhatsApp Flows docs.

Product message

Commerce messages depend on catalog and product setup in Meta Commerce Manager. Confirm the required identifiers in Meta's send messages guide.

Product list message

Raw payload escape hatch

If Meta adds a message shape before this package exposes a dedicated builder, you can still send the raw payload directly.

Laravel Notifications

The package includes a WhatsAppChannel so you can send WhatsApp messages through Laravel notifications.

This is still built on top of the same WhatsApp Cloud API send endpoint, so template and conversation-window rules remain the same.

Define a notification

Route the notification

Add routeNotificationForWhatsApp to your notifiable model:

Use richer builders in notifications

Webhooks

If you are new to the webhook flow, read Meta's webhook docs alongside this section.

Routes

The GET route handles Meta webhook verification. The POST route validates signatures, parses inbound payloads, and dispatches Laravel events.

When WHATSAPP_RESTRICT_INBOUND_MESSAGES_TO_PHONE_NUMBER_ID=true, the webhook parser ignores entries whose metadata.phone_number_id does not match your configured phone_number_id.

Custom webhook controller

If you want to handle inbound messages yourself instead of relying on event listeners, extend BaseWhatsAppWebhookController and override the protected hooks you need. The package still handles signature validation, payload parsing, typed DTO creation, and the default JSON webhook response.

Useful hooks when extending the controller:

• handleIncomingMessage()
• handleIncomingStatus()
• handleWebhookPayload()
• webhookResponse()
• parseWebhookPayload()
• ensureValidSignature()

If you want a hybrid approach, your custom controller can still call the package dispatch helpers:

• dispatchWelcomeRequested()
• dispatchMessageReceived()
• dispatchSpecializedMessageEvents()
• dispatchStatusUpdated()

Events

Listen for events

Inbound message helpers

WhatsApp Flows

This section focuses on the Laravel integration points. For flow authoring, publishing, encryption requirements, and runtime behavior, use Meta's WhatsApp Flows docs as the primary reference.

Flow endpoint controller

Extend FlowEndpointController and wire a route:

FlowEndpointController handles the encrypted request/response cycle for you. Your controller only needs to decide what the next flow payload should be.

Generate flow keys

Copy the printed environment values to .env, then publish the public key to Meta:

Business-Scoped User IDs

WhatsApp can send business-scoped user IDs (BSUIDs) in webhook payloads. This package supports both legacy phone-number identifiers and the newer BSUID fields.

The goal is simple: you should not have to care whether the user came in as a BSUID, parent BSUID, or phone number when replying.

Inbound identity resolution order:

1. user_id / from_user_id (preferred)
2. parent_user_id / from_parent_user_id
3. wa_id / from (legacy phone number)

Use recipient() when you want the package to choose the correct outbound field automatically.

Outbound routing:

• When sending to a BSUID, the package uses recipient in the API payload
• When sending to a phone number, the package uses to
• Recipient::businessScopedUser(...) and Recipient::phoneNumber(...) make this explicit

Conversational Components

Manage commands, prompts, and welcome messages on your business phone number.

If you need the product behavior and limits behind these features, Meta's conversational components docs are the authoritative reference.

Configure components in config/whatsapp-cloud.php:

Sync via artisan:

Media Endpoints

These helpers wrap Meta's media endpoints. For MIME support, lifecycle details, and download semantics, see Meta's media reference.

Mark messages as read

This maps to Meta's message status update behavior in the send messages guide.

Show typing indicator

Typing indicators are sent through the same message status update flow and are tied to a message you are replying to.

Artisan Commands

Facade Reference

The WhatsAppCloud facade resolves to WhatsAppClient.

The alias is registered automatically via Laravel auto-discovery.

If you prefer constructor injection instead of the facade, resolve Mohapinkepane\WhatsAppCloud\Client\WhatsAppClient from the container and use the same methods.

Disclaimer

This is an independent community package. It is not affiliated with, endorsed by, or maintained by Meta or WhatsApp.

Platform rules such as template approval, pricing, delivery windows, rate limits, and account review remain defined by Meta. Use the official documentation linked above when you need the authoritative platform behavior.

See DISCLAIMER.md for the longer form notice.

Quality

Real integration tests

composer integration-test sends real outbound messages to the WhatsApp Cloud API. It is intentionally separated from composer test so the default suite stays fast and offline.

Use .env.integration.example as the starting point, then copy its values into .env.integration. The integration suite loads .env.integration automatically.

Required environment variables:

Optional overrides for the live suite:

The live suite covers plain text, URL previews, image/audio/document/sticker/video media, contacts, location, location requests, reply buttons, lists, CTA URL messages, contextual replies, and reactions. Template, flow, commerce, and business-scoped recipient coverage auto-skip until their extra identifiers are configured.

Non-template messages still depend on WhatsApp's customer service window rules. If delivery is accepted by the API but nothing appears on the device, verify the recipient has an open conversation window with the business phone number. Meta documents that behavior in the send messages guide.

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md.

License

The MIT License (MIT). See LICENSE for details.