Pular para o conteúdo
apiwpp
Integração

API de WhatsApp para PHP: envio com curl ou Guzzle e webhook assinado

Envie mensagens de WhatsApp em PHP com curl, Guzzle ou o cliente gerado da OpenAPI, e receba webhooks verificando a assinatura com hash_hmac.

Atualizado em

A apiwpp é uma API REST com JSON, então qualquer PHP que faça uma requisição HTTPS consegue enviar mensagens de WhatsApp: a extensão curl, o Guzzle ou o cliente gerado da especificação OpenAPI. Para receber mensagens e confirmações de entrega, basta um script que responda a um POST. Esta página mostra os três jeitos de enviar e um webhook em PHP puro, sem framework. Se o seu projeto é em Laravel, a página de integração com Laravel usa os recursos do framework.

O que você precisa

Enviar com curl, sem dependências

POST /connections/{id}/send coloca a mensagem na fila do número e responde 202 com o jobId, o horário previsto (scheduledAt, em milissegundos unix) e a posição na fila. Com a extensão curl, o cabeçalho Retry-After é lido por uma função de cabeçalhos:

<?php

function apiwpp_send(array $payload): array
{
    $connectionId = getenv('APIWPP_CONNECTION_ID');
    $retryAfter = null;

    $ch = curl_init("https://api.apiwpp.com/connections/{$connectionId}/send");
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR),
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 15,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . getenv('APIWPP_KEY'),
            'Content-Type: application/json',
            'Accept: application/json',
        ],
        CURLOPT_HEADERFUNCTION => function ($ch, string $line) use (&$retryAfter): int {
            if (stripos($line, 'retry-after:') === 0) {
                $retryAfter = (int) trim(substr($line, strlen('retry-after:')));
            }
            return strlen($line);
        },
    ]);

    $body = curl_exec($ch);
    if ($body === false) {
        throw new RuntimeException('apiwpp: ' . curl_error($ch)); // timeout: retry with the same clientRef
    }

    return [
        'status' => curl_getinfo($ch, CURLINFO_RESPONSE_CODE),
        'body' => json_decode($body, true) ?? [],
        'retryAfter' => $retryAfter,
    ];
}

$result = apiwpp_send([
    'to' => '5511988887777',
    'message' => 'Olá, Ana! Seu pedido 1234 saiu para entrega.',
    'clientRef' => 'pedido-1234-envio',
]);
// 202: ['jobId' => '…', 'scheduledAt' => 1790251205000, 'position' => 1]

O campo to leva só dígitos, com país e DDD. A apiwpp consulta em qual endereço o número está registrado no WhatsApp, então contas antigas sem o nono dígito também recebem. Para mídia, troque message por media, com type, url (https pública) e, num documento, mimetype.

Enviar com Guzzle

Com o Guzzle, as respostas 4xx viram exceções, e o Retry-After vem da resposta anexada a elas:

<?php

use GuzzleHttp\Client;
use GuzzleHttp\Exception\ClientException;

$http = new Client(['base_uri' => 'https://api.apiwpp.com', 'timeout' => 15]);
$connectionId = getenv('APIWPP_CONNECTION_ID');

try {
    $response = $http->post("/connections/{$connectionId}/send", [
        'headers' => ['Authorization' => 'Bearer ' . getenv('APIWPP_KEY')],
        'json' => [
            'to' => '5511988887777',
            'message' => 'Olá, Ana! Seu pedido 1234 saiu para entrega.',
            'clientRef' => 'pedido-1234-envio',
        ],
    ]);
    $job = json_decode((string) $response->getBody(), true); // 202, or 200 with duplicate: true
} catch (ClientException $e) {
    $response = $e->getResponse();
    if ($response->getStatusCode() === 429) {
        $wait = (int) ($response->getHeaderLine('Retry-After') ?: 60);
        // schedule a new attempt in $wait seconds
    } else {
        throw $e; // 400, 401, 403: fix the request, retrying will not help
    }
}

O 429 com o código new_recipient_cap_reached é o teto de destinatários novos que um número alcança em 24 horas, uma das proteções da fila com ritmo anti-bloqueio. Nada entra na fila nesse caso.

Repetir sem duplicar com clientRef

Um tempo esgotado não diz se a API aceitou o envio. Por isso, repita sempre com o mesmo clientRef: a repetição responde 200 com o job original e "duplicate": true, sem enfileirar nada. O valor tem até 200 caracteres, fica reservado por 7 dias e volta nos eventos message.delivery e message.send_failed. Derive-o do que o envio representa (pedido-1234-envio), nunca de uniqid() ou de um número aleatório gerado a cada tentativa.

O cliente PHP gerado

