Empresa brasileira · Entrega automática · Suporte em português Seg a sex, 9h as 18h · PIX em reais
ProxyBox
API de WhatsApp · Integrações

13 modelos prontos para a API de WhatsApp: HTTP e JSON para copiar e adaptar

Modelos HTTP e JSON: pedido pago no WooCommerce com trecho PHP, Asaas, Hotmart, Kiwify, formulário, CRM, planilha, agenda, IA e não perturbe.

11 min de leitura Atualizado em 14 de novembro de 2026
Resposta curta
Todo modelo desta página faz a mesma coisa: um evento no seu sistema (pedido pago, cobrança, lead, linha de planilha) dispara uma chamada POST /messages/text com a chave no cabeçalho apikey, um Idempotency-Key com o id do evento e um texto curto. Há 13 modelos, com um trecho de PHP seguro para o WooCommerce, e todos assumem que quem recebe espera a mensagem.

Recurso em beta e modelos não testados em terceiros. A API da ProxyBox está em beta. Os formatos de aviso de WooCommerce, Asaas, Hotmart, Kiwify, Mercado Pago, RD Station, Kommo, Bitrix24 e Pipedrive aparecem aqui como exemplos; confira os campos reais na documentação de cada um.

O que todo modelo precisa respeitar?

  1. Uma mensagem por evento, para a pessoa do evento. Nada de lista.
  2. Consentimento. Peça a permissão (uma caixa no checkout, no formulário, no cadastro) e respeite o não perturbe.
  3. Chave só no servidor. Em constante, variável de ambiente ou cofre; nunca em página, aplicativo ou código que o cliente vê.
  4. Idempotency-Key com o id do evento (pedido-4512, cobranca-pay_123): se a plataforma reenviar o aviso, a mensagem não sai duas vezes.
  5. Trate os erros 429 (espere o retry_after), 409 (instância desconectada ou trava de contato novo) e 422 number_not_on_whatsapp (registre e não insista).
  6. Telefone com código do país, só dígitos. O Brasil começa com 55; a API resolve o nono dígito.
  7. Teste no sandbox.

A chamada-base, que os modelos repetem:

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/messages/text" \
  -H "apikey: SUA_CHAVE" -H "Idempotency-Key: ID_DO_EVENTO" -H "Content-Type: application/json" \
  -d '{"to":"5547999999999","text":"Texto da mensagem"}'

1. Pedido pago no WooCommerce

Quando: o pagamento do pedido é confirmado. Quem recebe: o comprador, que marcou aceitar mensagens no WhatsApp.

Para o WordPress chamar a API diretamente, sem plugin, ponha este trecho no functions.php do tema filho (ou num plugin seu). A chave fica numa constante no wp-config.php, fora do tema:

php
// wp-config.php (fora do tema, nunca em repositório):
// define('PROXYBOX_WA_KEY', 'pbwa_SUA_CHAVE');

add_action('woocommerce_payment_complete', 'pb_wa_pedido_pago', 20, 1);

function pb_wa_pedido_pago($order_id)
{
    if (!defined('PROXYBOX_WA_KEY')) {
        return;
    }
    $order = wc_get_order($order_id);
    // não envia duas vezes e só com consentimento (campo que o seu checkout grava)
    if (!$order || $order->get_meta('_pb_wa_enviado') || $order->get_meta('_aceita_whatsapp') !== 'yes') {
        return;
    }

    $fone = preg_replace('/\D+/', '', (string) $order->get_billing_phone());
    if (strlen($fone) <= 11) {
        $fone = '55' . $fone; // DDD + número sem código do país
    }
    $nome = sanitize_text_field($order->get_billing_first_name());
    $texto = sprintf('Olá, %s! Recebemos o pagamento do pedido #%s. Obrigado pela compra!', $nome, $order->get_order_number());

    $resp = wp_remote_post('https://proxybox.com.br/api/whatsapp/v1/messages/text', [
        'timeout' => 10,
        'headers' => [
            'apikey'          => PROXYBOX_WA_KEY,
            'Content-Type'    => 'application/json',
            'Idempotency-Key' => 'woo-pago-' . $order_id,
        ],
        'body'    => wp_json_encode(['to' => $fone, 'text' => $texto]),
    ]);

    if (is_wp_error($resp)) {
        $order->add_order_note('WhatsApp: falha de rede, mensagem não enviada.');
        return;
    }
    $code = (int) wp_remote_retrieve_response_code($resp);
    if ($code >= 200 && $code < 300) {
        $order->update_meta_data('_pb_wa_enviado', '1');
        $order->save();
        $order->add_order_note('WhatsApp enviado ao cliente.');
    } else {
        $order->add_order_note('WhatsApp não enviado (HTTP ' . $code . ').');
    }
}

