SDK PHP: установка и методы

Установка

PHP 8.1 или новее, расширения cURL и JSON. Установка через Composer, автозагрузка PSR-4.

Команда устанавливает пакет из Packagist. API v1 одинаков для всех трёх SDK; инструкции в репозиториях доступны на русском.

composer require waix/waix-php:^0.2

Ключ и первый запрос

Ключ хранится на сервере. Для отправки нужен scope messages:write; для чтения — messages:read. Connection ID берётся из раздела WhatsApp. Подготовьте собственный одобренный шаблон с одной переменной или измените компоненты примера.

<?php
require 'vendor/autoload.php';

$waix = new Waix\Client(getenv('WAIX_API_KEY'));
// $eventId — UUID, уже сохранённый в записи заказа.
$result = $waix->messages->send([
    'connection_id' => getenv('WAIX_CONNECTION_ID'),
    'to' => '+77071234567', 'type' => 'template',
    'template' => [
        'name' => 'order_ready',
        'language' => ['code' => 'ru'],
        'components' => [[
            'type' => 'body',
            'parameters' => [['type' => 'text', 'text' => '42']]
        ]]
    ]
], $eventId);

UUID создаётся один раз для логической отправки и сохраняется до запроса. После тайм-аута повторяйте тот же запрос с тем же UUID; новый ключ означает новое сообщение. HTTP 202 подтверждает постановку в очередь, а не доставку.

Ошибки и тайм-аут

Исключение WaixError содержит status, errorCode, requestId, retryAfter. HTTP-статус 0 означает транспортную ошибку или тайм-аут. По request ID поддержка может найти запрос; ключи и полные тела сообщений в журнал писать не нужно.

Настройка тайм-аута: timeoutMs: 30000 — миллисекунды. По умолчанию 30 секунд. Автоматических повторов и переходов по редиректам нет. При 429 дождитесь Retry-After; ошибки 400, 401 и 403 сначала исправьте.

OTP: отправить, проверить, узнать статус

Нужен ключ OTP-проекта с соответствующими правами. В sandbox отправка возвращает test_code и не обращается к WhatsApp. Не передавайте test_code посетителю: проверка потеряет смысл.

$otp = new Waix\Client(getenv('WAIX_OTP_PROJECT_KEY'));
$sent = $otp->otp->send(['to' => '+77071234567', 'ttl' => 300], $eventId);
// Сохраните $sent['data']['id'] в сессии пользователя.
$status = $otp->otp->status($sent['data']['id']);
$result = $otp->otp->verify($sent['data']['id'], $suppliedCode);

Пример показывает отдельные этапы. suppliedCode / supplied_code / $suppliedCode — код из следующего запроса того же пользователя. Challenge ID хранится в его серверной сессии, а не принимается без проверки от любого посетителя. Успешная доставка кода ещё не означает успешную авторизацию.

Медиа и пагинация

$waix->media->upload($connectionId, '/path/invoice.pdf', 'application/pdf', ['type'=>'document'])

Укажите Connection ID, MIME-тип и вид медиа. Файлы должны соответствовать ограничениям API. Python загружает файл в память; для больших документов учитывайте доступную память процесса.

$waix->messages->list(['limit'=>50, 'before'=>$cursor, 'before_id'=>$cursorId])

Метод возвращает весь JSON-ответ. Для следующей страницы передайте одновременно pagination.next_before и pagination.next_before_id. Когда оба значения отсутствуют, список закончился.

Проверка вебхука

Waix\Webhook::verify($rawBody, $timestamp, $signature, $secret)

rawBody / raw_body — исходные байты HTTP-запроса до JSON-парсера. timestamp и signature — заголовки X-Waix-Timestamp и X-Waix-Signature. secret — секрет вашего вебхука или OTP-проекта.

Проверка сравнивает HMAC-SHA256 за постоянное время и допускает расхождение часов до 300 секунд. Неверная подпись или просроченное время дают false. После проверки сохраняйте X-Waix-Delivery и не обрабатывайте одно событие дважды.

SDK 0.2: журнал и диагностика

Во всех SDK появился messages.iterate: он читает журнал по страницам, сохраняет фильтры и переносит оба курсора. У Node.js это async iterator, у Python и PHP — generator. Полный журнал не нужно загружать в память.

По умолчанию ответ ограничен 2 МиБ. Ошибки HTTP сохраняют статус, request ID и Retry-After, даже если прокси вернул HTML. Повторный курсор и превышение заданного количества страниц останавливают обход с понятной ошибкой.

Для журналирования используйте error.toJSON() в Node.js, error.to_dict() в Python или json_encode($error) в PHP. Эти методы исключают тело ответа, которое может содержать данные клиента. Полные примеры и настройки лимитов приведены в README пакета.

Остальные методы

SDK поддерживают чтение и обновление профиля номера, создание и редактирование шаблонов, preview, удаление медиа, настройку вебхука и смену его секрета. Названия методов и полные сигнатуры приведены в README пакета. Для новых методов API v1 есть общий request с относительным путём.

Часть методов управления требует более широких прав. OTP-ключ проекта не может изменять общий вебхук компании. Не расширяйте права рабочего ключа только ради отладки: создайте отдельный ключ для нужной операции.