Cliente PHP
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 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
| 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).
1Instale
Com o pacote recebido do suporte (a pasta whatsapp-gateway-php), aponte o Composer para ela como um repositório local e instale:
composer config repositories.whatsapp-gateway path ./whatsapp-gateway-php
composer require costasoftware/whatsapp-gateway-client:1.0.0Para gerar você mesmo, crie o arquivo de opções do gerador, o mesmo com que o pacote é gerado:
invokerPackage: 'WhatsappGateway\Client'
composerPackageName: costasoftware/whatsapp-gateway-client
artifactVersion: 1.0.0
licenseName: proprietary
enumUnknownDefaultCase: true
hideGenerationTimestamp: trueDepois 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:
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-phpO 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
<?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:
<?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 chave3Envie 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:
<?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:
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:
<?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:
<?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:
<?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
- Enviar mensagens: texto, mídia, localização, templates e a fila do número.
- Webhooks e assinatura: o endpoint, a assinatura e as novas tentativas.
- Visão geral da API: todas as operações que o cliente pode chamar.
- Cliente TypeScript: o mesmo, gerado para TypeScript.