O que o trecho faz e não faz:

  • usa wp_remote_post e wp_json_encode, sem eval, exec ou chamadas ao sistema;
  • só envia se o pedido tem o campo _aceita_whatsapp igual a yes: o seu checkout precisa gravar isso a partir de uma caixa de confirmação (sem ela, o trecho não envia);
  • grava _pb_wa_enviado para não repetir, e a Idempotency-Key protege de reexecuções;
  • não guarda a chave, não mostra a chave e não expõe erro técnico ao cliente: só uma nota interna no pedido;
  • espera até 10 segundos, o que pode atrasar a finalização em casos raros; para lojas grandes, mova a chamada para uma tarefa agendada do WordPress (wp_schedule_single_event).

Alternativa sem código no WordPress: em WooCommerce > Configurações > Avançado > Webhooks, crie um webhook "Pedido atualizado" apontando para o n8n ou para o seu servidor; o Woo assina o corpo no cabeçalho X-WC-Webhook-Signature, que você confere. O fluxo então chama a API como no modelo base.

2. Cobrança criada ou vencida no Asaas

Quando: o Asaas avisa PAYMENT_CREATED, PAYMENT_OVERDUE ou PAYMENT_RECEIVED. Quem recebe: o cliente da cobrança.

Pontos da documentação do Asaas, lidos em 11/11/2026: o evento PAYMENT_RECEIVED é distinto de PAYMENT_CONFIRMED; a entrega é "pelo menos uma vez" (trate o id do evento como chave única); e o cabeçalho asaas-access-token identifica a origem. O aviso traz o id do cliente, não o telefone: busque o telefone na API do Asaas.

js
// Express: endpoint que o Asaas chama
app.post("/asaas", express.json(), async (req, res) => {
  if (req.header("asaas-access-token") !== process.env.ASAAS_TOKEN) return res.sendStatus(401);
  res.sendStatus(200); // responda logo; processe depois
  const { id, event, payment } = req.body; // campos de exemplo: confira na documentação do Asaas
  if (event !== "PAYMENT_OVERDUE") return;

  const cliente = await (await fetch(`https://api.asaas.com/v3/customers/${payment.customer}`, { headers: { access_token: process.env.ASAAS_KEY } })).json();
  if (!cliente.mobilePhone) return;
  await fetch("https://proxybox.com.br/api/whatsapp/v1/messages/text", {
    method: "POST",
    headers: { apikey: process.env.WA_KEY, "Idempotency-Key": `asaas-${id}`, "Content-Type": "application/json" },
    body: JSON.stringify({ to: "55" + cliente.mobilePhone.replace(/\D/g, ""), text: `Olá! A cobrança de R$ ${payment.value} venceu em ${payment.dueDate}. Link: ${payment.invoiceUrl}` }),
  });
});

Cuidado: só cobre quem tem cobrança com você. Cobrança envolve dados pessoais: mantenha o texto curto, sem CPF, e ofereça um jeito de parar.

Quer rodar isto agora? O sandbox é grátis, não precisa de número e já vem com a chave da API.

Testar grátis

3. Compra aprovada na Hotmart