Se você prefere métodos e modelos a montar arrays, há um cliente gerado da especificação OpenAPI 3.1 com o OpenAPI Generator, sobre Guzzle. Ele ainda não está no Packagist: peça o pacote pronto pelo suporte ou gere o seu. A seção de webhooks sai da especificação antes de gerar, porque o gerador a transformaria em chamadas que não existem:

jq 'del(.webhooks)' openapi.json > openapi.api.json
docker run --rm -v "$PWD:/local" openapitools/openapi-generator-cli:v7.25.0 generate \
  -i /local/openapi.api.json -g php -o /local/apiwpp-php \
  --additional-properties=invokerPackage='Apiwpp\Client'

O openapi.json é a especificação publicada na documentação. O pacote traz uma classe por grupo da referência (MessagesApi, ConnectionsApi…) e um modelo por corpo. Os campos dos modelos seguem o padrão do PHP, client_ref, e voltam ao nome da API, clientRef, no JSON enviado:

<?php

use Apiwpp\Client\Api\MessagesApi;
use Apiwpp\Client\ApiException;
use Apiwpp\Client\Configuration;
use Apiwpp\Client\Model\SendMessageRequest;
use GuzzleHttp\Client as HttpClient;

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

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

try {
    $job = $messages->sendMessage(getenv('APIWPP_CONNECTION_ID'), new SendMessageRequest([
        'to' => '5511988887777',
        'message' => 'Olá, Ana! Seu pedido 1234 saiu para entrega.',
        'client_ref' => 'pedido-1234-envio',
    ]));
    echo $job->getJobId();
} catch (ApiException $e) {
    // $e->getCode() is the HTTP status; $e->getResponseBody() has the error JSON
}

A versão mínima do PHP é a que o composer.json gerado declara. A página de OpenAPI e clientes gerados resume os dois clientes.

Receber webhooks em PHP puro

Cada evento chega como um POST no endereço de webhook do projeto. Com o segredo definido, a entrega traz X-Sales-Timestamp (segundos unix) e X-Sales-Signature (sha256= seguido do HMAC-SHA256 de timestamp + "." + corpo bruto). Recuse timestamps a mais de 300 segundos e compare em tempo constante com hash_equals:

<?php
// webhook.php
$secret = getenv('APIWPP_WEBHOOK_SECRET');
if (!is_string($secret) || $secret === '') {
    http_response_code(500); // no secret, nothing to verify: refuse everything
    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, true);
enqueue($event); // your queue or a jobs table: process after answering
http_response_code(204);

Três cuidados. A assinatura é calculada sobre o corpo bruto: use php://input, nunca um json_encode refeito. Nunca verifique com um segredo vazio, porque qualquer pessoa calcularia esse HMAC. E responda 2xx em até 10 segundos: o trabalho pesado vai para uma fila.

A entrega é pelo menos uma vez, com até 6 tentativas quando o seu endpoint falha. Guarde o messageId dos eventos já processados (em message.delivery, junto com o status) e ignore os repetidos, assim como os tipos de evento que o seu código não conhece. Com o cliente gerado, ObjectSerializer::deserialize(json_decode($rawBody)->data, MessageIncomingEvent::class) preenche o modelo do evento. Os tipos de evento estão em webhooks assinados, e o HMAC tem um verbete no glossário.

Perguntas frequentes

Preciso de um framework para usar a API em PHP?

Não. A extensão curl basta para enviar, e um script que lê php://input basta para receber. O Guzzle e o cliente gerado deixam o código mais curto e tipado, e em Laravel o Http facade faz o mesmo papel.

O cliente PHP está no Packagist?

Ainda não. O cliente é gerado da especificação OpenAPI 3.1 a cada mudança da API, mas não está publicado em registros de pacotes. Peça o pacote pronto pelo suporte ou gere-o com o OpenAPI Generator, como mostra esta página.

Por que usar hash_equals e não uma comparação com ===?

Porque o === para no primeiro caractere diferente, e o tempo da resposta vaza quanto da assinatura estava certo. O hash_equals compara em tempo constante, o que impede esse ataque.

Por que o modelo usa client_ref e o JSON usa clientRef?

O OpenAPI Generator segue o padrão de nomes do PHP nos modelos. Na serialização, cada campo volta ao nome da especificação, então a API recebe clientRef normalmente.

Todos: Integrações →

Envie mensagens de WhatsApp a partir de Jobs do Laravel com o Http facade e clientRef, receba os eventos numa rota protegida por um middleware de assinatura HMAC e processe tudo na fila, sem duplicar.

Envie mensagens com o fetch nativo do Node.js, sem dependências, e receba os eventos num endpoint Express que verifica a assinatura HMAC-SHA256 de cada entrega.

Tipos gerados da especificação OpenAPI 3.1 com o openapi-typescript e chamadas pelo openapi-fetch: cada rota, corpo, resposta e evento de webhook tipado, sem código escrito à mão.

Conecte seu primeiro número hoje.

7 dias grátis, sem cartão de crédito.