# Cliente PHP

Fonte: https://apiwpp.com/docs/clientes/php
Seção: Clientes
Atualizado em: 2026-09-29

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

O cliente PHP é gerado da [especificação OpenAPI 3.1](https://apiwpp.com/docs/api) a cada mudança da API, sem código escrito à mão, pelo [OpenAPI Generator](https://openapi-generator.tech/) (gerador `php`, sobre o [Guzzle](https://docs.guzzlephp.org/)). 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.

> **Ainda não está no Packagist**
>
> O pacote `costasoftware/whatsapp-gateway-client` ainda não foi publicado no Packagist nem em outro registro de pacotes. Há dois caminhos: pedir o pacote pronto pelo suporte, ou gerá-lo você mesmo a partir da especificação, como no passo 1. O resultado é o mesmo código.

## O que o pacote traz

| Parte | O que é |
| --- | --- |
| `WhatsappGateway\Client\Api\*Api` | Uma 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`) |
| `Configuration` | O endereço da API (`setHost`) e a chave (`setAccessToken`) |
| `ApiException` | A exceção de toda resposta fora de `2xx` e de toda falha de rede |
| `ObjectSerializer` | Converte 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](https://apiwpp.com/docs/novidades)).

## 1. Instale

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

**Pacote pronto**

```bash
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:

**openapi-generator.yaml**

```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](https://apiwpp.com/docs/openapi.json), 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:

**Gerar o pacote**

```bash
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.

## 2. Configure o cliente

**gateway.php**

```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](https://apiwpp.com/docs/referencia/escopos) das operações que o seu sistema chama (veja [Autenticação](https://apiwpp.com/docs/autenticacao)). O mesmo `$http` e o mesmo `$config` servem para todas as classes `*Api`.

Para conferir a chave, chame [`GET /me`](https://apiwpp.com/docs/api/conta/quem-esta-chamando):

**Confira a chave**

```php
<?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
```

## 3. Envie 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`:

**Enviar mensagem**

```php
<?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:

**A mesma requisição em cURL**

```bash
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](https://apiwpp.com/docs/guias/idempotencia)).

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`:

**Enviar um documento**

```php
<?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](https://apiwpp.com/docs/referencia/cabecalhos)). Todo método também tem as variantes `…Async` e `…AsyncWithHttpInfo`, que devolvem uma promise do Guzzle. O [guia de envio](https://apiwpp.com/docs/guias/enviar-mensagens) mostra os demais tipos de mensagem: localização, templates e o `typing_delay`.

## 4. Trate os erros

Toda resposta fora de `2xx` lança `ApiException`. O `getCode()` é o status HTTP, o `getResponseObject()` é o [corpo de erro](https://apiwpp.com/docs/guias/erros) 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:

**Tratar os erros**

```php
<?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](https://apiwpp.com/docs/guias/limites-de-envio)). A tabela completa de status e códigos está em [Códigos de erro](https://apiwpp.com/docs/referencia/codigos-de-erro).

> **Não desligue as exceções do Guzzle**
>
> O cliente conta com o comportamento padrão do Guzzle, que transforma as respostas `4xx` e `5xx` em exceção. Não crie o `HttpClient` com `'http_errors' => false`: sem a exceção, um erro deixa de chegar ao seu `catch`.

## 5. Receba 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](https://apiwpp.com/docs/guias/webhooks-e-assinatura#verifique-a-assinatura), e depois converta o `data` com o `ObjectSerializer`:

**Receber eventos**

```php
<?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);
```

> **O ping não tem modelo**
>
> O evento [`ping`](https://apiwpp.com/docs/webhooks/ping), enviado só pelo teste do endpoint, não faz parte da especificação: não há modelo para ele, e o seu `connectionId` e `tenantId` vêm `null`. Por isso o exemplo lê `type` do JSON antes de escolher o modelo. Ignore os tipos que você não conhece e responda `2xx`: a API pode ganhar eventos novos.

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](https://apiwpp.com/docs/guias/webhooks-e-assinatura#verifique-a-assinatura)). A lista dos eventos e dos campos de cada um está em [Webhooks](https://apiwpp.com/docs/webhooks).

## Próximos passos

- [Enviar mensagens](https://apiwpp.com/docs/guias/enviar-mensagens): texto, mídia, localização, templates e a fila do número.
- [Webhooks e assinatura](https://apiwpp.com/docs/guias/webhooks-e-assinatura): o endpoint, a assinatura e as novas tentativas.
- [Visão geral da API](https://apiwpp.com/docs/api): todas as operações que o cliente pode chamar.
- [Cliente TypeScript](https://apiwpp.com/docs/clientes/typescript): o mesmo, gerado para TypeScript.