Quando: a Hotmart avisa compra aprovada. Quem recebe: o comprador. A Hotmart tem a sua forma de autenticar o aviso (um token no cabeçalho): confira na documentação e valide a origem antes de enviar. Os nomes de campo abaixo são de exemplo.

json
{
  "to": "5511988887777",
  "text": "Olá, Carlos! Sua compra de \"Curso de Fotografia\" foi aprovada. Acesse a área de membros: https://membros.exemplo.com.br"
}

Use o id da transação como Idempotency-Key (hotmart-HP12345678). Se o telefone do comprador não vier no aviso, não invente: deixe de enviar e registre.

4. Compra aprovada na Kiwify

Mesmo desenho do modelo 3: a Kiwify avisa a compra aprovada por webhook, você valida a origem como a documentação dela pede, extrai nome, produto e telefone (nomes de campo a conferir) e chama a API com Idempotency-Key igual ao id do pedido (kiwify-<id>). Texto sugerido: "Olá, {nome}! Seu acesso a {produto} foi liberado: {link}".

5. Formulário do site

Quando: a pessoa preenche um formulário e marca "quero receber retorno pelo WhatsApp". Em PHP, no POST do formulário:

php
$resp = (new WhatsApp(getenv('WA_KEY')))->texto(
    '55' . preg_replace('/\D/', '', $_POST['telefone']),
    'Olá, ' . htmlspecialchars($_POST['nome'], ENT_QUOTES) . '! Recebemos o seu contato e retornamos em até 1 dia útil.',
    'form-' . $idDoRegistro
);

A classe WhatsApp é o cliente mínimo de SDKs. Valide o formulário (captcha, limite por IP) antes de chamar a API: um formulário aberto vira, sem querer, um disparador de mensagens para qualquer número. Esse é o abuso mais comum.

6. Lead novo no RD Station

O RD Station avisa um evento de conversão por webhook para o n8n ou o Make. O fluxo, na ordem: recebe o evento, confere o consentimento (campo do formulário), chama POST /messages/text com uma mensagem de boas-vindas, e quando o lead responde (aviso message.received), anota no RD o interesse. Nomes de campo do RD: a conferir na documentação.

7. Lead novo no Kommo, Bitrix24 ou Pipedrive

Igual ao modelo 6, com o gatilho "lead criado" do CRM. Para o caminho de volta, o fluxo escuta o aviso message.received, procura o lead pelo telefone (data.from) e cria uma nota ou muda a etapa. Cada CRM tem OAuth e limites próprios; é por isso que não há conector fechado. Para equipes que precisam de atendimento de verdade, o Chatwoot é mais adequado.

8. Linha nova na planilha vira uma mensagem

Com Apps Script, num gatilho "ao editar" ou por tempo:

js
function avisar(linha) { // linha = [nome, telefone, texto, enviado]
  if (linha[3] === "sim") return;
  var chave = PropertiesService.getScriptProperties().getProperty("WA_KEY");
  var r = UrlFetchApp.fetch("https://proxybox.com.br/api/whatsapp/v1/messages/text", {
    method: "post", contentType: "application/json", muteHttpExceptions: true,
    headers: { apikey: chave, "Idempotency-Key": "sheet-" + linha[1] + "-" + linha[2].length },
    payload: JSON.stringify({ to: "55" + String(linha[1]).replace(/\D/g, ""), text: linha[2] })
  });
  return r.getResponseCode() === 200;
}

A planilha guarda a chave em Propriedades do script, nunca numa célula. Marque a linha como enviada. Não use para percorrer a lista inteira de uma vez: o limite é de 10 por minuto, e envio em massa é proibido.

9. Lembrete de agenda

O agendamento de uma mensagem foi provado em aparelho real em 12/11/2026 (a mensagem chegou na hora marcada).

Para avisar a consulta de amanhã às 9h, use o agendamento de uma mensagem: o POST leva schedule.at, e a ProxyBox envia na hora marcada.

json
{
  "to": "5547999999999",
  "text": "Lembrete: sua consulta é amanhã às 9h. Responda 1 para confirmar ou 2 para remarcar.",
  "schedule": { "at": "2026-11-12T08:00:00-03:00" }
}

