Pular para o conteúdo

Cliente PHP

Um cliente PHP da API, gerado da especificação OpenAPI com o OpenAPI Generator sobre Guzzle: instalação, envio, erros e webhooks.

Ver em Markdown

O cliente PHP é gerado da especificação OpenAPI 3.1 a cada mudança da API, sem código escrito à mão, pelo OpenAPI Generator (gerador php, sobre o Guzzle). Há uma classe por grupo da referência, com um método por operação batizado pelo operationId (sendMessage, getQueue, createApiKey…), e um modelo por corpo de requisição, de resposta e de evento de webhook.

O que o pacote traz

ParteO que é
WhatsappGateway\Client\Api\*ApiUma classe por grupo da referência: ConnectionsApi, MessagesApi, ContactsApi, TemplatesApi, MediaApi, TenantsApi (projetos), APIKeysApi (chaves de API), UsageApi (uso), LogsApi (registros) e AccountApi (conta)
WhatsappGateway\Client\Model\*Os modelos: SendMessageRequest, SendMessage202Response, ErrorResponse, os eventos de webhook (MessageIncomingEvent…) e os demais, nomeados pelo operationId e pelo status (GetQueue200Response)
ConfigurationO endereço da API (setHost) e a chave (setAccessToken)
ApiExceptionA exceção de toda resposta fora de 2xx e de toda falha de rede
ObjectSerializerConverte o JSON recebido num modelo, como o data de um evento de webhook

O pacote exige PHP 8.1 ou mais novo, com as extensões curl, json e mbstring, e depende do guzzlehttp/guzzle ^7.3.

Os campos dos modelos seguem o padrão do PHP (client_ref, typing_delay, file_name), com getters e setters (getJobId(), setClientRef()); no JSON enviado e recebido eles voltam ao nome da API (clientRef, typingDelay, fileName). Um valor de enumeração que o cliente ainda não conhece, como um status novo, é lido como unknown_default_open_api em vez de gerar erro: a API só cresce de forma compatível (veja Novidades).

1Instale

Com o pacote recebido do suporte (a pasta whatsapp-gateway-php), aponte o Composer para ela como um repositório local e instale:

bashPacote pronto
composer config repositories.whatsapp-gateway path ./whatsapp-gateway-php
composer require costasoftware/whatsapp-gateway-client:1.0.0

Para gerar você mesmo, crie o arquivo de opções do gerador, o mesmo com que o pacote é gerado:

yamlopenapi-generator.yaml
invokerPackage: 'WhatsappGateway\Client'
composerPackageName: costasoftware/whatsapp-gateway-client
artifactVersion: 1.0.0
licenseName: proprietary
enumUnknownDefaultCase: true
hideGenerationTimestamp: true

Depois baixe a especificação publicada nesta documentação, tire dela a seção de webhooks (o gerador a transformaria em chamadas que não existem; os modelos dos eventos continuam em components.schemas) e rode o gerador com Docker:

bashGerar o pacote
curl -s https://apiwpp.com/docs/openapi.json | jq 'del(.webhooks)' > openapi.api.json
docker run --rm -u "$(id -u):$(id -g)" -v "$PWD:/local" openapitools/openapi-generator-cli:v7.25.0 generate \
  -g php -c /local/openapi-generator.yaml \
  -i /local/openapi.api.json -o /local/whatsapp-gateway-php

O pacote sai na pasta whatsapp-gateway-php; instale-o com os dois comandos do pacote pronto. Quando a API mudar, gere de novo: as operações e os campos novos aparecem como métodos e getters novos.

2Configure o cliente

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

use GuzzleHttp\Client as HttpClient;
use WhatsappGateway\Client\Api\MessagesApi;
use WhatsappGateway\Client\Configuration;

$config = (new Configuration())
    ->setHost('https://api.apiwpp.com')
    ->setAccessToken(getenv('WHATSAPP_API_KEY'));

$http = new HttpClient(['timeout' => 30]);
$messages = new MessagesApi($http, $config);

Com setAccessToken, toda requisição sai com Authorization: Bearer <chave>. Guarde a chave num cofre de segredos ou numa variável de ambiente, nunca no código, e dê a ela só os escopos das operações que o seu sistema chama (veja Autenticação). O mesmo $http e o mesmo $config servem para todas as classes *Api.

Para conferir a chave, chame GET /me:

phpVer na referência
<?php
require __DIR__ . '/gateway.php';

use WhatsappGateway\Client\Api\AccountApi;

