PHP code example of gowa-php / sdk

    
        
<?php
require_once('vendor/autoload.php');

/* Start to develop here. Best regards https://php-download.com/ */

    

gowa-php / sdk example snippets

use Gowa\Sdk\Config;
use Gowa\Sdk\GowaClient;

$config = new Config(
    baseUrl: 'https://gowa.yourcompany.com',
    username: 'admin',
    password: 'secretpassword',
    timeout: 15
);

$client = new GowaClient($config);

// Or inject a custom Guzzle handler (e.g. for testing or Laravel Http::fake() HandlerStack) without losing Config options:
// $client = new GowaClient($config, handler: $customHandler);

// Register device and webhook
$device = $client->createDevice(
    deviceId: 'my-instance-uuid',
    webhookUrl: 'https://myapi.com/webhooks/gowa/my-instance-uuid',
    webhookSecret: 'my_hmac_secret_48_chars',
    events: ['message', 'message.ack', 'message.reaction', 'message.edited', 'message.revoked']
);

// Start pairing via QR Code
$pairing = $client->startQrPairing('my-instance-uuid');
echo $pairing->qrLink; // QR Code URL

// Or request 8-digit code for manual typing on phone
$codePairing = $client->startCodePairing('my-instance-uuid', '5511999998888');
echo $codePairing->pairCode; // e.g. ABCD-1234

// List all registered devices on the server
$devices = $client->devices();

// Reconnect or permanently delete/purge a device slot
$client->reconnectDevice('my-instance-uuid');
$client->deleteDevice('my-instance-uuid');

// Check if a number is registered on WhatsApp before messaging
if ($client->checkUser('my-instance-uuid', '5511999998888')) {
    echo "Phone is on WhatsApp!";
}

// Send text with mentions (@everyone or phone numbers) and disappearing messages duration (24h = 86400s)
$client->sendText(
    deviceId: 'my-instance-uuid',
    to: '[email protected]',
    text: 'Hello @everyone and @5511999998888!',
    mentions: ['5511999998888', '@everyone'],
    duration: 86400,
);

// Send URL link with preview
$client->sendLink('my-instance-uuid', '5511999998888', 'https://fazz.ai', 'Check our website');

// Send interactive poll
$client->sendPoll('my-instance-uuid', '5511999998888', 'What is your preferred time?', ['Morning', 'Afternoon', 'Evening']);

use Gowa\Sdk\Dto\MediaType;
use Gowa\Sdk\Dto\MediaUpload;
use Gowa\Sdk\Dto\MediaPayload;

// Send voice note (PTT) from external URL
$upload = MediaUpload::fromUrl('https://mycompany.com/storage/voicenote.m4a');
$media = new MediaPayload(type: MediaType::Audio, upload: $upload, voice: true);
$client->sendMedia('my-instance-uuid', '5511999998888', $media);

// Send local image with caption mentions and view-once enabled
$imgUpload = MediaUpload::fromPath('/path/to/invoice.jpg');
$imgMedia = new MediaPayload(
    type: MediaType::Image,
    upload: $imgUpload,
    caption: 'Invoice for @5511999998888',
    mentions: ['5511999998888'],
    viewOnce: true,
);
$client->sendMedia('my-instance-uuid', '5511999998888', $imgMedia);

use Gowa\Sdk\Dto\ScheduleOptions;

// Schedule a message for future or recurring delivery
$schedule = new ScheduleOptions(
    scheduledAt: '2026-10-01T09:00:00Z',
    timezone: 'America/Sao_Paulo',
    recurrence: 'weekly',
    weekdays: [1, 3, 5], // Monday, Wednesday, Friday
    endAt: '2026-12-31T23:59:59Z',
    occurrenceLimit: 20,
);

$sent = $client->sendText(
    deviceId: 'my-instance-uuid',
    to: '5511999998888',
    text: 'Weekly reminder!',
    schedule: $schedule,
);

echo $sent->scheduleId; // e.g. '0b5c3a8e-7f5d-4d6f-9d1e-2f8c1a7b9e10'

// Manage schedules
$schedules = $client->listSchedules('my-instance-uuid');
$client->pauseSchedule('my-instance-uuid', $sent->scheduleId);
$client->resumeSchedule('my-instance-uuid', $sent->scheduleId);
$client->cancelSchedule('my-instance-uuid', $sent->scheduleId);

