integração · php
API WhatsApp PHP com curl ou Guzzle, sem SDK e sem servidor extra
Integre a API WhatsApp PHP do seu SaaS com o que o projeto já tem: curl nativo ou Guzzle chamando a REST da D-API para conectar o número do cliente, enviar mensagens e receber eventos num endpoint PHP comum.
SaaS testa 14 dias com o time técnico ajudando na integração.
- conexões na D-API
- 1.875
- de uptime garantido em contrato
- 99,9%
- datacenters no Brasil
- 4
- por ligação de WhatsApp na API não-oficial
- R$ 0
Funciona no PHP que você já roda
Não há SDK PHP. Qualquer cliente HTTP chama a REST com o header Authorization, em hospedagem compartilhada ou em contêiner.
Webhook num arquivo PHP
O evento chega como POST JSON. php://input, um token no path e uma tabela com índice único no ID da mensagem resolvem.
Assinatura verificável
O webhook de comandos com secret envia X-DAPI-Signature, validado com hash_hmac e hash_equals.
A API WhatsApp PHP da D-API é a mesma API REST que serve qualquer linguagem. Não existe SDK PHP, e um SaaS em PHP não precisa de um: a API recebe JSON, autentica por um header e está descrita em OpenAPI 3. Com curl nativo ou Guzzle, o seu sistema conecta o WhatsApp do cliente, envia mensagens e recebe eventos sem adicionar outro serviço à infraestrutura.
O exemplo desta página é uma plataforma de pedidos para restaurantes, escrita em PHP, em que cada restaurante conecta o próprio número para avisar o cliente sobre o pedido.
Chamar a API de WhatsApp com curl em PHP
O resultado esperado é uma função única, com timeout e tratamento de erro, que o resto do código usa. Com curl nativo:
<?php
function dapi(string $method, string $path, ?array $body = null): array
{
$ch = curl_init('https://api.d-api.cloud' . $path);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => $method,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CONNECTTIMEOUT => 5,
CURLOPT_TIMEOUT => 20,
CURLOPT_HTTPHEADER => [
'Authorization: ' . getenv('DAPI_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => $body === null ? null : json_encode($body),
]);
$raw = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
$error = curl_error($ch);
curl_close($ch);
if ($raw === false) {
throw new RuntimeException("Falha de rede: $error");
}
$data = json_decode($raw, true) ?? [];
if ($status >= 400 || ($data['success'] ?? null) === false) {
throw new RuntimeException($data['error'] ?? $data['message'] ?? "HTTP $status", $status);
}
return $data;
}
A função confere duas coisas porque a API usa as duas. Um envio síncrono que não saiu volta com HTTP 400 e success: false. Algumas rotas respondem success: false no corpo com status 200, por exemplo quando a sessão ainda não está conectada.
A mesma chamada com Guzzle
Se o projeto já usa Guzzle, o cliente fica assim:
<?php
use GuzzleHttp\Client;
$dapi = new Client([
'base_uri' => 'https://api.d-api.cloud',
'timeout' => 20,
'http_errors' => false,
'headers' => ['Authorization' => getenv('DAPI_API_KEY')],
]);
$resp = $dapi->post('/api/v1/messages/send/text', ['json' => [
'sessionId' => 'rest-cantina-da-vila',
'to' => '5511999999999',
'text' => 'Seu pedido 8812 saiu para entrega. Chega em uns 30 minutos.',
]]);
$data = json_decode((string) $resp->getBody(), true);
Com http_errors desligado, o seu código lê o corpo também nas respostas de erro e aplica a mesma regra de status e success.
Conectar o número do restaurante
Dono de restaurante costuma configurar o sistema pelo computador do caixa, com o celular no bolso. Para ele, o código de pareamento é mais prático que o QR: ele digita um código no WhatsApp em vez de apontar a câmera para a tela.
<?php
dapi('POST', '/api/v1/sessions', [
'sessionId' => 'rest-cantina-da-vila',
'type' => 'unofficial',
'connectionMode' => 'pair',
'pairPhone' => '5511988887777',
'webhookUrl' => 'https://pedidos.seu-saas.com/hooks/whatsapp.php?t=' . getenv('WA_HOOK_TOKEN'),
]);
$pair = dapi('GET', '/api/v1/sessions/rest-cantina-da-vila/pair-code');
echo $pair['pairCode']; // código de 8 caracteres, como ABCD-1234
No celular, o dono abre Aparelhos conectados, escolhe conectar com número de telefone e digita o código. O evento connection.status com status: "connected" avisa o seu sistema para fechar a tela de onboarding. O passo a passo para o usuário final está em código de pareamento do WhatsApp.
Avisar o pedido com texto e localização
O aviso de pedido fica mais útil com o endereço de retirada ou o ponto de entrega. POST /api/v1/messages/send/location recebe latitude, longitude, name e address:
<?php
dapi('POST', '/api/v1/messages/send/location', [
'sessionId' => 'rest-cantina-da-vila',
'to' => '5511999999999',
'latitude' => -23.5614,
'longitude' => -46.6559,
'name' => 'Cantina da Vila',
'address' => 'Retirada no balcão lateral',
]);
A resposta síncrona traz o messageId. Grave-o no pedido para casar depois com os eventos message.delivered e message.read.
Receber o webhook em PHP
As respostas dos clientes chegam como POST JSON com o envelope event, sessionId, data, timestamp e traceId. Um arquivo PHP basta:
<?php
if (!hash_equals(getenv('WA_HOOK_TOKEN'), $_GET['t'] ?? '')) {
http_response_code(401);
exit;
}
$event = json_decode(file_get_contents('php://input'), true);
$pdo->prepare('INSERT IGNORE INTO wa_events (message_id, session_id, event, payload) VALUES (?, ?, ?, ?)')
->execute([$event['data']['id'] ?? null, $event['sessionId'], $event['event'], json_encode($event)]);
http_response_code(200);
if (function_exists('fastcgi_finish_request')) {
fastcgi_finish_request();
}
A tabela wa_events com índice único em message_id absorve as reentregas. Elas acontecem: cada tentativa espera até 30 segundos e a entrega é repetida até 7 vezes com backoff exponencial. Um worker lê a tabela e aplica a regra de negócio, como reconhecer “cancelar” na mensagem do cliente. Evite responder 404 ou 410 por erro interno, porque esses códigos encerram as tentativas para aquela URL. O formato de cada evento está no catálogo de eventos de webhook.
Envio assíncrono e assinatura em PHP
Na hora do almoço, o restaurante dispara dezenas de avisos por minuto. Com 'async' => true no corpo, a API responde na hora com um commandId, e o resultado de cada envio chega depois no webhook de conta command.result. Esse webhook, configurado com secret, assina o corpo bruto com HMAC-SHA256 no header X-DAPI-Signature:
<?php
$raw = file_get_contents('php://input');
$expected = hash_hmac('sha256', $raw, getenv('DAPI_CMD_SECRET'));
if (!hash_equals($expected, $_SERVER['HTTP_X_DAPI_SIGNATURE'] ?? '')) {
http_response_code(401);
exit;
}
$result = json_decode($raw, true)['data'];
O $result traz commandId, success, data com o messageId e error em caso de falha. Use o commandId como chave para ignorar repetições. O fluxo completo, com ordem por destinatário e limites, está em comandos assíncronos.
Escolher os eventos que chegam no seu PHP
Um restaurante movimentado gera muito evento que o seu sistema não usa. Filtrar na origem reduz carga no servidor e linhas na tabela. Na criação da sessão, ignoreGroups e ignoreStatus deixam de fora mensagens de grupos e os status (stories) dos contatos. Para escolher evento por evento, POST /api/v1/sessions/{sessionId}/webhook-config aceita dois modos: single, com todos os eventos habilitados indo para a mesma URL, e per_event, em que cada evento tem a sua webhookUrl. Um desenho comum é mandar messages.received para o endpoint de atendimento e connection.status para um script que avisa o restaurante quando o número desconecta, com data.status igual a logged_out ou disconnected.
Mídia nos dois sentidos
Cardápio em PDF, foto do prato do dia e áudio do cliente explicando o endereço entram no mesmo fluxo. Para enviar, as rotas /api/v1/messages/send/document, /image e /audio recebem o arquivo no campo de mesmo nome, com fileName e mimetype no documento e caption onde faz sentido. Para receber, o messages.received de mídia traz media_url apontando para o arquivo já armazenado e media_data com mimetype e tamanho, então o worker baixa com o mesmo cliente HTTP e anexa ao pedido.
O que repetir quando a chamada falha
Repetir um envio pode duplicar o aviso para o cliente do restaurante, então a retentativa precisa de critério. Repita automaticamente falha de rede antes da resposta, 5xx e 429, respeitando o header Retry-After. Trate 400 como erro de dado e registre o motivo. Para os avisos em volume, o modo assíncrono é mais seguro: a D-API nunca reexecuta um comando que falhou, e o command.result diz com certeza o que saiu.
Mesmo contrato, qualquer stack
Tudo nesta página é a REST pura, então o mesmo desenho funciona em outros serviços do seu produto. O guia de API WhatsApp Python mostra o fluxo com httpx e FastAPI, e o SDK Node cobre as mesmas rotas com tipos. A lista completa de endpoints está na documentação da D-API.
Time D-API. Atualizado em .
Perguntas frequentes
A D-API tem SDK para PHP?
Não. O SDK oficial é para Node.js. Em PHP, a integração é feita direto na API REST, que é a mesma que o SDK chama, com curl ou Guzzle.
Meu PHP roda em PHP-FPM. Como respondo o webhook rápido?
Grave o evento numa fila ou tabela e responda 200. Em PHP-FPM, fastcgi_finish_request entrega a resposta ao cliente e deixa o script terminar o trabalho leve depois. Processamento pesado vai para um worker.
Posso usar a mesma integração para vários clientes do meu sistema?
Pode. Cada número é uma sessão com o sessionId que você escolhe. Todo evento traz o sessionId, e o seu código usa esse valor para achar o tenant.
Como sei se uma mensagem não saiu?
No envio síncrono, a falha volta com HTTP 400 e success false. Algumas rotas respondem success false no corpo, como quando a sessão não está conectada, então confira o status HTTP e o campo success.