A resposta é 202 com schedule_id. Ao cancelar o compromisso, DELETE /schedules/{id}. Detalhes em agendar.

10. Resposta com IA

Ligue o bot do tipo OpenAI ou Claude com instruções claras e a aprovação humana na estreia:

json
{
  "type": "openai", "url": "https://api.openai.com/v1", "api_key": "SUA_CHAVE", "model": "gpt-4o-mini",
  "system_prompt": "Você atende a Loja Exemplo. Responda em até 3 frases, sem markdown. Se não souber, diga que vai chamar um atendente.",
  "trigger": "all", "ignore_groups": true, "stop_on_human_minutes": 30
}

Envie em PUT /integrations/bot e, em PUT /instance/settings, {"approval_mode": "bots"}.

11. Perguntar com botões e gravar a escolha

Envie uma pergunta com botões de resposta ("Confirma a entrega amanhã?" com sim e nao; o envio foi provado em aparelho em 12/11/2026) e trate o message.received com type igual a button_reply. Lembre-se: o aviso do toque recebido ainda não foi provado; aceite também "sim" e "não" em texto. Lista e carrossel não funcionam.

12. Quem pede para parar entra no não perturbe

Provado em aparelho real em 12/11/2026: com o número na lista, o envio dá 409 opted_out; ao tirá-lo, volta a enviar.

Quando chegar message.received com texto "PARAR", "SAIR" ou semelhante, chame POST /optout com o telefone e responda uma confirmação:

bash
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/optout" \
  -H "apikey: SUA_CHAVE" -H "Content-Type: application/json" \
  -d '{"phone":"5547999999999","reason":"Pediu para parar"}'

Depois disso, qualquer envio a esse número devolve 409 opted_out e nada sai. Esse modelo deve existir em toda instância que manda mensagens automáticas.

13. Alerta de queda da instância

Receba connection.updated e number.restricted e avise a sua equipe (e-mail, Slack, Telegram) quando status for disconnected. Combine com GET /health a cada poucos minutos e com a página de status. Um monitor como o Uptime Kuma pode consultar o /status?format=json da ProxyBox.

E os modelos do n8n?

O pacote de nós do n8n traz 8 modelos importáveis (resposta automática, atendimento com IA, verificar número, fatura em PDF, lembrete, botões e planilha, encaminhar para Chatwoot, Slack e Telegram, backup diário). Eles ainda não foram rodados num n8n real.

Veja também

Índice completo: índice dos guias. Sobre o produto: API de WhatsApp para o seu sistema.

Autoria: equipe técnica da ProxyBox. Atualizado em 11/11/2026. Formatos de terceiros: Asaas lido em 11/11/2026; os demais não foram conferidos nesta rodada. Recurso em beta.

Perguntas frequentes

Os modelos foram testados com Woo, Asaas, Hotmart e os outros?
Não. Os modelos foram escritos contra a API da ProxyBox, que tem testes automáticos, mas não foram executados nos serviços de terceiros. Confira os nomes de campo na documentação de cada plataforma antes de ligar.
Posso usar os modelos para enviar para uma lista de clientes?
Não. Cada modelo manda uma mensagem por evento (um pedido, uma cobrança, um lead) a quem tem relação com aquele evento. Envio para listas é mensagem em massa, proibido pela política de uso aceitável.
Preciso do n8n?
Não. Os modelos mostram a chamada HTTP; você pode fazê-la do n8n, do Make, de um servidor seu ou, no caso do WordPress, do próprio WordPress.

Guias relacionados

Pronto para colocar no ar?

Comece no sandbox, grátis. Quando funcionar, contrate a instância do seu número e pague com PIX ou saldo.

Com IP brasileiro dedicado R$ 89,90/mês
Só a instância (traga o seu IP) R$ 39,90/mês
Travou em alguma etapa?Manda o print do erro no WhatsApp. Respondemos em português.
Suporte em português Fale no WhatsApp