API do WhatsApp Business com PHP: Tutorial Completo 2026

PHP ainda é a linguagem de servidor mais usada no mundo, e integrar a API do WhatsApp Business com PHP é mais simples do que parece. Com cURL ou a biblioteca Guzzle, você envia mensagens, processa webhooks e cria chatbots sem precisar migrar sua stack.

Configuração e dependências

A forma mais simples de fazer chamadas HTTP em PHP é com a biblioteca Guzzle, que abstrai o cURL e fornece uma API limpa para requisições. Para o webhook, qualquer servidor PHP (Apache, Nginx com PHP-FPM, Laravel, Slim) funciona.

1. composer require guzzlehttp/guzzle vlucas/phpdotenv
2. Crie o arquivo .env com WHATSAPP_TOKEN, PHONE_NUMBER_ID, VERIFY_TOKEN e APP_SECRET
3. Crie a classe WhatsAppClient para encapsular as chamadas à API
4. Crie o endpoint webhook.php para processar eventos recebidos

Enviando mensagens de texto com PHP e Guzzle

A função de envio cria uma instância do Guzzle Client com o base_uri da Graph API e o header Authorization com o token. O método post() envia o payload JSON com o número do destinatário e o conteúdo da mensagem.

Em caso de erro, capture GuzzleException e registre o response body para diagnóstico. Erros comuns são token expirado, número inválido e template não aprovado.

• Base URI: https://graph.facebook.com/v19.0/
• Endpoint: {PHONE_NUMBER_ID}/messages
• Headers: Content-Type: application/json, Authorization: Bearer {token}
• Body mínimo para texto: messaging_product, recipient_type, to, type='text', text.body

Implementando o webhook em PHP puro

O arquivo webhook.php precisa tratar dois tipos de requisição: GET (verificação inicial da Meta) e POST (eventos de mensagem). Use $_SERVER['REQUEST_METHOD'] para diferenciar.

Na verificação GET, compare $_GET['hub_verify_token'] com seu token secreto e imprima $_GET['hub_challenge'] sem headers adicionais. Na requisição POST, leia o body com file_get_contents('php://input') e decodifique o JSON.

Integração com Laravel

Em um projeto Laravel, crie um Controller para o webhook, registre as rotas no routes/api.php e use o sistema de Jobs para processamento assíncrono das mensagens. Isso garante resposta rápida ao webhook e processamento em background.

1. php artisan make:controller WhatsAppWebhookController
2. Adicione rotas GET e POST para /api/webhook/whatsapp em routes/api.php
3. Adicione a rota ao array $except do VerifyCsrfToken middleware
4. php artisan make:job ProcessWhatsAppMessage para processamento assíncrono
5. Configure a queue driver para Redis ou database em produção
6. php artisan make:service WhatsAppService para encapsular a lógica de envio

Enviando templates com parâmetros dinâmicos

Para enviar um template com variáveis, monte o array components com um objeto do tipo body e o array parameters com os valores. Cada variável {{1}}, {{2}} corresponde a um objeto no array na mesma ordem.

• tipo 'header': parâmetros que aparecem no cabeçalho do template
• tipo 'body': parâmetros do corpo principal da mensagem
• tipo 'button': parâmetros de botões com URL dinâmica
• Variáveis de data e número também usam type='text'

Deploy e configuração no servidor

O webhook precisa ser HTTPS. Use Certbot com Let's Encrypt para configurar SSL gratuitamente em um VPS com Apache ou Nginx. Configure o DocumentRoot para o diretório público do projeto e garanta que as variáveis de ambiente estão disponíveis para o PHP-FPM.

• Apache: configure mod_rewrite para o .htaccess do Laravel
• Nginx: use fastcgi_pass para o PHP-FPM e configure try_files para o index.php
• Certbot: certbot --nginx -d seudominio.com.br para SSL automático
• Variáveis de ambiente: use .env ou variáveis de sistema, nunca hardcode no código

Perguntas frequentes