Resposta curta: a API de WhatsApp da ProxyBox é uma instância por número, com chave própria e IP brasileiro de provedor dedicado, para enviar e receber mensagens, mídia e avisos por HTTP, ligar bots e o Chatwoot e guardar a mídia recebida no seu armazenamento. Não é a API oficial da Meta: o WhatsApp pode bloquear qualquer número. O preço é de R$ 89,90 por mês no plano com IP dedicado e de R$ 39,90 só com a sua própria conexão.
A primeira mensagem, depois de conectar o número, é uma chamada:
``bash``
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/messages/text" \
-H "apikey: SUA_CHAVE" -H "Content-Type: application/json" \
-d '{"to":"5547999999999","text":"Seu pedido saiu para entrega."}'
# {"ok":true,"id":"3EB0B430B6F8F1D0E053AC120E0A9E5C","to":"5547999999999","status":"sent","sent_at":"2026-11-12T14:03:22-03:00"}
Você contrata, lê o QR com o celular do número (ou digita um código de pareamento), recebe uma chave que abre só aquela instância e passa a enviar e receber pelo seu sistema, sem montar servidor, sem instalar nada e sem cuidar de atualização. Antes de pagar, dá para testar a integração inteira no sandbox, um ambiente grátis que não envia nada ao WhatsApp. A referência traz um exemplo para cada rota, e a especificação OpenAPI e a coleção do Postman ficam num endereço público. Todos os guias estão reunidos na documentação da API de WhatsApp.
Importante antes de seguir: esta API usa o mesmo protocolo dos aparelhos conectados ao WhatsApp. Ela não é a API oficial da Meta, não tem vínculo com a Meta e o WhatsApp pode bloquear qualquer número, inclusive o seu. Não há reembolso por bloqueio. A seção o que saber antes de contratar explica o que isso significa na prática.
*Autoria: equipe técnica da ProxyBox. Atualizado em 12/11/2026. Preços de concorrentes lidos nos sites deles em 10 e 11/11/2026; recursos novos da versão 1.2 estão em beta, salvo os provados em 12/11/2026 (veja o histórico de versões).*
O que vem em cada instância?
Cada instância é um número de WhatsApp conectado à API, com chave, histórico e, no plano com IP, endereço de saída só dela. Lista curta do que ela inclui:
- Um número, uma instância, um IP. Três números são três instâncias. O WhatsApp enxerga o número sempre no mesmo lugar, no Brasil, e não no endereço de um servidor dividido com centenas de outros.
- Uma chave por instância, sem chave global. A chave
pbwa_…abre só aquela instância, pode ser limitada a IPs permitidos e, se vazar, é trocada no painel (a anterior morre na hora). - Envio completo: texto, imagem, vídeo, áudio, mensagem de voz, documento, figurinha, localização, contato, link, enquete, reação, edição e apagar mensagem.
- Botões de resposta e de ação (link, copiar código e ligar), provados em aparelho; lista e carrossel não funcionam hoje. E status (desligado por padrão), em beta.
- Cobrança PIX com o código "copia e cola" e botão de copiar, provada em aparelho em 14/11/2026, além de bloquear contato, comunidades, canais e presença, em beta.
- Grupos, contatos e conversas: administrar grupos, conferir se um número tem WhatsApp, ler conversas, etiquetar e baixar a mídia que chegou.
- Receber do jeito que preferir: aviso automático assinado, ou consulta com espera se você não tem endereço público, e mensagens seguidas reunidas em um aviso só.
- Bots e atendimento: Typebot, Dify, Flowise, OpenAI e compatíveis, Claude, n8n ou webhook respondendo pela instância, e o Chatwoot para a equipe.
- Controle: aprovação humana antes de bots e assistentes enviarem, equipe com papéis, atividade e métricas e lista de "não perturbe".
- Agendamento de uma mensagem por vez, até 30 dias à frente, sem repetição.
- Rotas no estilo da Evolution e da Z-API para migrar sem reescrever, e um conector para assistentes de IA.
- Limites de ritmo que protegem o número e um painel em português com QR, chave, teste de envio e histórico.
Provado em aparelho real em 12/11/2026, pela API pública: texto, texto temporário (expires_in), texto citando (reply_to), imagem por base64, documento (PDF), voz e áudio como arquivo, figurinha, localização, contato, link (sai como texto com o endereço), enquete, botões de resposta e de ação (link, copiar código e ligar), reação (colocar e tirar), editar, apagar para todos, encaminhar, marcar como lida, ler conversa, não perturbe, aprovação humana, agendamento de uma mensagem, etiquetas, ajustes e proteções (IP permitido recusado, status desligado), consulta de avisos (fila), e as rotas no estilo da Evolution (sendText, sendButtons, whatsappNumbers) e da Z-API (send-text). Provado em 10/11/2026: imagem, documento, voz, áudio, enquete, ler conversas e baixar mídia recebida, contatos, foto, perfil e listar grupos. Não funcionam: lista (menu) e carrossel, que o WhatsApp mostra como "mensagem incompatível" e a API recusa com 422 interactive_unsupported. Ainda não provados (em beta): botão de localização, vídeo, status, grupos além de listar, avisos de mensagens recebidas (voto de enquete, resposta de botão, reação, texto, foto, voz), recusa de chamada, S3, Chatwoot, bots e imagem por URL. O que não foi provado aparece escrito como limite, não como promessa.
O que é diferente nas outras APIs, e o que é igual?
Quem compara APIs de WhatsApp logo vê que várias coisas se repetem. Aqui vai a leitura honesta do que é diferencial e do que é paridade (conferida em 10 e 11/11/2026 nos sites e nas documentações):
| Recurso | ProxyBox | Outros que informam o recurso |
|---|---|---|
| IP brasileiro de provedor, um por número, incluso | Sim, no plano com IP | Nenhum concorrente lido tem página de produto igual; uazapi documenta proxy gerenciado por região; Evolution, WAHA e outras aceitam o proxy do cliente |
| Se o IP cai, a instância desconecta em vez de sair pelo IP do servidor | Sim (provado com IP de casa) | A documentação da Z-API para parceiros conecta sem proxy depois de três falhas |
| Chave só por instância, sem chave global | Sim | Evolution mantém chave global |
| Rotas no estilo da Evolution e da Z-API | Sim, as duas | Não encontramos outra que ofereça as duas |
| Sandbox grátis | Sim, 30 dias | Whapi.Cloud tem sandbox |
| Aprovação humana antes de IA enviar | Sim | Wassenger descreve robô com aprovação |
| Conector de IA (MCP) | Sim | WAHA e Wassenger também têm |
| Typebot, Dify, Flowise, OpenAI, Chatwoot, S3 | Sim, em beta | A Evolution tem a família inteira |
| Consulta de avisos (pull) com espera | Sim | Não é exclusivo |
| WebSocket, filas (RabbitMQ, SQS, Kafka) | Não | A Evolution oferece |
Em resumo: o que não se copia com uma tarde de código é o IP de provedor brasileiro por número, incluso e vendido pela mesma empresa, com a instância desenhada para desconectar em vez de vazar o endereço do servidor. O resto é, em boa parte, paridade, e a lista de ausências é a última linha da tabela.
Como a ProxyBox se compara à Z-API, W-API, Whapi, WAHA e Evolution em preço?
No preço, a ProxyBox não é a mais barata, e não pretende ser: o plano com IP traz o endereço junto. Preços lidos nos sites em 11/11/2026 (salvo onde indicado), sem criar conta. Preço e plano mudam: confira no site de cada uma antes de decidir.
| Alternativa | Preço público | IP na página de preço | Observação da página |
|---|---|---|---|
| W-API | R$ 19,90 (Lite) a R$ 29,90 (Pro) por mês por instância; pacotes para agências | Não informado | O plano Lite não tem enquetes, listas, botões nem PIX; teste de 7 dias |
| Wafly | R$ 59,90 por mês por número (lido em 10/11) | Não informado | Teste de 3 dias; nó próprio para n8n |
| Whapi.Cloud | US$ 29 por mês por número, de US$ 40 (site em inglês); em 10/11 a versão em português mostrava R$ 49 | Não informado; a central de ajuda cita proxies padrão e regionais | Sandbox grátis: 150 mensagens por dia, 30 verificações de número por dia, 1.000 requisições por mês; teste de 5 dias |
| Mega API | R$ 69,90 (Start) ou R$ 99,90 (Business) por instância (lido em 10/11) | Não informado | Grupos e mais rotas só nos planos mais caros |
| Z-API | R$ 99,99 por mês por canal (Omni, teste de 2 dias); R$ 89,99 por canal com 10 canais ou mais (Partner) | Proxy do cliente, no programa para parceiros | Documentação extensa; sem contrato mínimo, segundo a página |
| Wassenger | De US$ 39,90 a US$ 99,90 por mês por número, conforme os agentes incluídos; teste de 7 dias | Não informado | Inclui agentes de atendimento |
| WAHA | O site diz "100% gratuito e de código aberto"; recursos pagos (Plus) citados nos guias: preço não confirmado | Você providencia | Você hospeda; atualização e IP por sua conta |
| Evolution API (você hospeda) | Software de código aberto (Apache 2.0, com condições de marca); você paga servidor e IP | Você providencia | A chave global continua existindo e abre tudo; a página oficial lida não descreve uma oferta gerenciada pelos mantenedores |
A uazapi também vende por instância, mas o site oficial não abriu nas nossas leituras de 11/11 e o preço não foi confirmado. Se o seu uso não depende de IP, uma opção mais barata pode bastar. A conta completa, com custo por instância e custos escondidos, está em quanto custa uma API de WhatsApp por número em 2026. Quem vem da Z-API pode ler alternativa à Z-API, e quem hoje hospeda a Evolution, Evolution hospedada ou contratada.
O IP brasileiro dedicado impede o bloqueio do número?
Não. O IP evita que o número apareça junto de centenas de outros num servidor compartilhado, mas o WhatsApp decide o bloqueio pelo comportamento da conta: quem escreve para quem, quantas vezes, quantas pessoas denunciam. Por isso o ritmo é limitado e a política de uso aceitável existe.
O que muda com o IP dedicado: no plano com IP, a instância sai por um IP de provedor de internet brasileiro (do tipo que uma casa ou uma empresa recebe), usado só por ela. O WhatsApp vê o número sempre no mesmo lugar. Na prova em aparelho real de 10/11/2026, feita com um IP de casa, ao parar o relé do IP o número desconectou em até 25 segundos, sem sair pelo IP do servidor, e reconectou sozinho em 3 segundos quando o relé voltou. O mesmo teste com o IP de provedor final ainda será repetido.
Troca de IP: reiniciar o relé do IP reconectou o número em cerca de 1 segundo, sem ler o QR de novo (prova em aparelho real de 10/11/2026). A troca para outro IP de provedor real ainda não foi provada, então nesse caso o WhatsApp pode pedir a leitura do QR.
Quem já tem IP próprio pode contratar o plano sem IP, mais barato. As causas reais de bloqueio estão em WhatsApp banido: causas na API e no Business.
Dá para enviar mais do que texto?
Sim: imagem, vídeo, áudio, voz, documento, figurinha, localização, contato, link e enquete, cada um com a sua rota e os mesmos nomes de campo. Mídia vai por endereço https ou em base64, com limite por tipo.
| O que enviar | Rota | Guia |
|---|---|---|
| Texto, com resposta a uma mensagem e menção | POST /messages/text | Primeiros passos |
| Imagem, vídeo, áudio, voz, documento e figurinha | POST /messages/image e as irmãs | Enviar mídia |
| Enquete, reação, editar, apagar, localização, contato, link e "digitando…" | POST /messages/poll e outras | Mensagens e ações |
| Botões de resposta e de ação (lista e carrossel não funcionam) | POST /messages/interactive | Botões |
| Cobrança PIX com código "copia e cola" e botão de copiar | POST /messages/pix | Referência |
| Bloquear, silenciar, fixar, comunidades, canais e presença (em beta) | várias | Bloquear, silenciar e comunidades |
| Status (stories), desligado por padrão (em beta) | POST /status/text e irmãs | Status |
Limites que a página de venda não esconde: imagem até 10 MB, vídeo e áudio até 16 MB, documento até 25 MB, figurinha até 1 MB; a voz depende do conversor de áudio da instância e, se ele faltar, a API responde com erro claro em vez de mandar um arquivo comum; na localização só as coordenadas seguem. Link sai como texto com o endereço, sem prévia do site (provado em 12/11/2026). Todo envio aceita ainda expires_in para mensagens temporárias. Lista (menu) e carrossel não funcionam hoje: o WhatsApp mostra "mensagem incompatível" e a API os recusa com 422 interactive_unsupported. Os botões de resposta, link, copiar e ligar funcionam (provado em 12/11/2026); a resposta da API ainda avisa que o WhatsApp pode não mostrá-los, por prudência. O status vai para todos os contatos do número, por isso vem desligado e tem teto de 3 por dia.
Como funcionam grupos, contatos e conversas?
A API administra grupos (criar, adicionar e tirar gente, promover, nome, descrição, foto, trava, link de convite, pedidos de entrada), consulta contatos (se o número tem WhatsApp, nome, foto, perfil comercial), lê o histórico que a instância guardou, com a mídia recebida disponível para baixar, e permite criar etiquetas próprias para organizar as conversas (elas ficam na ProxyBox e não aparecem no aplicativo do WhatsApp). Os guias: grupos, contatos e conversas e mídia recebida.
Ler conversas, baixar mídia recebida, consultar contatos, foto e privacidade e listar grupos foram provados em aparelho real. Ressalvas: baixar mídia antiga pode falhar; criar grupo exige ao menos 1 participante; a verificação de número não distingue o nono dígito (o envio descobre a forma certa); ações de grupo exigem que o seu número seja administrador e têm tetos. Administração de grupo segue em beta: pode mudar.
Posso agendar uma mensagem?
Sim, uma de cada vez, até 30 dias à frente e sem repetição. Qualquer envio aceita um horário futuro; a API guarda o pedido e envia na hora marcada, pelas mesmas regras de ritmo do envio comum. Não existe agenda recorrente nem envio para todos, e isso é proposital. O guia agendar uma mensagem mostra como listar e cancelar. Recurso em beta: pode mudar.
Como recebo as mensagens: aviso automático, consulta ou os dois?
Aviso automático (push). Cada aviso (mensagem recebida, entregue, lida, número que caiu ou voltou, alguém que entrou num grupo, voto em enquete, pedido de aprovação) é assinado com HMAC-SHA256 e entregue ao seu endereço https; se o seu sistema não responder, as novas tentativas saem após 1 minuto, 5 minutos, 15 minutos, 1 hora e 6 horas, e depois o aviso fica como desistido, com botão para reenviar. O painel guarda os avisos dos últimos 7 dias. A instância pode entregar no formato da ProxyBox, da Evolution ou da Z-API. Guia: aviso automático. O voto em enquete depende de o WhatsApp entregá-lo e ainda não foi provado.
Consulta (pull). Sem endereço público, o seu sistema pergunta: GET /events com cursor, espera de até 25 segundos e confirmação em POST /events/ack. Os avisos ficam 7 dias. Guia: receber por consulta.
Agrupar mensagens. Quem escreve em três mensagens seguidas gera um único aviso message.batch depois de alguns segundos de silêncio, o que ajuda bots e atendimento. Guia: agrupar mensagens.
Como ligo bots, o Chatwoot e a mídia ao meu armazenamento?
Cada instância pode ter um bot que responde sozinho: Typebot, Dify, Flowise, qualquer serviço de IA no formato da OpenAI (OpenRouter, Groq, Ollama), Claude, ou o seu fluxo no n8n ou servidor, por webhook assinado. O bot nasce desligado, responde no máximo 20 vezes por hora em cada conversa e 200 por dia, pausa quando você responde pelo celular e sai pelas mesmas travas da API. Com a aprovação humana ligada, uma pessoa lê antes de cada resposta sair. Visão geral: bots.
Para atendimento em equipe, a ponte com o Chatwoot espelha as conversas e envia as respostas dos atendentes pelo número. E o armazenamento S3 (S3, R2, Backblaze, MinIO) recebe as imagens, áudios e documentos que chegam, com o endereço no aviso. Os bots, o Chatwoot e o S3 foram testados com simuladores; nenhum foi provado contra o serviço real nem em aparelho. A página de integrações mostra o status de cada ferramenta, e os modelos prontos cobrem WooCommerce, Asaas, Hotmart, planilhas e CRMs.
Como conecto o número, e o que é a chave de acesso (passkey)?
Você lê um QR ou digita um código de pareamento, pelo painel ou pela API. Se o WhatsApp pedir a chave de acesso (passkey) do aparelho, o estado da instância avisa e a confirmação é feita no painel e no celular. O guia conectar por QR, código e passkey tem o passo a passo e os limites de tentativas.
Não tem número? O número virtual para WhatsApp é um número brasileiro com DDD, sem chip, por 30 dias e renovável. Você cria o WhatsApp no celular com ele e depois conecta a conta aqui. No painel há um combo com a API, o IP dedicado e o número numa compra só.
Como migro da Evolution ou da Z-API, uso o n8n ou um assistente de IA?
Existem duas bases de rotas de compatibilidade. No formato da Evolution, em https://proxybox.com.br/api/whatsapp/evolution: você troca o endereço e a chave, usa o slug da instância no lugar de {instance} e, nas rotas cobertas, o código antigo segue funcionando (sendText, sendButtons e whatsappNumbers provados em aparelho em 12/11/2026; sendList é recusado, porque lista não funciona). No formato da Z-API, em https://proxybox.com.br/api/whatsapp/zapi/instances/{slug}/token/{chave}, com os mesmos campos da Z-API nas rotas cobertas. Os mapas rota a rota estão em migrar da Evolution e migrar da Z-API. A da Z-API tem verificações automáticas e o send-text foi provado em aparelho em 12/11/2026; os caminhos de muitas outras rotas ainda não foram conferidos contra a Z-API.
No n8n, a API é REST: o envio sai por um nó HTTP Request e o recebimento por um nó Webhook, com fluxos prontos no guia WhatsApp no n8n, e existe um pacote de nós da ProxyBox com 89 operações e 12 modelos (instalação manual, em beta). Para Claude, Cursor e outros assistentes, há um conector (MCP) em que cada envio pede a sua confirmação: usar a API de WhatsApp no Claude e no Cursor. SDKs de Node, Python e PHP ainda não existem, e não prometemos data: veja o que há hoje.
Quais limites protegem o número?
O ritmo é limitado por instância, e o cliente só pode deixar mais devagar, nunca mais rápido. No envio, o padrão é de 10 mensagens por minuto, 500 por dia e pausa de 3 a 10 segundos entre uma mensagem e outra.
- Ações leves (reação, editar, "digitando…"): até 60 por minuto. Leituras: até 120 por minuto.
- Consultas de número: até 300 verificações por dia. Administração de grupo: tetos por hora e por dia, como 10 grupos criados por dia. Status: 3 por dia.
- Trava de contato novo. Quando o WhatsApp restringe o envio para contatos novos, a instância passa a enviar só a telefones com quem já houve conversa nos últimos 60 dias, por cerca de 6 horas. Grupos não entram nessa trava. O guia restrição 463 explica o que fazer.
- Lista de não perturbe. Telefones que pediram para parar ficam numa lista própria; enviar a eles devolve erro sem sair mensagem. Veja não perturbe e chamadas.
- Vigia de conexão. De 5 em 5 minutos a API confere se a instância conectada responde de verdade; se falhar três vezes seguidas, tenta reconectar e avisa você.
Esses limites são proteção, não garantia. A tabela completa está em erros e limites da API. Sobre a segurança da chave, dos avisos e dos dados, veja o resumo em segurança.
Quanto custa uma API de WhatsApp por número?
O preço mensal da ProxyBox, por instância, é R$ 89,90 no plano com IP brasileiro dedicado e R$ 39,90 só com a sua própria conexão (você traz um IP ISP que já tem na ProxyBox). Inclui a instância, a chave, os avisos automáticos e o suporte em português; no plano com IP, inclui também o IP dedicado. Pague com o saldo da carteira, que você recarrega por PIX. A renovação automática é opcional. O ambiente de teste (sandbox) é grátis, uma vez por conta, por 30 dias. Agências que criam muitas instâncias poderão fazê-lo por API quando a API de conta abrir; ainda é "em breve".
Quanto mais instâncias você tem, menos cada uma custa: a partir de 5 instâncias, R$ 79,90 cada; a partir de 10, R$ 74,90 (no plano com IP). A faixa vale na compra e na renovação, pelo total de instâncias pagas que você mantém. Você escolhe onde fica o IP dedicado: o Brasil é o recomendado e o padrão. Outros lugares, como Estados Unidos, Reino Unido e Portugal, abrem aos poucos e podem aumentar o risco de bloqueio, principalmente se o número do WhatsApp for de um país diferente do IP.
O que saber antes de contratar
- É API não oficial. Ela funciona como um aparelho conectado ao WhatsApp e não é um produto da Meta. Os termos do WhatsApp (consultados em 10/11/2026) não preveem esse tipo de acesso, e por isso o bloqueio de número é um risco real e permanente.
- O bloqueio pode acontecer com qualquer número. Os motivos mais comuns são denúncias, mensagem para quem não conhece você, volume alto em pouco tempo e conteúdo repetido. A ProxyBox não tem como evitar nem desfazer um bloqueio, e não reembolsa por bloqueio.
- Use um número que você possa perder, dedicado ao envio, e não o telefone pessoal nem o número principal do negócio. O chip precisa continuar ativo no celular do número.
- Peça consentimento. Escreva só para quem espera receber e atenda quem pedir para parar. A sessão do número fica guardada na ProxyBox enquanto a instância existir (veja a política de privacidade).
- Bots e IA respondem por você. Teste antes, use a aprovação humana na estreia e lembre que o texto da conversa vai para o serviço de IA que você escolher.
Onde ficam a especificação, o Postman e o status?
Em endereços públicos da própria ProxyBox: /api-whatsapp/openapi.json (OpenAPI 3.1), /api-whatsapp/postman.json (coleção para Postman, Insomnia e Bruno) e /api-whatsapp/status (estado do serviço e incidentes). O guia especificação, Postman e status mostra como importar. Glossário para os termos.
O que a API não resolve?
- Não garante entrega nem leitura. A mensagem depende do WhatsApp e do destinatário; o aviso de entrega mostra o que o WhatsApp informou.
- Não faz mensagem em massa. Não existe lista de transmissão, envio para todos nem agendamento que se repete. O status ("stories") é a única publicação que alcança muitos contatos, vem desligado e tem teto. Publicação em canal, comunidades, catálogo, bloquear contato e chamadas de voz também ficam de fora.
- Não oferece WebSocket nem filas (RabbitMQ, SQS, Kafka). O aviso assinado e a consulta com espera cobrem o mesmo uso sem infraestrutura persistente.
- Não é um sistema de atendimento nem um CRM. É a ponte entre o WhatsApp e o seu sistema; para atendentes e funil, use o Chatwoot ou o seu CRM.
- Não cria número. A API conecta uma conta de WhatsApp que já existe no seu celular. Se falta o número, ele é vendido à parte: veja o número virtual para WhatsApp. Para um código de cadastro em outro aplicativo, veja o número virtual para SMS.