whatsapp-gateway/php-sdk

PHP SDK for WhatsApp Gateway customer API and webhooks.

v0.1.0 2026-05-10 19:03 UTC

Requires

• php: >=8.0
• ext-curl: *
• ext-json: *

Requires (Dev)

• phpunit/phpunit: ^9.6 || ^10.0

MIT

README

SDK examples are available now. Official package releases are being prepared.

This private beta scaffold provides a small PHP client for the WhatsApp Gateway customer API and customer webhooks. It talks only to WhatsApp Gateway public endpoints.

Installation

During private beta, copy this package into your project or use it from a private repository.

Do not use a public package install command until an official package release is announced.

Examples

Example scripts are available in the examples/ directory:

• examples/send-message.php
• examples/verify-webhook.php
• examples/parse-webhook-event.php

Tests

The package includes phpunit.xml and no-live-network tests. After installing development dependencies, run:

vendor/bin/phpunit

Configure The Client

use WhatsAppGateway\Client;

$client = new Client([
    'api_key' => 'wg_live_replace_with_your_key',
    'base_url' => 'https://evoapi.faisak.com',
    'timeout' => 15,
]);

Send A Message

$result = $client->sendMessage([
    'instance_id' => 'demo-support-line',
    'phone' => '+9665XXXXXXX',
    'message' => 'Your support request has been updated.',
    'message_purpose' => 'support',
]);

echo $result['message_id'] ?? '';

Allowed message_purpose values:

• transactional
• operational
• support
• internal_team
• authentication

Not allowed:

• marketing
• promotion
• cold_outreach
• bulk_campaign
• political
• unknown

Handle API Errors

use WhatsAppGateway\ApiException;

try {
    $client->sendMessage([
        'instance_id' => 'demo-support-line',
        'phone' => '+9665XXXXXXX',
        'message' => 'Your order has shipped.',
        'message_purpose' => 'transactional',
    ]);
} catch (ApiException $exception) {
    echo $exception->getErrorCode();
    echo $exception->getMessage();
}

Common error codes include module_not_enabled, message_purpose_not_allowed, recipient_suppressed, sending_throttled, and gateway_send_failed.

Verify Webhook Signatures

use WhatsAppGateway\Webhooks;

$rawBody = file_get_contents('php://input') ?: '';
$timestamp = $_SERVER['HTTP_X_WHATSAPP_GATEWAY_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_WHATSAPP_GATEWAY_SIGNATURE'] ?? '';
$secret = 'replace_with_webhook_signing_secret';

if (!Webhooks::verifySignature($rawBody, $timestamp, $signature, $secret)) {
    http_response_code(401);
    exit('Invalid signature');
}

Preferred signature format:

X-WhatsApp-Gateway-Signature: sha256=<hex>

The HMAC input is:

timestamp + "." + raw_body

Parse message.received

use WhatsAppGateway\Webhooks;

$payload = Webhooks::parseEvent($rawBody);

if (Webhooks::eventType($payload) === 'message.received') {
    $from = $payload['from'] ?? '';
    $messageText = $payload['message_text'] ?? '';
    $timestamp = $payload['timestamp'] ?? '';
}

Parse recipient.opted_out

$payload = Webhooks::parseEvent($rawBody);

if (Webhooks::eventType($payload) === 'recipient.opted_out') {
    $from = $payload['from'] ?? '';
    $reason = $payload['reason'] ?? 'recipient_requested_stop';
}

Responsible Messaging

WhatsApp Gateway is for transactional, operational, support, internal team, and authentication-style messages. Marketing, cold outreach, political messaging, and bulk campaigns are not allowed.

Useful Links

• https://evoapi.faisak.com/docs/openapi
• https://evoapi.faisak.com/docs/sdk/postman