WhatsApp Cloud API for PHP

Lightweight PHP wrapper for Meta's WhatsApp Cloud API. Zero dependencies.

Send text, template, image, document, video, audio, location, contact, and sticker messages. Receive and verify webhooks.

Author: Renzo Johnson

Requirements

PHP 8.4+
ext-curl
ext-json

Installation

composer require renzojohnson/whatsapp-cloud-api

Quick Start

use RenzoJohnson\WhatsApp\WhatsApp;

$wa = new WhatsApp('YOUR_PHONE_NUMBER_ID', 'YOUR_ACCESS_TOKEN');

// Send a text message
$wa->sendText('14155551234', 'Hello from PHP!');

Sending Messages

Text

$wa->sendText('14155551234', 'Hello World');

// With link preview
$wa->sendText('14155551234', 'Check https://example.com', previewUrl: true);

Template

// Simple template (no parameters)
$wa->sendTemplate('14155551234', 'hello_world', 'en_US');

// Template with parameters
$wa->sendTemplate('14155551234', 'order_update', 'en_US', [
    [
        'type' => 'body',
        'parameters' => [
            ['type' => 'text', 'text' => 'John'],
            ['type' => 'text', 'text' => 'ORD-12345'],
        ],
    ],
]);

Image

// By URL
$wa->sendImage('14155551234', link: 'https://example.com/photo.jpg', caption: 'A photo');

// By media ID (uploaded via uploadMedia)
$wa->sendImage('14155551234', mediaId: 'media_123');

Document

$wa->sendDocument(
    '14155551234',
    link: 'https://example.com/invoice.pdf',
    caption: 'Your invoice',
    filename: 'invoice-2026.pdf',
);

Video

$wa->sendVideo('14155551234', link: 'https://example.com/clip.mp4', caption: 'Watch this');

Audio

$wa->sendAudio('14155551234', link: 'https://example.com/audio.mp3');

Location

$wa->sendLocation(
    '14155551234',
    latitude: 28.5383,
    longitude: -81.3792,
    name: 'Orlando Office',
    address: '123 Main St, Orlando, FL',
);

Contact

$wa->sendContact(
    '14155551234',
    name: ['first_name' => 'Jane', 'last_name' => 'Doe'],
    phones: [['phone' => '+14155559999', 'type' => 'CELL']],
);

Sticker

$wa->sendSticker('14155551234', link: 'https://example.com/sticker.webp');

Media

Upload

$response = $wa->uploadMedia('/path/to/file.jpg', 'image/jpeg');
$mediaId = $response['id'];

Get Media URL

$media = $wa->getMedia('media_123');
$url = $media['url'];

Delete

$wa->deleteMedia('media_123');

Mark as Read

$wa->markAsRead('wamid.abc123');

Webhooks

Verification (GET request from Meta)

use RenzoJohnson\WhatsApp\Webhook\Listener;

// Responds to Meta's verification challenge
Listener::verify('YOUR_VERIFY_TOKEN');

Receiving Messages (POST from Meta)

use RenzoJohnson\WhatsApp\Webhook\Listener;
use RenzoJohnson\WhatsApp\Webhook\Notification;

Listener::listen('YOUR_APP_SECRET', function (Notification $notification, array $raw) {
    if ($notification->isText()) {
        echo 'From: ' . $notification->from . "\n";
        echo 'Text: ' . $notification->text . "\n";
    }

    if ($notification->isImage()) {
        echo 'Image ID: ' . $notification->image['id'] . "\n";
    }
});

The listener validates the X-Hub-Signature-256 header using HMAC-SHA256 before processing. Invalid signatures return 401.

Notification Properties

Property	Type	Description
`from`	string	Sender's phone number
`type`	string	Message type (text, image, document, etc.)
`timestamp`	string	Unix timestamp
`messageId`	?string	WhatsApp message ID
`text`	?string	Text body (when type is text)
`image`	?array	Image data (id, mime_type, sha256)
`document`	?array	Document data
`video`	?array	Video data
`audio`	?array	Audio data
`location`	?array	Location data (latitude, longitude)
`sticker`	?array	Sticker data
`contacts`	?array	Contact cards
`interactive`	?array	Interactive response data
`context`	?array	Reply context (quoted message)

Type Checks

$notification->isText();
$notification->isImage();
$notification->isDocument();
$notification->isVideo();
$notification->isAudio();
$notification->isLocation();
$notification->isSticker();
$notification->isInteractive();

Error Handling

use RenzoJohnson\WhatsApp\Exception\AuthenticationException;
use RenzoJohnson\WhatsApp\Exception\RateLimitException;
use RenzoJohnson\WhatsApp\Exception\WhatsAppException;

try {
    $wa->sendText('14155551234', 'Hello');
} catch (AuthenticationException $e) {
    // Invalid or expired access token (401)
} catch (RateLimitException $e) {
    // Too many requests (429)
} catch (WhatsAppException $e) {
    // Other API errors (400, 500, etc.)
    $errorData = $e->getErrorData();
}

Testing

composer install
vendor/bin/phpunit

renzojohnson/whatsapp-cloud-api