WhatsApp Cloud API PHP SDK

This package provides a PHP interface for interacting with the WhatsApp Cloud API. It allows developers to send various types of messages (text, media, templates, etc.) through their PHP applications.

Note: The first 1,000 conversations each month are free via the WhatsApp Cloud API.

To use the API, instantiate the WhatsAppCloudApi class with your configuration. You must provide your from_phone_number_id and your Facebook WhatsApp application access_token. If you intend to manage templates, you should also provide your business_id.

use Netflie//WhatsAppCloudApi//WhatsAppCloudApi;

$whatsapp_cloud_api = new WhatsAppCloudApi([
    'from_phone_number_id' => 'your-configured-from-phone-number-id',
    'access_token' => 'your-facebook-whatsapp-application-token',
]);

Webhook Verification

When setting up your webhook in the Meta App dashboard, use the WebHook::verify method to validate the request.

Reading Notifications

Use the WebHook class to parse incoming JSON payloads from Meta. Use read() for a single notification or readAll() to handle batched notifications.

use Netflie\WhatsAppCloudApi\WebHook;

// Verification
$webhook = new WebHook();
echo $webhook->verify($_GET, "<your-verify-token>");

// Reading notifications
$payload = json_decode(file_get_contents('php://input'), true);
$webhook = new WebHook();
$notification = $webhook->read($payload);

In version 4.x, the sendContact() method has changed its parameter order. The BSUID recipient argument now comes before the variadic phone arguments.

If you were previously passing a Phone as the third argument, you must now explicitly pass null or the BSUID recipient first to maintain correct argument positioning.

// Sending to a standard phone number
$whatsapp_cloud_api->sendContact(to: $to, name: $name, recipient: null, phone: $phone);

// Sending only to a BSUID recipient
$whatsapp_cloud_api->sendContact(to: null, name: $name, recipient: $recipient_bsuid, phone: $phone);

Before using this SDK, ensure your environment meets the following requirements:

• PHP: version 7.4 or higher.
• CURL: a recent version (>= 7.19.4) compiled with OpenSSL and zlib.

Install the library using Composer to integrate the WhatsApp Cloud API into your PHP project.

composer require netflie/whatsapp-cloud-api

In version 4.x, all send* methods that post to /messages support an optional ?string $recipient = null argument for BSUID (Business Solution User ID) recipients.

• You can send a message using to, recipient, or both.
• If both are provided, the WhatsApp Cloud API gives precedence to to.
• The base message model now requires at least one of to or recipient to be present.

// Sending with BSUID
$whatsapp_cloud_api->sendTextMessage(to: null, text: 'Hello from BSUID', preview_url: false, recipient: 'US.13491208655302741918');

The WhatsAppCloudApi methods return a Response object on success. If the WhatsApp servers return an error, a \Netflie\WhatsAppCloudApi\Response\ResponseException is thrown. You can catch this exception to inspect the actual response returned by Meta.

try {
    $response = $whatsapp_cloud_api->sendTextMessage('34676104574', 'Hello');
} catch (\Netflie\WhatsAppCloudApi\Response\ResponseException $e) {
    print_r($e->response()); // Inspect the Meta server response
}