API do WhatsApp para Desenvolvedores — Construa, Lance, Escale

Uma API do WhatsApp que prioriza o desenvolvedor, com endpoints REST limpos, webhooks, exemplos de código em seis linguagens e infraestrutura que cresce com o seu projeto.

const response = await fetch('https://api2whats.com/send-text', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    to: '971501234567',
    message: 'Hello from my app!'
  })
});
const data = await response.json();
console.log(data.id); // message ID

Por Que os Desenvolvedores Escolhem Esta API

A maioria das soluções de API do WhatsApp é projetada primeiro para usuários não técnicos e depois para desenvolvedores. A documentação é escassa, as mensagens de erro são inúteis e você passa mais tempo lutando contra a API do que construindo com ela. Construímos esta API ao contrário — desenvolvedores primeiro, todo o resto depois.

Cada endpoint retorna JSON estruturado com códigos de erro claros. Cada requisição tem um formato de resposta previsível. A documentação inclui exemplos de código funcionais que você pode copiar e executar imediatamente. E o sistema de webhooks entrega mensagens recebidas ao seu servidor em tempo real com payloads assinados, para que você possa verificar a autenticidade.

Seja você construindo um chatbot de suporte ao cliente, um sistema de notificação de pedidos, uma ferramenta de automação de marketing ou uma integração personalizada para um cliente, a API sai do seu caminho e deixa você focar no seu código.

Visão Geral da Arquitetura

A API fica entre sua aplicação e os servidores do WhatsApp. Aqui está o que acontece quando você envia uma mensagem:

1. Sua aplicação envia uma requisição HTTP POST ao endpoint da API
2. A API autentica sua requisição usando a chave de API no cabeçalho Authorization
3. A mensagem é roteada para a instância correta do WhatsApp (se você tiver várias)
4. A mensagem é entregue por uma conexão WebSocket persistente ao WhatsApp
5. Você recebe uma resposta com o ID da mensagem e o status de entrega
6. As atualizações de status subsequentes (entregue, lida) são enviadas ao seu webhook

Todo o ciclo normalmente leva menos de 50 milissegundos. Não há navegador envolvido, nem processamento de capturas de tela, nem manipulação de DOM. A conexão WebSocket é persistente e lida automaticamente com reconexão, renovação de autenticação e recuperação de erros.

Referência da API REST

Todos os endpoints seguem as convenções REST. As requisições usam corpos JSON. As respostas usam JSON. A autenticação é feita via tokens Bearer no cabeçalho Authorization.

Enviando Mensagens

Gerenciando Instâncias

Webhooks

Integração de Webhooks

Os webhooks são como você recebe mensagens recebidas. Quando alguém envia uma mensagem para o seu número do WhatsApp conectado, a API faz uma requisição POST para sua URL de webhook com os dados da mensagem.

Um payload de webhook tem esta aparência:

{
  "event": "message",
  "instance": "instance_abc123",
  "data": {
    "id": "3EB0A1B2C3D4E5F6",
    "from": "971501234567",
    "message": "Hi, I need help with my order",
    "timestamp": 1691234567,
    "type": "text"
  }
}

Seu manipulador de webhook processa esses dados e pode disparar qualquer resposta automatizada. O sistema de webhooks suporta lógica de novas tentativas — se seu servidor estiver temporariamente indisponível, a API tenta a entrega várias vezes antes de desistir.

Por segurança, todos os payloads de webhook incluem um cabeçalho X-Signature que você pode verificar para garantir que a requisição realmente veio da nossa API e não de terceiros.

Exemplos de Código em Seis Linguagens

Fornecemos exemplos de código funcionais para cada operação comum. Cada exemplo é um script completo e executável — não um trecho que deixa você adivinhando sobre imports, tratamento de erros ou configuração.

PHP

<?php
$ch = curl_init('https://api2whats.com/send-text');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ***',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'to' => '971501234567',
        'message' => 'Hello from PHP!',
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Python

import requests

response = requests.post(
    'https://api2whats.com/send-text',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        'to': '971501234567',
        'message': 'Hello from Python!',
    }
)
print(response.json())

JavaScript (Node.js)

const response = await fetch('https://api2whats.com/send-text', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        to: '971501234567',
        message: 'Hello from Node.js!',
    }),
});
const data = await response.json();
console.log(data);

Tratamento de Erros

A API usa códigos de status HTTP padrão e retorna respostas de erro estruturadas:

{
    "success": false,
    "error": {
        "code": "INSTANCE_DISCONNECTED",
        "message": "The WhatsApp instance is not connected"
    }
}

Os códigos de erro comuns incluem:

• 401 Unauthorized — Chave de API inválida ou ausente
• 400 Bad Request — Campos obrigatórios ausentes ou dados inválidos
• 404 Not Found — Instância ou recurso inexistente
• 429 Too Many Requests — Limite de taxa excedido
• 500 Internal Server Error — Algo deu errado do nosso lado (raro)

Segurança dos Webhooks

