Pular para o conteúdo
D-APITestar grátis

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.

A gente também é SaaS

SaaS liberado pelo time testa 14 dias grátis, com um grupo de onboarding em que o time técnico da D-API acompanha a integração no seu produto.

Continue por aqui

Liberar seu teste grátis

Responda rapidinho e o time libera seu teste pelo WhatsApp, com o time técnico ajudando na integração.

Seus dados são usados só pra liberar o teste. Sem spam.