$caller = (new AccountApi($http, $config))->getCaller();

echo $caller->getKind(), PHP_EOL;                  // "apiKey"
echo implode(', ', $caller->getScopes()), PHP_EOL; // os escopos da chave

3Envie uma mensagem

Os parâmetros de caminho são os primeiros argumentos do método, e o corpo é o modelo da requisição, montado com um array de campos em snake_case:

phpVer na referência
<?php
require __DIR__ . '/gateway.php';

use WhatsappGateway\Client\Model\SendMessage200Response;
use WhatsappGateway\Client\Model\SendMessageRequest;

$connectionId = getenv('WHATSAPP_CONNECTION_ID');

$job = $messages->sendMessage($connectionId, new SendMessageRequest([
    'to' => '5511988887777',
    'message' => 'Olá! Seu pedido 1234 saiu para entrega.',
    'client_ref' => 'pedido-1234',
]));

if ($job instanceof SendMessage200Response && $job->getDuplicate()) {
    // 200: um envio anterior com o mesmo clientRef já tinha enfileirado esta mensagem
    echo 'Já estava na fila: ', $job->getJobId(), PHP_EOL;
} else {
    // 202: enfileirada agora
    echo 'Na fila: ', $job->getJobId(), ' posição ', $job->getPosition(), PHP_EOL;
}

O que o cliente envia é exatamente esta requisição:

bashA mesma requisição em cURL
curl -s -X POST "https://api.apiwpp.com/connections/$CONNECTION_ID/send" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "5511988887777", "message": "Olá! Seu pedido 1234 saiu para entrega.", "clientRef": "pedido-1234"}'

A resposta 202 (SendMessage202Response) traz o jobId, o scheduledAt (milissegundos unix do envio previsto) e a position na fila do número. Repetir a mesma requisição com o mesmo client_ref responde 200 (SendMessage200Response) com duplicate: true e o job original, sem enfileirar de novo: é assim que um envio pode ser repetido com segurança depois de uma falha de rede (veja Idempotência).

Os objetos aninhados têm modelos próprios, como a mídia (SendMessageRequestMedia) e a localização (SendMessageRequestLocation). Para ler também o status e os cabeçalhos da resposta, use a variante …WithHttpInfo do método, que devolve [modelo, status, cabeçalhos]. Aqui, um documento, com o aviso de cota do cabeçalho X-Usage-Warning:

phpVer na referência
<?php
require __DIR__ . '/gateway.php';

use WhatsappGateway\Client\Model\SendMessageRequest;
use WhatsappGateway\Client\Model\SendMessageRequestMedia;

$connectionId = getenv('WHATSAPP_CONNECTION_ID');

[$job, $status, $headers] = $messages->sendMessageWithHttpInfo($connectionId, new SendMessageRequest([
    'to' => '5511988887777',
    'media' => new SendMessageRequestMedia([
        'type' => 'document',
        'url' => 'https://files.example.com/boletos/1234.pdf',
        'file_name' => 'boleto-1234.pdf',
        'mimetype' => 'application/pdf',
        'caption' => 'Seu boleto',
    ]),
    'client_ref' => 'boleto-1234',
]));

$headers = array_change_key_case($headers, CASE_LOWER);
if (isset($headers['x-usage-warning'])) {
    error_log('Cota de mensagens perto do fim: ' . $headers['x-usage-warning'][0]);
}

X-Usage-Warning vem nos envios aceitos a partir de 80% da cota do plano (veja Cabeçalhos). Todo método também tem as variantes …Async e …AsyncWithHttpInfo, que devolvem uma promise do Guzzle. O guia de envio mostra os demais tipos de mensagem: localização, templates e o typing_delay.

4Trate os erros

Toda resposta fora de 2xx lança ApiException. O getCode() é o status HTTP, o getResponseObject() é o corpo de erro já convertido num modelo (getError() sempre, e às vezes getMessage(), getStatusCode(), getCode() e getFeature()), e o getResponseHeaders() traz os cabeçalhos, como o Retry-After. Uma falha de rede (DNS, conexão recusada, timeout) também lança ApiException, com getCode() igual a 0 e sem corpo.

Decida pelo status e pelo code, nunca pelo texto de error, que é para pessoas e pode mudar:

phpTratar os erros
<?php
require __DIR__ . '/gateway.php';

use WhatsappGateway\Client\ApiException;
use WhatsappGateway\Client\Model\SendMessageRequest;

