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?
- Uma mensagem por evento, para a pessoa do evento. Nada de lista.
- Consentimento. Peça a permissão (uma caixa no checkout, no formulário, no cadastro) e respeite o não perturbe.
- Chave só no servidor. Em constante, variável de ambiente ou cofre; nunca em página, aplicativo ou código que o cliente vê.
Idempotency-Keycom o id do evento (pedido-4512,cobranca-pay_123): se a plataforma reenviar o aviso, a mensagem não sai duas vezes.- Trate os erros
429(espere oretry_after),409(instância desconectada ou trava de contato novo) e422 number_not_on_whatsapp(registre e não insista). - Telefone com código do país, só dígitos. O Brasil começa com 55; a API resolve o nono dígito.
- Teste no sandbox.
A chamada-base, que os modelos repetem:
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:
// 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_postewp_json_encode, semeval,execou chamadas ao sistema; - só envia se o pedido tem o campo
_aceita_whatsappigual ayes: o seu checkout precisa gravar isso a partir de uma caixa de confirmação (sem ela, o trecho não envia); - grava
_pb_wa_enviadopara não repetir, e aIdempotency-Keyprotege 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.
// 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átis3. 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.
{
"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:
$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:
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.
{
"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:
{
"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:
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
- Integrações da API de WhatsApp: n8n, Make, Zapier
- Agendar mensagem de WhatsApp pela API
- Não perturbe e recusar chamadas: API de WhatsApp
- SDKs, OpenAPI e Postman da API de WhatsApp
Í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.