warsita / warsita-php

v0.2.1 2026-10-29 06:56 UTC

Requires

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

Requires (Dev)

• orchestra/testbench: ^8.0 || ^9.0 || ^10.0
• phpunit/phpunit: ^10.5 || ^11.0
• symfony/yaml: ^6.4 || ^7.0

MIT

• laravel
• whatsapp
• webhook
• whatsapp-api
• warsita

Published on Packagist.org on 2026-10-29 06:56 UTC

README

The official PHP client for the Warsita WhatsApp API: send messages, manage sessions, contacts and groups, and verify webhooks. No dependencies beyond the curl and json extensions, and it registers itself in Laravel.

composer require warsita/warsita-php

PHP 8.1 or newer.

Send a message

use Warsita\Warsita;

$warsita = new Warsita('wsk_…'); // the session's API key, or set WARSITA_API_KEY

$message = $warsita->messages->send(['to' => '[phone]', 'text' => 'Your order has shipped.']);
echo $message['id'], ' ', $message['status']; // msg_… queued

Every send carries an Idempotency-Key (generated, or pass idempotencyKey:), so the client retries rate limits and dropped connections without sending twice.

$warsita->messages->send(['to' => '[e-mail]', 'image' => ['url' => 'https://example.com/receipt.png', 'caption' => 'Receipt']]);
$warsita->messages->send(['to' => '[phone]', 'poll' => ['name' => 'Which day?', 'options' => ['Friday', 'Saturday'], 'selectable_count' => 1]]);

$file = $warsita->media->upload(file_get_contents('invoice.pdf'), 'invoice.pdf', 'application/pdf');
$warsita->messages->send(['to' => '[phone]', 'document' => ['media_id' => $file['id']]]);

Laravel

The service provider is discovered on its own. Set the key in .env:

WARSITA_API_KEY=wsk_…

and inject the client wherever you need it:

use Warsita\Warsita;

class ShipmentController
{
    public function notify(Warsita $warsita, Order $order)
    {
        $warsita->messages->send(['to' => $order->phone, 'text' => "Order {$order->number} has shipped."]);
    }
}

php artisan vendor:publish --tag=warsita-config copies config/warsita.php if you want to change it (WARSITA_SESSION_ID and WARSITA_BASE_URL are read too).

Personal access tokens

A session API key (wsk_…) acts for its own session. A personal access token (wsp_…) acts for the whole workspace and manages sessions; name the session for messaging calls:

$warsita = new Warsita('wsp_…', sessionId: 'ses_3kV9mQ2pX7aL0zR5tN8w');
$sessions = $warsita->sessions->list();
$warsita->groups->list(sessionId: $sessions[1]['id']); // or per call

$warsita->sessions->events('ses_…', function (array $state) {
    echo $state['status'], "\n"; // live status and QR codes; return false to stop
});

With several numbers, a token can let Warsita pick one per message (sender rotation): of the sessions with the rotation setting on, the one that wrote to this person longest ago.

$message = $warsita->messages->send(['rotate' => true, 'to' => '[phone]', 'text' => 'Your invoice is due on 1 November.']);
echo $message['from'], ' ', $message['session_id'];
$warsita->messages->get($message['id']); // no session needed

Sessions can be private to the member who creates them: $warsita->sessions->create(['name' => 'My number', 'visibility' => 'private']).

Receive webhooks

Pass the raw body, not parsed JSON:

use Warsita\Webhook;

$event = Webhook::verify(file_get_contents('php://input'), $_SERVER['HTTP_X_WARSITA_SIGNATURE'] ?? null, $webhookSecret);
if ($event['event'] === 'messages.received') {
    error_log($event['data']['text'] ?? '');
}

In Laravel: Webhook::verify($request->getContent(), $request->header('X-Warsita-Signature'), config('services.warsita.webhook_secret')). It throws WebhookVerificationException on a wrong signature or one older than five minutes.

What's included

messages	send, list, get, edit, delete, resend, react, markRead
media	upload, get
account	get, setPresence, setChatPresence
contacts	list, check, get, picture, ids, block, unblock, blocklist
groups	list, get, create, update, updateParticipants, setPicture, inviteLink, resetInviteLink, inviteInfo, join, leave
sessions	list, create, get, update, delete, connect, restart, disconnect, qr, pairingCode, regenerateApiKey, logs, clearMessages, events (live stream)
sessions->webhook	get, set, rotateSecret, test, deliveries, resend

Methods return the API's JSON as arrays; responses that hold only data are unwrapped. Errors throw Warsita\WarsitaException with the API's status, errorCode and message (and retryAfter on rate limits). The full reference is at warsita.com/docs.

Development

openapi.yaml is a copy of the published spec (curl -sf https://warsita.com/openapi.yaml -o openapi.yaml). composer install && vendor/bin/phpunit checks, among other things, that every operation in the spec has a method.