Cada requisição de webhook inclui um cabeçalho X-Signature que contém uma assinatura HMAC-SHA256 do corpo da requisição. Seu manipulador de webhook deve verificar essa assinatura para garantir que a requisição realmente veio da nossa API e não de terceiros.

// Node.js webhook signature verification
const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
    const expected = crypto
        .createHmac('sha256', secret)
        .update(payload)
        .digest('hex');
    return crypto.timingSafeEqual(
        Buffer.from(signature),
        Buffer.from(expected)
    );
}

app.post('/webhook', (req, res) => {
    const sig = req.headers['x-signature'];
    const body = JSON.stringify(req.body);

    if (!verifySignature(body, sig, WEBHOOK_SECRET)) {
        return res.status(401).json({ error: 'Invalid signature' });
    }

    // Process the message...
    res.json({ success: true });
});

Testes e Depuração

A API oferece várias ferramentas para testar e depurar sua integração:

• Registros do painel — Veja todas as requisições à API e suas respostas em tempo real no seu painel
• Endpoint de teste de webhook — Envie um webhook de teste para verificar se seu manipulador está funcionando corretamente
• Acompanhamento do status da mensagem — Consulte o status de qualquer mensagem pelo ID
• Monitoramento da taxa de erros — Acompanhe as taxas de erro da sua API ao longo do tempo no painel

Recomendamos começar com uma instância de teste conectada ao seu número pessoal. Envie mensagens de teste, verifique os webhooks e confira o tratamento de erros antes de entrar em produção com tráfego real.

Boas Práticas para Desenvolvedores

• Armazene as chaves de API com segurança — Use variáveis de ambiente, não strings fixas no código. Nunca faça commit de chaves de API no controle de versão.
• Trate os erros com elegância — Implemente lógica de novas tentativas com backoff exponencial para erros transitórios (5xx, timeouts de rede).
• Valide as assinaturas dos webhooks — Nunca confie em requisições de webhook não verificadas. Sempre verifique o cabeçalho X-Signature.
• Use pool de conexões — Reutilize conexões HTTP entre as requisições em vez de criar novas para cada chamada à API.
• Monitore os limites de taxa — Verifique o cabeçalho X-RateLimit-Remaining e implemente limitação proativa ao se aproximar dos limites.
• Registre tudo — Registre pares de requisição/resposta para depuração. Oculte dados sensíveis (números de telefone, conteúdo de mensagens) nos registros de produção.

Limites de Taxa

Os limites de taxa são aplicados por chave de API e variam conforme o plano. A API retorna um código de status 429 com um cabeçalho Retry-After quando você atinge o limite. Estes são os padrões:

• Plano Basic — 100 requisições por minuto
• Plano Professional — 300 requisições por minuto
• Plano Enterprise — 1000 requisições por minuto

Se você atinge os limites de taxa com frequência, considere fazer upgrade do plano ou agrupar requisições quando possível.

Formatos de Payload de Webhook

As mensagens recebidas chegam em formatos diferentes, dependendo do tipo de mensagem:

Mensagem de Texto

{
  "event": "message",
  "data": {
    "id": "3EB0A1B2C3D4E5F6",
    "from": "971501234567",
    "message": "Hello!",
    "type": "text",
    "timestamp": 1691234567
  }
}

Mensagem de Imagem

{
  "event": "message",
  "data": {
    "id": "3EB0A1B2C3D4E5F7",
    "from": "971501234567",
    "type": "image",
    "caption": "Check this out!",
    "mediaUrl": "https://api2whats.com/media/...",
    "mimeType": "image/jpeg",
    "timestamp": 1691234568
  }
}

Atualização de Status

{
  "event": "status",
  "data": {
    "id": "3EB0A1B2C3D4E5F6",
    "status": "delivered",
    "timestamp": 1691234600
  }
}

Os valores de status incluem: sent (entregue ao WhatsApp), delivered (chegou ao dispositivo) e read (aberta pelo destinatário).

Começando

1. Crie uma conta (grátis, sem cartão de crédito)
2. Escolha um plano na página de preços
3. Crie uma instância no seu painel
4. Conecte seu número de telefone via QR ou código de pareamento
5. Leia a documentação completa da API
6. Envie sua primeira mensagem e comece a construir

Comunidade e Suporte

Junte-se à nossa comunidade de desenvolvedores para obter ajuda, compartilhar integrações e se manter atualizado sobre novos recursos. Temos uma comunidade ativa de desenvolvedores criando integrações do WhatsApp em todos os setores.

• Documentação — Referência abrangente da API com exemplos funcionais
• Exemplos de código — Scripts completos e executáveis em PHP, Python, JavaScript e cURL
• Suporte por e-mail — Resposta em até 24 horas para todos os planos
• Registros do painel — Visibilidade em tempo real das requisições à API e das entregas de webhook
• Página de status — Status do sistema ao vivo e histórico de incidentes

Esteja você construindo sua primeira integração do WhatsApp ou escalando uma existente, nossos recursos e equipe de suporte estão aqui para ajudar você a ter sucesso.