Z Api Php Sdk Laravel Package

Getting Started

Install the package via Composer:

composer require saade/z-api-php-sdk

Publish the configuration file (if the package provides one):

php artisan vendor:publish --tag="z-api-config"

Add your Z-API credentials to .env. Typical values include the instance ID, token, and client token (used for webhook security):

ZAPI_INSTANCE_ID=your-instance-id
ZAPI_TOKEN=your-instance-token
ZAPI_CLIENT_TOKEN=your-client-token

The quickest first use case is sending a WhatsApp text message. Resolve the SDK from the container (or use its facade, if provided) and call the relevant resource method—for example:

use Saade\ZApi\ZApi;

$response = ZApi::messages()->sendText(
    phone: '5511999999999',
    message: 'Hello from Laravel!'
);

Start by reading the package README for the exact resource names and method signatures. Most day‑to‑day work will involve the messages, instances, and contacts resources.

Implementation Patterns

Wrap SDK calls in your own service or action classes. Keep controllers thin by delegating message sending, contact syncing, and instance management to dedicated classes. This makes testing and swapping the SDK easier.

class SendWhatsAppMessage
{
    public function __construct(private ZApi $zapi) {}

    public function handle(string $phone, string $text): void
    {
        $this->zapi->messages()->sendText($phone, $text);
    }
}

Queue outgoing messages. Sending a message is an external HTTP call; always dispatch it through a queued job to avoid blocking web requests and to benefit from retries.

SendWhatsAppMessage::dispatch($phone, $text)->onQueue('whatsapp');

Handle webhooks in a dedicated controller. Z-API sends delivery statuses and incoming messages via webhooks. Validate the request using the client token (the package may provide a middleware or helper), then dispatch a job to process the payload asynchronously.

Use Saloon’s testing helpers. Since the SDK is built on Saloon, you can fake HTTP responses in your tests:

ZApi::fake([
    SendTextRequest::class => ZApi::response(['messageId' => 'abc123']),
]);

Support multiple instances. If your application manages more than one WhatsApp instance, instantiate the SDK with per‑instance credentials rather than relying solely on the global config. Check whether the package exposes a factory or a ZApi::forInstance() method.

Gotchas and Tips

• Saloon 4 is required in v1.1.0. This release fixes CVE‑2026‑33942, CVE‑2026‑33182, and CVE‑2026‑33183. If you are upgrading from v1.0.0, review Saloon’s upgrade guide for breaking changes (e.g., response handling, middleware signatures, and request class constructors). Run your test suite after upgrading.
• Laravel 13 support means the package works on Laravel 13, but confirm your PHP version meets Laravel 13’s requirements. If you are still on Laravel 10/11/12, v1.1.0 remains compatible.
• Config caching: after changing Z‑API credentials in .env, run php artisan config:clear (or config:cache in production). Stale config is a common source of “invalid token” errors.
• Webhook security: never trust incoming webhook payloads without verifying the client token. Use a timing‑safe comparison and reject requests with missing or mismatched tokens.
• Rate limits and retries: Z‑API enforces rate limits. Implement exponential backoff on 429 responses. Saloon’s retry middleware can be configured on the SDK’s client if the package exposes it.
• Error handling: SDK methods may throw exceptions for API errors (4xx/5xx) or network failures. Catch Saloon\Exceptions\Request\RequestException and log the response body for debugging.
• Extension points: Saloon allows custom middleware, so you can add request logging, metrics, or additional retries by extending the SDK’s client. Look for a ZApi::client() method or a config option to register middleware.
• Version pinning: given the security fixes in v1.1.0, pin to ^1.1 in composer.json and avoid downgrading to v1.0.0.