README

A PHP HTTP Client for the Wati.io WhatsApp API. Provides a simple, fluent API to interact with Wati's REST API.

Related Packages

For a higher-level, feature-rich integration, consider using wati-sdk. It provides ready-to-use request classes, response DTOs, and additional convenience features built on top of this HTTP client.

Installation

This package requires PHP 8.3 or higher (8.3, 8.4, and 8.5 are supported).

composer require "phpjuice/wati-http-client"

Setup

Get Your Credentials

1. Log in to your Wati Account
2. Navigate to API Docs in the top menu
3. Copy your API Endpoint URL and Bearer Token

Create a Client

<?php

use Wati\Http\WatiClient;
use Wati\Http\WatiEnvironment;

// Get this URL from your Wati Dashboard (API Docs section)
// It includes your tenant ID: https://your-instance.wati.io/{tenantId}
$endpoint = "https://your-instance.wati.io/123456";
$bearerToken = "your-bearer-token";

// Create environment
$environment = new WatiEnvironment($endpoint, $bearerToken);

// Create client
$client = new WatiClient($environment);

With Custom Options

<?php

$client = new WatiClient($environment, [
    'timeout' => 60,           // Request timeout in seconds (default: 30)
    'connect_timeout' => 15,   // Connection timeout in seconds (default: 10)
    'verify' => true,          // Verify SSL certificate (default: true)
    'proxy' => 'tcp://localhost:8080',  // Proxy URL (default: null)
    'debug' => false,          // Enable debug mode (default: false)
]);

Usage

Making Requests

Extend WatiRequest to create your API requests:

<?php

use Wati\Http\WatiRequest;
use GuzzleHttp\Psr7\Utils;

class GetContactsRequest extends WatiRequest
{
    public function __construct(int $page = 1, int $pageSize = 50)
    {
        parent::__construct(
            'GET',
            "/api/v1/getContacts?page={$page}&pageSize={$pageSize}",
            ['Accept' => 'application/json']
        );
    }
}

class SendTemplateMessageRequest extends WatiRequest
{
    public function __construct(string $phoneNumber, string $templateName, array $parameters = [])
    {
        $body = json_encode([
            'template_name' => $templateName,
            'broadcast_name' => $templateName,
            'parameters' => $parameters,
        ]);

        parent::__construct(
            'POST',
            "/api/v1/sendTemplateMessage?whatsappNumber={$phoneNumber}",
            [
                'Accept' => 'application/json',
                'Content-Type' => 'application/json',
            ],
            Utils::streamFor($body)
        );
    }
}

Execute Requests

<?php

use GuzzleHttp\Utils;

// Get contacts
$response = $client->send(new GetContactsRequest());
$data = Utils::jsonDecode($response->getBody()->getContents(), true);

// Send a template message
$response = $client->send(new SendTemplateMessageRequest(
    '1234567890',
    'hello_world',
    ['name' => 'John']
));

API Reference

For full API documentation, visit Wati API Docs.

Available Endpoints

• Messaging: Send templates, session messages, interactive messages
• Contacts: Get, add, update contacts
• Conversations: Messages, status updates
• Templates: Get and send message templates
• Campaigns: Manage broadcasts

Error Handling

The client throws specific exceptions for different error scenarios:

<?php

use Wati\Http\Exceptions\AuthenticationException;
use Wati\Http\Exceptions\RateLimitException;
use Wati\Http\Exceptions\ValidationException;
use Wati\Http\Exceptions\WatiApiException;
use Wati\Http\Exceptions\WatiException;

try {
    $response = $client->send(new GetContactsRequest());
} catch (AuthenticationException $e) {
    // Invalid bearer token - check credentials
    echo "Auth failed: " . $e->getMessage();
} catch (RateLimitException $e) {
    // Rate limited - wait and retry
    $retryAfter = $e->getRetryAfter(); // seconds to wait
} catch (ValidationException $e) {
    // Invalid request parameters
    $errors = $e->getResponseData();
} catch (WatiApiException $e) {
    // Other API errors (4xx, 5xx)
    $statusCode = $e->getStatusCode();
    $data = $e->getResponseData();
} catch (WatiException $e) {
    // Connection or other HTTP errors
    echo "Request failed: " . $e->getMessage();
}

Changelog

Please see the CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security-related issues, please email the author instead of using the issue tracker.

License

Please see the License file.