final class RetryLater extends RuntimeException
{
    public function __construct(public readonly int $seconds)
    {
        parent::__construct("Tente de novo em {$seconds} s");
    }
}

/** Um cabeçalho da resposta, sem depender de maiúsculas e minúsculas */
function responseHeader(ApiException $e, string $name): ?string
{
    $headers = array_change_key_case($e->getResponseHeaders() ?? [], CASE_LOWER);
    return $headers[strtolower($name)][0] ?? null;
}

$connectionId = getenv('WHATSAPP_CONNECTION_ID');

try {
    $job = $messages->sendMessage($connectionId, new SendMessageRequest([
        'to' => '5511988887777',
        'message' => 'Olá!',
        'client_ref' => 'pedido-1234',
    ]));
} catch (ApiException $e) {
    $status = $e->getCode(); // 0 quando a requisição nem chegou à API
    $error = $e->getResponseObject(); // o corpo de erro convertido, ou null
    $code = $error?->getCode(); // subscription_inactive, plan_feature_required…

    switch ($status) {
        case 0:
        case 429:
        case 503:
            // Espere o Retry-After e repita com o mesmo client_ref: não duplica
            throw new RetryLater((int) (responseHeader($e, 'Retry-After') ?? 60));
        case 402: // code: subscription_inactive
            throw new RuntimeException('A assinatura da organização não está em dia', 0, $e);
        default:
            // 400: corpo inválido, destinatário inválido ou conexão que não está aberta
            // 401: chave ausente, desconhecida, revogada ou expirada
            // 403: falta um escopo, ou o plano não inclui o recurso (plan_feature_required)
            throw new RuntimeException("{$status}: " . ($error?->getError() ?? $e->getMessage()), 0, $e);
    }
}

RetryLater aqui é uma classe sua, que agenda a nova tentativa. No 429 de POST /connections/{id}/send, o cabeçalho X-Usage-Percent diz quanto da cota do plano já foi usado, e o error new_recipient_cap_reached diz que o número atingiu o limite de destinatários novos do dia (veja Limites de envio). A tabela completa de status e códigos está em Códigos de erro.

5Receba os webhooks com modelos

Os eventos de webhook estão na mesma especificação, e o pacote traz um modelo para o data de cada tipo: MessageIncomingEvent, MessageDeliveryEvent, ConnectionStatusEvent e os demais. Verifique a assinatura sobre o corpo bruto antes de converter o JSON, como no guia Webhooks e assinatura, e depois converta o data com o ObjectSerializer:

phpReceber eventos
<?php
require __DIR__ . '/vendor/autoload.php';

use WhatsappGateway\Client\Model\MessageDeliveryEvent;
use WhatsappGateway\Client\Model\MessageIncomingEvent;
use WhatsappGateway\Client\ObjectSerializer;

$secret = getenv('WHATSAPP_WEBHOOK_SECRET');
if (!is_string($secret) || $secret === '') {
    // Sem segredo não há o que verificar: recuse tudo até configurá-lo
    http_response_code(500);
    exit;
}

$rawBody = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_SALES_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_SALES_SIGNATURE'] ?? '';

$fresh = ctype_digit($timestamp) && abs(time() - (int) $timestamp) <= 300;
$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);

if (!$fresh || !hash_equals($expected, $signature)) {
    http_response_code(401);
    exit;
}

$event = json_decode($rawBody);

switch ($event->type ?? null) {
    case 'message.incoming':
        /** @var MessageIncomingEvent $data */
        $data = ObjectSerializer::deserialize($event->data, MessageIncomingEvent::class);
        error_log(($data->getPhone() ?? $data->getJid()) . ' escreveu: ' . $data->getBody());
        break;
    case 'message.delivery':
        /** @var MessageDeliveryEvent $data */
        $data = ObjectSerializer::deserialize($event->data, MessageDeliveryEvent::class);
        error_log($data->getMessageId() . ' ' . $data->getStatus());
        break;
    default:
        // ping e tipos novos: ignore o que você não conhece
        break;
}

// Em produção, enfileire o evento e responda logo: o limite é de 10 segundos
http_response_code(204);

A entrega é pelo menos uma vez: o mesmo evento pode chegar de novo, então aplique cada um de forma idempotente (por data.messageId, quando houver). Em Laravel, o segredo vem de config(...), não de getenv() (veja a observação no guia de webhooks). A lista dos eventos e dos campos de cada um está em Webhooks.

Próximos passos

Esta página ajudou? · Atualizado em 29 set 2026