Como ler este histórico
- Estável quer dizer provado em uso real e com compromisso de não mudar sem aviso. Hoje, só o que veio na v1.0.
- Provado em aparelho real quer dizer que a rota foi usada em um número real em 10/11/2026 (ela aparece como
stableemGET /instance). - Beta (beta) quer dizer que a rota existe, tem teste automatizado, mas ainda não foi provada em número real. Pode mudar nome de campo ou comportamento.
- Cada rota diz a sua situação em
GET /instance, no campocapabilities, comstatusigual astableoubeta. - Mudanças que quebram código existente serão avisadas aqui, com data, antes de entrar. Acrescentar campo na resposta não é mudança que quebra: programe o seu código para ignorar campos que não conhece.
Provado em aparelho real em 14/11/2026
Teste feito pelo dono, em um número real, com um IP brasileiro de provedor. Funcionou: conexão por código de pareamento (o aparelho aparece como "ProxyBox"); bloquear, desbloquear e listar bloqueados; fixar mensagem; convite de evento; quem adiciona membros ao grupo e aprovação de entrada; voto em enquete (poll.vote), toque em botão de resposta (message.received com type: button_reply) e mensagens de texto e foto recebidas, lidos pela consulta de avisos (GET /events); e a aprovação humana pela API (envio pendente, aprovado e rejeitado).
Não funcionou e foi retirado: botão PIX nativo (o WhatsApp aceita o envio e a mensagem não chega).
Voltaram a funcionar (beta): mudar o recado do perfil e criar comunidade, depois da atualização do motor, provados em 14/11/2026. Vincular grupo a uma comunidade e listar os grupos dela também foram provados no aplicativo em 14/11/2026; a lista pode levar alguns segundos para refletir a mudança.
Voltou de outro jeito: a cobrança PIX agora vai como mensagem com o código "copia e cola" e o botão "Copiar código PIX" (POST /messages/pix), provada em aparelho real em 14/11/2026.
Aceitas pelo WhatsApp, sem conferência na tela: silenciar conversa, marcar como não lida, privacidade (repetindo o valor atual), criar e silenciar canal e apagar conversa.
Provado em aparelho real em 12/11/2026
Teste feito pelo dono, em um número real, pela API pública. Funcionou: texto, texto temporário (expires_in), texto citando (reply_to), imagem por base64, documento (PDF), voz (PTT) e áudio como arquivo, figurinha, localização, contato, link (sai como texto com o endereço), enquete, botões de resposta, botões 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 (409 opted_out e voltar a enviar depois), aprovação humana (202 pendente, aprovar envia, rejeitar descarta), agendamento de uma mensagem (chegou na hora), etiquetas, ajustes e proteções (um IP permitido que deixaria o cliente de fora é recusado; status desligado devolve 403), eventos por consulta (fila), as rotas no estilo da Evolution (sendText, sendButtons, whatsappNumbers) e a da Z-API (send-text).
Não funciona: lista (menu) e carrossel. O WhatsApp mostra "mensagem incompatível"; a API os recusa com 422 interactive_unsupported (também sendList da Evolution e send-option-list e send-carousel da Z-API). Veja botões.
Ainda não provado (segue em beta): botão de localização, vídeo, status (stories), reação e voz recebidas, recusa de chamada, S3, Chatwoot, bots e imagem por URL.
Mudou: GET status da Z-API devolve {connected, smartphoneConnected, session, error}. Clientes HTTP com o agente padrão do urllib do Python podem receber 403 do Cloudflare: use requests ou defina um User-Agent (erros e limites).
v1.4 (14/11/2026)
- 16 rotas novas, em beta (beta): bloquear e desbloquear contato e listar bloqueados; silenciar conversa, marcar como não lida e apagar conversa; fixar mensagem; mudar a privacidade; listar, colocar e tirar grupos de uma comunidade; criar e silenciar canal; quem adiciona membros e aprovação de entrada em grupo; convite de evento. Detalhes na referência.
- Painel: nova aba "Mais ações" com essas rotas.
- Receber avisos por SSE (beta):
GET /events/streamempurra os mesmos avisos deGET /events, em conexões de até 25 segundos que se renovam sozinhas. Veja receber por consulta. - Presença (beta):
POST /presence/subscribeacompanha se um contato está online e o avisopresence.updatechega comfrom,state(onlineouoffline) e, quando a pessoa deixa,last_seen. Só chega de quem você assinou, e não chega de quem escondeu o "online" nas configurações do WhatsApp. O aviso de "offline" foi provado em aparelho real em 14/11/2026; o de "online" e olast_seendependem de a pessoa deixar essas informações visíveis. - Vídeo redondo (beta):
POST /messages/videocomround: trueenvia o vídeo como mensagem de vídeo (a bolinha). Provado em aparelho real em 14/11/2026. - Apagar status e etiqueta de membro (beta):
DELETE /status/{id}ePOST /groups/{group}/member-label. A etiqueta de membro foi provada em aparelho real em 14/11/2026 (aparece ao lado do nome, na lista de membros); apagar status ainda não foi provado. - Guia novo: migrar da Wafly.
- IP da instância: no plano com o seu próprio IP, a ProxyBox avisa 3 dias antes se o IP vai vencer sem renovação automática e avisa de novo quando ele vence; o painel mostra o motivo, e a instância e a chave continuam as mesmas. Se você trocar o IP por outro, a instância passa a usar o IP novo sozinha, sem ler o QR de novo.
- Aviso ao cliente: se o número ficar desconectado por mais de 10 minutos, a ProxyBox avisa por e-mail e no painel.
- Nome no WhatsApp: o aparelho conectado aparece como "ProxyBox", sem número de versão do motor.
- Limites desta versão: adicionar contato na agenda, vídeo redondo e catálogo de produtos não são suportados. Testados em 14/11/2026 e retirados: o botão PIX nativo (o WhatsApp aceita o envio e a mensagem não chega; no lugar existe a cobrança com copia e cola).
v1.3 (13/11/2026)
- "Digitando…" antes do texto: ajuste
humanizeda instância e campohumanizenoPOST /messages/text. Até 8 segundos, com variação. Instâncias novas vêm com o ajuste ligado. Nada muda para quem não usa. - Placar de risco:
GET /instancepassa a trazerrisk(Tranquilo, Atenção ou Alto risco, com motivos e dicas) ehumanize. O painel ganha o cartão "Sinais do número", e o dono recebe um aviso por dia quando a instância chega a Alto risco (ajusterisk_alert). São sinais, não garantia.
v1.2 (12/11/2026)
Catálogo de 88 operações (75 na v1.1). Tudo em beta; nada liga sozinho; a chave whatsapp_api segue desligada até o lançamento.
Envio e conteúdo
- Botões de resposta e de ação:
POST /messages/interactive(provados em 12/11/2026). Lista e carrossel não funcionam:422 interactive_unsupported. Guia. - Status (stories):
POST /status/text,/status/image,/status/video; desligado por padrão, 3 por dia. Guia. - Etiquetas próprias:
/labels, eGET /chats?label=. Guia.
Receber
- Modo de consulta:
delivery_mode,GET /events(comwaitde até 25 s) ePOST /events/ack. Guia. - Agrupamento de mensagens seguidas:
buffer_seconds,buffer_replacee o avisomessage.batch. Guia. - Novos avisos:
message.batch,poll.vote(depende do WhatsApp entregar o voto),approval.requestedeapproval.decided;typeigual abutton_reply;media.urlemedia.storedquando o S3 está ligado; formato de avisozapi. Aviso automático.
Controle e segurança
- IPs permitidos da chave:
api_allowlist, erro403 ip_not_allowed. Guia. - Equipe com papéis de visualizador e operador (pelo painel). Guia.
- Aprovação humana:
approval_mode, rotas/approvals. Guia. - Atividade e métricas:
GET /activity,GET /metrics. Guia. - Sandbox grátis: 1 por conta, 30 dias, 100 envios por dia,
POST /sandbox/simulate/receive. Guia.
Integrações
- Bots por instância: Typebot, Dify, Flowise, OpenAI e compatíveis, Claude, n8n e webhook. Visão geral.
- Chatwoot. Guia.
- Mídia recebida no seu S3, R2, Backblaze ou MinIO. Guia.
- Rotas no estilo da Z-API (
/api/whatsapp/zapi/...). Mapa.sendButtonsesendStatusda Evolution mapeados na base compatível (sendButtonsprovado;sendListrecusado). Mapa. - Pacote de nós do n8n com 89 operações e 8 modelos (instalação manual). Guia.
- 13 modelos prontos e a página de integrações.
- Conector MCP: as ferramentas das rotas novas entram quando o pacote do conector for atualizado; a lista atual está na página do MCP.
- API de conta (criar e cancelar instâncias por API): construída e desligada; em breve. Página.
Erros novos: interactive_unsupported, ip_not_allowed, status_disabled, sandbox_expired, not_available, too_many_waiters, approval_queue_full, approval_chat_full, approval_media_url_only. Tabela em erros e limites.
v1.1 (11/11/2026)
Envio
- Novas rotas de mídia: imagem, vídeo, áudio (com mensagem de voz), documento e figurinha, por endereço https ou base64. Veja enviar mídia.
- Localização, contato, link, enquete e encaminhar. Reação, edição, apagar (para todos ou só na instância), marcar como lida e ouvida, estrela, "digitando…", presença e recusar chamada. Veja mensagens e ações.
reply_toementionsnos envios que fazem sentido.expires_inem todo envio, para mensagem temporária de 24 horas, 7 dias ou 90 dias.schedule: agende uma mensagem, até 30 dias, comGET/DELETEem/schedules. Veja agendar.- O destino
toaceita grupo e a forma@s.whatsapp.net. A resolução do nono dígito é automática: número e identidade.
Leitura
- Contatos: verificar números, perfil, foto, perfil comercial, lista e privacidade. Contatos.
- Conversas e mensagens, baixar mídia recebida, fixar, arquivar, mensagens temporárias e pedir histórico. Conversas e mídia recebida.
- Grupos (criar, participantes, nome, descrição, foto, travas, link, pedidos de entrada) e canais (consultar e seguir). Grupos.
Instância
GET /instance/qr,POST /instance/pair-code,POST /instance/restart,POST /instance/logout;passkey,signaleqr_hintemGET /instance. Conectar.GET /health: ida e volta real ao WhatsApp, com o campodeafpara "conectado, mas sem resposta".- Vigia de conexão a cada 5 minutos.
- Lista de não perturbe e ajustes de chamada. Não perturbe e chamadas.
- Trava de contato novo (
409 new_contacts_locked). Restrição 463.
Avisos
- Novos eventos:
group.message.received,group.message.sent,group.updated,message.reaction,message.edited,message.revoked,call.receivedemessage.scheduled_failed. message.receivedcomtypereal,media,reply_toegroup.- Formato
evolutionpor instância. Aviso automático.
Compatibilidade e ferramentas
- Base de rotas no estilo da Evolution v2. Migrar da Evolution.
- Conector MCP com 66 ferramentas de WhatsApp. Claude e Cursor.
- OpenAPI 3.1, coleção do Postman e página de status. Especificação e status.
Erros novos: new_contacts_locked, opted_out, media_unavailable, media_too_large, unsupported, not_found, not_group_admin, forbidden, schedule_in_past, schedule_too_far, schedule_limit, not_cancelable, already_connected, confirmation_required, optout_limit e timeout. Tabela em erros e limites.
v1.0 (10/11/2026)
GET /instance: estado, número, limites e uso do dia.POST /messages/text: texto de 1 a 4.096 caracteres, comIdempotency-Key.- Limites: 10 por minuto, 500 por dia, pausa de 3 a 10 segundos.
- Avisos assinados (HMAC-SHA256):
message.received,message.sent,message.status,connection.updated,qr.updated,number.logged_outenumber.restricted, com fila e novas tentativas. - Erros:
invalid_key,instance_paused,not_connected,invalid_request,rate_limited,daily_limit,engine_unavailable,instance_preparingenumber_not_on_whatsapp.
O que ficou de fora, de propósito?
Mensagem em massa, lista de transmissão, envio para todos os contatos, agenda recorrente, bloquear contato, comunidades, catálogo, publicar em canal, chamada de voz pela API, vídeo redondo, localização ao vivo, fixar mensagem e evento. Também ficam de fora WebSocket e filas (RabbitMQ, SQS, NATS, Kafka): o aviso assinado e a consulta com espera cobrem o uso. SDKs oficiais ainda não existem (SDKs). Alguns itens podem entrar depois; a decisão é registrada aqui.
O que já foi provado em aparelho real, e o que não?
Provado em 10/11/2026: texto, imagem, documento, voz, áudio como arquivo, figurinha, localização, contato, enquete, "digitando…", reação (e remover), editar, marcar como lida, encaminhar, apagar para todos, ler conversa, baixar mídia recebida, contatos, perfil, foto, privacidade, listar grupos e conversas; reiniciar o relé do IP reconecta em cerca de 1 segundo sem QR; sem o relé, o número desconecta sem sair pelo IP do servidor.
Ainda em beta (v1.1): vídeo, link (sai como texto com o endereço, sem prévia), estrela (instável), apagar só na instância, áudio ouvido, presença, recusar chamada, verificar números (não distingue o nono dígito), perfil comercial, mudar nome e foto, fixar, arquivar, mensagens temporárias, pedir histórico, criação e administração de grupos (criar exige ao menos 1 participante), canais, agendamento, pareamento por QR, chave de acesso, não perturbe, ajustes de chamada e a troca para outro IP real de provedor. Toda a v1.2 está em beta, sem prova em aparelho.
Veja também
- Referência da API de WhatsApp v1.2: rotas
- Botões no WhatsApp via API: resposta e ação
- Bots de WhatsApp pela API: tipos e limites
- Migrar da Z-API: mapa de rotas
Índice completo: índice dos guias. Sobre o produto: a API de WhatsApp com IP de provedor.
Autoria: equipe técnica da ProxyBox. Atualizado em 12/11/2026. Data da v1.2: 12/11/2026; da v1.1: 11/11/2026; a v1.0 foi a primeira versão desenhada, em 10/11/2026. A API ainda não está aberta ao público; este histórico acompanha o que está em preparo.