// Forward message (also supports scheduling via ScheduleOptions)
$client->forwardMessage('my-instance-uuid', '5511999998888', 'WAMID_ORIGINAL_123');

// Edit sent text
$client->editMessage('my-instance-uuid', '5511999998888', 'WAMID_ORIGINAL_123', 'Updated message text');

// Send emoji reaction
$client->sendReaction('my-instance-uuid', '5511999998888', 'WAMID_ORIGINAL_123', '👍');

// Revoke (Delete for everyone)
$client->revokeMessage('my-instance-uuid', '5511999998888', 'WAMID_ORIGINAL_123');

// Star or unstar message
$client->starMessage('my-instance-uuid', '5511999998888', 'WAMID_ORIGINAL_123', true);

// Request older chat history from the phone on-demand (e.g. 50 messages)
$client->requestChatHistory('my-instance-uuid', '5511999998888', count: 50);

use Gowa\Sdk\Exceptions\MediaUnavailableException;

// 1. Query media with candidate phones (e.g. echo outbound vs inbound recipient)
try {
    $remoteMedia = $client->describeMedia(
        deviceId: 'my-instance-uuid',
        phones: ['5511888888888', '5511999999999'], // tries candidate phones in order
        providerMessageId: 'WAMID_ORIGINAL_123'
    );
} catch (MediaUnavailableException $e) {
    // Media was permanently refused (e.g. text-only message or expired)
    $remoteMedia = null;
}

// 2. Download decrypted media with custom timeout (default is Config timeout)
if ($remoteMedia !== null) {
    $client->downloadMedia(
        mediaUrl: $remoteMedia->url,
        destinationPath: '/path/to/downloaded.mp4',
        timeout: 120 // dedicated timeout for large media downloads
    );
}

use Gowa\Sdk\Dto\EventPayload;
use Gowa\Sdk\Dto\LiveLocationPayload;
use Gowa\Sdk\Dto\PollPayload;
use Gowa\Sdk\Security\WebhookSignature;
use Gowa\Sdk\Webhook\Dto\IncomingAck;
use Gowa\Sdk\Webhook\Dto\IncomingMessage;
use Gowa\Sdk\Webhook\Event;
use Gowa\Sdk\Webhook\WebhookParser;

$payload = file_get_contents('php://input');
// GOWA sends the signature header formatted as "sha256=<hex>"
$signature = $_SERVER['HTTP_X_HUB_SIGNATURE_256'] ?? '';
$secret = 'my_hmac_secret_48_chars';

// 1. Verify HMAC SHA-256 signature (ion: {$poll->question}\n";
            })
            ->whenEvent(function (EventPayload $event) {
                echo "Event title: {$event->name}\n";
            })
            ->whenText(function (string $text) {
                echo "Text: {$text}\n";
            })
            ->otherwise(function (IncomingMessage $msg) {
                echo "Other message type: {$msg->type}\n";
            });
    })
    ->onAck(function (IncomingAck $ack) {
        echo "Receipt: {$ack->receiptType}\n";
    })
    ->otherwise(function (mixed $data, Event $event) {
        echo "Unhandled or unknown event: {$event->value}\n";
    });

// Traditional array access and helper methods remain fully supported:
// $event = WebhookParser::parse($payload);
// if ($event->isMessage()) { $msg = $event->message(); ... }
// or $event['event'] === Event::Message

use Gowa\Sdk\Exceptions\GowaRequestException;
use Gowa\Sdk\Exceptions\GowaUnreachableException;
use Gowa\Sdk\Exceptions\MediaUnavailableException;

try {
    $client->sendText('my-device-id', '5511999998888', 'Hello');
} catch (GowaUnreachableException $e) {
    // Network failure, connection timeout, DNS failure, or server unreachable
    // Reconcile delivery status before retrying non-idempotent operations (such as sending messages)
} catch (MediaUnavailableException $e) {
    // Permanent media download refusal (e.g. message does not contain media or unsupported format)
} catch (GowaRequestException $e) {
    // Server responded with an error (4xx/5xx or code != SUCCESS)
    $status = $e->statusCode;    // e.g. 400
    $code = $e->gowaCode;        // e.g. "VALIDATION_ERROR"
    $message = $e->gowaMessage;  // e.g. "your audio type is not allowed..."
}

bash
composer