Integração do WhatsApp com PHP e Laravel
Envie mensagens de WhatsApp pelo Laravel com o Http facade e Jobs, receba webhooks com assinatura HMAC e processe eventos em fila sem duplicar.
Mandar uma mensagem de WhatsApp a partir do Laravel parece coisa de três linhas, e o primeiro envio realmente é. O trabalho aparece depois: o pedido que dispara a confirmação roda dentro de um Job que pode ser executado de novo, a requisição cai por tempo esgotado sem dizer se a mensagem entrou, e o webhook que traz a resposta do cliente chega duas vezes ou é bloqueado pelo CSRF antes de chegar ao seu código.
Este tutorial mostra a integração que aguenta produção: o envio com o Http facade e com o cliente PHP gerado da especificação, o envio a partir de um Job com clientRef para que uma retentativa nunca duplique a mensagem, a rota de webhook com um middleware que confere a assinatura HMAC e o processamento dos eventos em fila, de forma idempotente. No final, o mesmo envio e a mesma verificação em PHP puro, com curl, para quem não usa framework.
Os exemplos usam Laravel 11 ou mais recente, mas quase tudo vale para as versões anteriores; onde muda, o texto avisa.
O que você precisa antes de começar
- Uma conta na apiwpp. O teste de 7 dias libera 1 número com os recursos do plano PRO, sem cartão.
- Um número conectado ao projeto, por QR code ou pelo código de pareamento de 8 caracteres. A conexão precisa estar com o status
openpara enviar. - Uma chave de API do projeto com o escopo
messages:send. A chave aparece uma única vez no painel: guarde-a no cofre de segredos, nunca no código. - Um segredo de webhook definido no projeto, para que cada entrega chegue assinada.
Coloque os valores no .env e exponha-os em config/services.php. Isso importa mais do que parece: com php artisan config:cache, o Laravel deixa de ler o .env em tempo de execução, e env() ou getenv() fora dos arquivos de configuração devolvem null ou false.
# .env
APIWPP_URL=https://api.apiwpp.com
APIWPP_KEY=wag_live_...
APIWPP_CONNECTION_ID=8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f
APIWPP_WEBHOOK_SECRET=cole-aqui-o-segredo-do-projeto
// config/services.php
'apiwpp' => [
'url' => env('APIWPP_URL', 'https://api.apiwpp.com'),
'key' => env('APIWPP_KEY'),
'connection_id' => env('APIWPP_CONNECTION_ID'),
'webhook_secret' => env('APIWPP_WEBHOOK_SECRET'),
],
Enviar uma mensagem com o Http facade
A rota de envio é POST /connections/{id}/send. Ela não envia na hora: 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. A fila envia no ritmo que protege o número, e o resultado chega depois pelos webhooks.
use Illuminate\Support\Facades\Http;
$response = Http::withToken(config('services.apiwpp.key'))
->acceptJson()
->timeout(15)
->post(config('services.apiwpp.url').'/connections/'.config('services.apiwpp.connection_id').'/send', [
'to' => '5511988887777',
'message' => 'Olá, Ana! Seu pedido 1234 saiu para entrega.',
'clientRef' => 'pedido-1234-envio',
]);
$response->status(); // 202
$response->json(); // ['jobId' => '…', 'scheduledAt' => 1790251205000, 'position' => 1]
É o mesmo código da aba PHP da página inicial, com a configuração tirada do lugar certo. Três detalhes do corpo:
toleva só dígitos, com país e DDD. A apiwpp pergunta ao WhatsApp em qual endereço o número está registrado, então contas antigas sem o nono dígito também recebem. O assunto tem um guia próprio sobre o nono dígito.messageé o texto. Antes dele, o destinatário vê "digitando…" por 1,5 segundo, o padrão do campotypingDelay.clientRefé o seu identificador do envio, com até 200 caracteres. É ele que torna a chamada segura para repetir, como mostra a próxima seção.
Para mídia, troque message por media, com type, url (https pública) e, num documento, mimetype. O envio de mídia cobre cada tipo.
Os erros que você precisa tratar
A API responde um JSON com pelo menos o campo error. Decida pelo status HTTP, nunca pelo texto:
| Status | O que significa | O que fazer |
|---|---|---|
202 | A mensagem entrou na fila | Guarde o jobId |
200 com duplicate: true | Esse clientRef já foi aceito antes; nada novo foi enfileirado | Trate como sucesso |
400 | Corpo inválido, destinatário inválido ou conexão fora do status open | Corrija; repetir não resolve |
401 e 403 | Chave inválida, revogada ou sem o escopo messages:send | Confira a chave |
429 | Limite de requisições ou teto de destinatários novos do número | Espere o Retry-After |
5xx ou tempo esgotado | Falha temporária | Repita com espera crescente, com o mesmo clientRef |
O 429 com new_recipient_cap_reached é o teto de pessoas novas que um número pode alcançar em 24 horas, uma das proteções da fila anti-bloqueio. Nada entra na fila nesse caso, então o seu sistema decide quando tentar de novo.
O mesmo envio com o cliente PHP gerado
Se você prefere métodos e modelos tipados a montar arrays, a apiwpp publica a especificação OpenAPI 3.1, e dela sai um cliente PHP feito com o OpenAPI Generator, sobre Guzzle. Os clientes ainda não estão no Packagist: peça o pacote pronto ao suporte ou gere o seu. O detalhe de cada cliente está em OpenAPI e SDKs.
Para gerar, remova a seção de webhooks da especificação (o gerador a transformaria em chamadas que não existem) e escolha o namespace em invokerPackage:
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'
Os campos dos modelos seguem o padrão do PHP (client_ref) e voltam ao nome da API (clientRef) no JSON enviado:
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(config('services.apiwpp.url'))
->setAccessToken(config('services.apiwpp.key'));
$messages = new MessagesApi(new HttpClient(['timeout' => 15]), $config);
try {
$job = $messages->sendMessage(config('services.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() é o status HTTP; $e->getResponseBody() traz o JSON do erro
report($e);
}
No Laravel, registre o MessagesApi como singleton num service provider e injete-o onde precisar. O resto deste tutorial usa o Http facade, porque ele dispensa dependências e facilita os testes.
Enviar a partir de um Job sem duplicar mensagens
Em produção, o envio não deve ficar na requisição do usuário. O lugar dele é um Job: o controller que confirma o pedido despacha, e o worker da fila chama a API. O risco é que o Laravel repete um Job que falhou, e uma falha depois de a apiwpp ter aceitado o envio (um tempo esgotado na resposta, um worker reiniciado) mandaria a mesma mensagem duas vezes.
O clientRef resolve isso. A primeira requisição com um clientRef enfileira a mensagem e responde 202. Qualquer repetição com o mesmo valor, na mesma conexão, responde 200 com o job original e "duplicate": true, sem enfileirar nada. A reserva vale por 7 dias. Por isso o clientRef precisa ser estável: derive-o do que o envio representa, como o id do pedido somado ao tipo do aviso, nunca de um valor aleatório gerado dentro do handle().
<?php
namespace App\Jobs;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;
use Illuminate\Support\Facades\Http;
use RuntimeException;
class SendWhatsAppMessage implements ShouldQueue
{
use Queueable;
public int $tries = 6;
public function __construct(
public string $to,
public string $message,
public string $clientRef, // ex.: "pedido-1234-envio"
) {}
/** Espera entre as tentativas, em segundos. */
public function backoff(): array
{
return [5, 15, 60, 300, 900];
}
public function handle(): void
{
// Um tempo esgotado lança ConnectionException e o Job é repetido:
// não sabemos se a mensagem entrou, mas o mesmo clientRef torna a repetição segura.
$response = Http::withToken(config('services.apiwpp.key'))
->acceptJson()
->timeout(15)
->post(config('services.apiwpp.url').'/connections/'.config('services.apiwpp.connection_id').'/send', [
'to' => $this->to,
'message' => $this->message,
'clientRef' => $this->clientRef,
]);
if ($response->successful()) {
return; // 202 (enfileirado) ou 200 com duplicate: true (já estava)
}
if ($response->status() === 429) {
$this->release((int) ($response->header('Retry-After') ?: 60));
return;
}
if ($response->serverError()) {
$response->throw(); // 5xx: nova tentativa com o backoff acima
}
// 4xx: repetir não resolve
$this->fail(new RuntimeException('apiwpp '.$response->status().': '.$response->json('error')));
}
}
E o despacho, no ponto do seu sistema em que o pedido sai para entrega:
SendWhatsAppMessage::dispatch(
to: $order->customer_phone,
message: "Olá, {$order->customer_name}! Seu pedido {$order->number} saiu para entrega.",
clientRef: "pedido-{$order->id}-envio",
);
Duas observações. Um release() conta como tentativa, então ajuste $tries se o seu volume esbarra com frequência no teto de destinatários novos. E, se for de propósito mandar a mesma mensagem de novo (o cliente pediu para reenviar o código de rastreio, por exemplo), use outro clientRef, como pedido-1234-envio-2: repetir o antigo só devolveria duplicate. O guia sobre mensagens duplicadas aprofunda o assunto.
Receber webhooks no Laravel
A apiwpp envia um POST para o endereço de webhook do projeto a cada evento: mensagem recebida (message.incoming), mudança de status de uma mensagem enviada (message.delivery), envio que não vai acontecer (message.send_failed), mudança da conexão (connection.status) e os demais listados em webhooks. Todos chegam no mesmo envelope:
{
"type": "message.delivery",
"connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
"tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
"externalId": "shop-42",
"timestamp": "2026-09-25T12:00:02.000Z",
"data": {
"messageId": "3EB0C767D26A1D8A3F52",
"status": "delivered",
"clientRef": "pedido-1234-envio",
"jid": "[email protected]",
"phone": "+5511988887777"
}
}
O endereço precisa ser https público e responder direto: redirecionamentos não são seguidos. Responda 2xx em até 10 segundos; qualquer outra resposta conta como falha e gera novas tentativas.
O middleware que confere a assinatura
Com o segredo definido no projeto, cada entrega traz dois cabeçalhos: X-Sales-Timestamp, com os segundos unix da tentativa, e X-Sales-Signature, com sha256= seguido do HMAC-SHA256 de timestamp + "." + corpo bruto. Para aceitar o evento, recuse timestamps a mais de 300 segundos do seu relógio e compare a assinatura em tempo constante. O que é HMAC e por que a comparação em tempo constante importa estão no glossário.
<?php
namespace App\Http\Middleware;
use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;
class VerifyApiwppSignature
{
public function handle(Request $request, Closure $next): Response
{
$secret = config('services.apiwpp.webhook_secret');
// Sem segredo não há o que verificar: recuse tudo até configurá-lo.
if (! is_string($secret) || $secret === '') {
abort(500, 'APIWPP_WEBHOOK_SECRET não está configurado');
}
$timestamp = (string) $request->header('X-Sales-Timestamp', '');
$signature = (string) $request->header('X-Sales-Signature', '');
$fresh = ctype_digit($timestamp) && abs(time() - (int) $timestamp) <= 300;
$expected = 'sha256='.hash_hmac('sha256', $timestamp.'.'.$request->getContent(), $secret);
if (! $fresh || ! hash_equals($expected, $signature)) {
abort(401);
}
return $next($request);
}
}
O ponto que mais derruba integrações: a assinatura é calculada sobre o corpo bruto, os bytes exatamente como chegaram. $request->getContent() entrega isso. Nunca assine de novo json_encode($request->all()): a serialização muda e a assinatura deixa de conferir.
A rota, fora do CSRF
Uma rota em routes/web.php passa pelo middleware de CSRF, e a apiwpp não tem como enviar o token do formulário. Registre a rota e tire o caminho da verificação:
// routes/web.php
use App\Http\Middleware\VerifyApiwppSignature;
use App\Jobs\ProcessApiwppEvent;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;
Route::post('/webhooks/apiwpp', function (Request $request) {
ProcessApiwppEvent::dispatch($request->json()->all());
return response()->noContent(); // 204, em milissegundos
})->middleware(VerifyApiwppSignature::class);
// bootstrap/app.php (Laravel 11 ou mais recente)
->withMiddleware(function (Middleware $middleware) {
$middleware->validateCsrfTokens(except: ['webhooks/apiwpp']);
})
No Laravel 10 ou anterior, a exceção vai no array $except de app/Http/Middleware/VerifyCsrfToken.php. Outra saída é declarar a rota em routes/api.php, que não passa pelo CSRF (no Laravel 11, o arquivo é criado com php artisan install:api). Em qualquer caso, a assinatura continua sendo a proteção da rota.
Processar os eventos em fila, sem duplicar
A rota só valida e despacha; o trabalho de verdade fica num Job. Isso mantém a resposta bem abaixo dos 10 segundos, mesmo quando o processamento consulta o banco ou chama outro serviço.
A entrega é pelo menos uma vez: uma resposta que se perdeu na rede, uma nova tentativa ou uma reconexão podem trazer o mesmo evento de novo. O processamento precisa ser idempotente, e a chave natural é o id da mensagem no WhatsApp. Em message.delivery e message.outgoing ele vem em data.messageId; em message.delivery, o mesmo id chega uma vez por status (sent, delivered, read), então o status entra na chave. Em message.incoming, o id está em data.raw.key.id. Para os eventos sem mensagem, como connection.status, um hash do evento inteiro serve.
Uma tabela com chave primária faz a deduplicação, e a transação garante que um evento que falhou no meio volte a ser processado na retentativa:
// migration
Schema::create('apiwpp_processed_events', function (Blueprint $table) {
$table->string('key')->primary();
$table->timestamp('created_at');
});
<?php
namespace App\Jobs;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;
use Illuminate\Support\Facades\DB;
class ProcessApiwppEvent implements ShouldQueue
{
use Queueable;
public function __construct(public array $event) {}
public function handle(): void
{
DB::transaction(function () {
$isNew = DB::table('apiwpp_processed_events')
->insertOrIgnore(['key' => $this->key(), 'created_at' => now()]);
if ($isNew === 0) {
return; // já processado
}
$data = $this->event['data'];
match ($this->event['type']) {
'message.incoming' => app(IncomingMessages::class)->handle($data),
'message.delivery' => app(DeliveryStatus::class)->update($data),
'message.send_failed' => app(DeliveryStatus::class)->failed($data),
'connection.status' => app(ConnectionMonitor::class)->handle($this->event['connectionId'], $data),
default => null, // tipos novos: ignore
};
});
}
private function key(): string
{
$data = $this->event['data'] ?? [];
$id = match ($this->event['type']) {
'message.incoming' => $data['raw']['key']['id'] ?? null,
'message.delivery' => isset($data['messageId']) ? $data['messageId'].':'.$data['status'] : null,
'message.outgoing' => $data['messageId'] ?? null,
default => null,
};
return $this->event['type'].':'.$this->event['connectionId'].':'
.($id ?? hash('sha256', json_encode($this->event)));
}
}
As classes IncomingMessages, DeliveryStatus e ConnectionMonitor são suas: é ali que a mensagem vira ticket, o pedido ganha o status "lido" ou alguém da equipe é avisado de que o número caiu. Repare no default => null: o contrato dos eventos só cresce, com tipos e campos novos, e o seu código deve ignorar o que não conhece em vez de falhar.
Dois cuidados com os eventos. O clientRef volta em message.delivery por até 72 horas depois do envio; um status mais tardio pode chegar com clientRef nulo, e aí você correlaciona pelo messageId. E a mídia recebida vem como uma URL assinada e temporária em data.media.url: baixe o arquivo no próprio Job, em vez de guardar o link. Limpe a tabela de eventos processados com um comando agendado, mas guarde pelo menos 7 dias: é o tempo em que uma entrega antiga ainda pode ser reenviada.
Se o seu endpoint ficar fora do ar, as entregas são tentadas de novo por cerca de 2, 4, 8, 16 e 32 segundos, e depois ficam no estado dead. O registro de entregas, no painel e na rota GET /webhooks/deliveries, mostra o estado, o status HTTP e o erro de cada uma, e a API reenvia uma entrega ou todas as mortas quando o sistema voltar. Com o processamento idempotente, reenviar tudo é seguro.
Testar sem chamar a API
O Http::fake() do Laravel permite testar o Job sem rede. Simule a resposta 202 e confira o que foi enviado:
use App\Jobs\SendWhatsAppMessage;
use Illuminate\Http\Client\Request;
use Illuminate\Support\Facades\Http;
public function test_envia_com_client_ref(): void
{
Http::fake([
'api.apiwpp.com/*' => Http::response(['jobId' => 'job-1', 'scheduledAt' => 1790251205000, 'position' => 1], 202),
]);
(new SendWhatsAppMessage('5511988887777', 'Olá!', 'pedido-1234-envio'))->handle();
Http::assertSent(fn (Request $request) =>
$request->hasHeader('Authorization')
&& $request['clientRef'] === 'pedido-1234-envio'
&& str_ends_with($request->url(), '/send'));
}
Para o webhook, monte o corpo, calcule a assinatura com o mesmo segredo do ambiente de teste e chame a rota com $this->call('POST', '/webhooks/apiwpp', server: [...], content: $body), passando os dois cabeçalhos como HTTP_X_SALES_TIMESTAMP e HTTP_X_SALES_SIGNATURE. Teste também o caminho que deve falhar: assinatura errada e timestamp antigo precisam receber 401.
PHP puro, sem framework
Sem Laravel, o curl nativo resolve os dois lados. O envio, com o Retry-After lido dos cabeçalhos:
<?php
$connectionId = getenv('APIWPP_CONNECTION_ID');
$headers = [];
$ch = curl_init("https://api.apiwpp.com/connections/{$connectionId}/send");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 15,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer '.getenv('APIWPP_KEY'),
'Content-Type: application/json',
'Accept: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'to' => '5511988887777',
'message' => 'Olá, Ana! Seu pedido 1234 saiu para entrega.',
'clientRef' => 'pedido-1234-envio',
], JSON_UNESCAPED_UNICODE),
CURLOPT_HEADERFUNCTION => function ($ch, $line) use (&$headers) {
$parts = explode(':', $line, 2);
if (count($parts) === 2) {
$headers[strtolower(trim($parts[0]))] = trim($parts[1]);
}
return strlen($line);
},
]);
$body = curl_exec($ch);
if ($body === false) {
// Rede ou tempo esgotado: repita depois com o mesmo clientRef
throw new RuntimeException(curl_error($ch));
}
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
$json = json_decode($body, true);
if ($status === 202 || $status === 200) {
echo "Na fila: {$json['jobId']}\n";
} elseif ($status === 429) {
echo 'Tente de novo em '.($headers['retry-after'] ?? '60')." s\n";
} else {
echo "Erro {$status}: {$json['error']}\n";
}
E o recebimento, num arquivo que responde no endereço do webhook:
<?php
$secret = getenv('APIWPP_WEBHOOK_SECRET');
if (!is_string($secret) || $secret === '') {
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, true);
// Grave $event numa fila ou tabela e processe fora da requisição
http_response_code(204);
Fora de um framework, getenv() funciona desde que a variável esteja no ambiente do PHP-FPM ou do servidor web. A página de integração com PHP reúne as variações com Guzzle.
Como começar hoje
- Adicione as quatro variáveis ao
.enve o blocoapiwppaoconfig/services.php. - Crie o
SendWhatsAppMessagee troque o primeiro envio do seu sistema por umdispatch, com umclientRefderivado do registro que a mensagem representa. - Crie o middleware
VerifyApiwppSignature, a rota/webhooks/apiwppfora do CSRF e o JobProcessApiwppEventcom a tabela de eventos processados. - Escreva os testes com
Http::fake()e um teste de webhook com assinatura válida e inválida. - Crie sua conta na apiwpp, conecte um número e mande a primeira mensagem de verdade. Os valores por número estão em preços.
Perguntas frequentes
Preciso de um pacote do Composer para usar a apiwpp no Laravel?
Não. A API é REST com JSON, e o Http facade do Laravel basta para enviar e ler as respostas. Se você quiser métodos e modelos tipados, há um cliente PHP gerado da especificação OpenAPI 3.1, sobre Guzzle, que você pede ao suporte ou gera com o OpenAPI Generator.
Como evitar que a retentativa de um Job envie a mensagem duas vezes?
Mande sempre um clientRef estável, derivado do registro que a mensagem representa, como pedido-1234-envio. Uma repetição com o mesmo valor, na mesma conexão, responde 200 com o job original e "duplicate": true, sem enfileirar nada. A reserva vale por 7 dias.
Por que o meu webhook no Laravel responde 419?
O 419 é o CSRF do Laravel recusando a requisição, porque a apiwpp não envia o token de formulário. Tire o caminho do webhook da verificação, com validateCsrfTokens(except: ...) no Laravel 11 ou no $except do VerifyCsrfToken nas versões anteriores, ou declare a rota em routes/api.php. A assinatura HMAC continua protegendo a rota.
Por que a assinatura do webhook não confere?
Quase sempre o HMAC foi calculado sobre um corpo diferente do que chegou, como um json_encode do array já convertido. Use $request->getContent(), os bytes exatamente como vieram, e a fórmula timestamp + "." + corpo. Confira também se o segredo chegou ao processo: com o cache de configuração, leia-o com config(), nunca com env() fora dos arquivos de configuração.
A mensagem sai no mesmo segundo em que o Job roda?
Não necessariamente. A chamada coloca a mensagem na fila do número e responde 202 com o scheduledAt e a posição. A fila respeita o ritmo que protege o número, com intervalos entre envios e limites por minuto, hora e dia, e o resultado chega depois pelo webhook message.delivery.
Posso usar Horizon ou outro driver de fila?
Sim. Os Jobs deste tutorial são Jobs comuns do Laravel e rodam em qualquer driver: database, Redis com Horizon ou SQS. O que garante que nada duplica é o clientRef no envio e a tabela de eventos processados no recebimento, não o driver da fila.
Leia também: