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

Documentação da API de WhatsApp: por onde começar e o que ler depois

Mapa dos guias da API de WhatsApp da ProxyBox, em ordem de leitura e por perfil, com o que já foi provado e o que está em beta.

10 min de leitura Atualizado em 14 de novembro de 2026
Resposta curta
Esta é a documentação da API de WhatsApp da ProxyBox, organizada em seis grupos: começar, enviar e receber, avisos e controle, integrações, bots e IA, e conta e migração. Se você é desenvolvedor, comece pelos primeiros passos; se quer testar sem número, pelo sandbox. Tudo o que chegou na versão 1.2 está em beta e vem marcado.

A API não é a oficial da Meta: o WhatsApp pode bloquear qualquer número, e a ProxyBox não reembolsa por bloqueio. Para conhecer o produto, o IP brasileiro dedicado e os planos, veja a página da API de WhatsApp.

Como leio a coluna "Situação"?

Cada recurso tem uma situação honesta, para você decidir quanto confiar:

  • Provado quer dizer que a rota foi usada em um número real, em aparelho, em 10/11/2026 e, pela API pública, em 12/11/2026 (veja o histórico de versões para a lista de 12/11): texto, imagem, documento, voz, áudio como arquivo, figurinha, localização, contato, enquete, reação, editar, apagar para todos, ler conversas, baixar mídia recebida, contatos, foto, perfil e listar grupos.
  • Beta quer dizer que o recurso já funciona, está em fase de testes e pode mudar. Isso vale para todas as novidades da versão 1.2.
  • Em breve quer dizer que ainda não está disponível.
  • Consulta é página de referência, sem recurso por trás.

Por onde começo, conforme o meu perfil?

Sou desenvolvedor

  1. Primeiros passos: a primeira mensagem.
  2. Sandbox: teste sem número e sem pagar.
  3. Aviso automático: receba mensagens e confira a assinatura.
  4. Erros e limites e referência: o que cada rota devolve.
  5. Segurança e IPs permitidos: proteja a chave antes de ir para produção.

Sou agência e gerencio vários números

  1. Primeiros passos para uma instância de teste.
  2. Equipe, papéis e métricas para dar acesso sem compartilhar a chave e acompanhar cada número.
  3. Chatwoot para o atendimento em equipe.
  4. Criar instâncias por API, para agências, ainda está em breve e não tem página.

Tenho uma loja virtual

  1. Modelos prontos: pedido pago no WooCommerce, cobrança, compra aprovada e formulário.
  2. Integrações: Woo, Asaas, Hotmart, Kiwify e Mercado Pago, com o status de cada uma.
  3. Agendar uma mensagem para lembretes.
  4. Não perturbe e chamadas: quem pede para parar não recebe mais nada.

Quero responder clientes automaticamente

  1. Bots de WhatsApp: escolha entre Typebot, Dify, Flowise, IA ou o seu fluxo.
  2. Aprovação humana: uma pessoa lê antes de a resposta sair.
  3. Receber por consulta e agrupar mensagens: o bot responde à frase completa.
  4. Botões: de resposta e de ação funcionam; lista (menu) e carrossel não.

Já uso a Evolution ou a Z-API

Migrar da Evolution, migrar da Z-API e migrar da Wafly trazem o mapa rota a rota. Para comparar preço, IP e recursos antes de decidir, leia alternativa à Z-API e Evolution hospedada ou contratada.

Qual é o mapa completo, em ordem de leitura?

Começar

Página O que resolve Situação
Enviar a 1ª mensagem pela API de WhatsApp Criar a instância, conectar e mandar a primeira mensagem em quatro passos. Texto provado
Conectar o WhatsApp à API: QR, código, passkey Ler o QR, usar o código de pareamento e tratar a chave de acesso. Código provado; QR e passkey em beta
Sandbox da API de WhatsApp: testar sem número Ambiente de teste, sem número e sem enviar ao WhatsApp. Beta
Nono dígito e @lid na API de WhatsApp Nono dígito, grupos e o identificador @lid. Nono dígito provado
Erros e limites da API de WhatsApp Tabela de erros, tetos por categoria e boas práticas. Misto
Erro 463 do WhatsApp (contato novo): o que fazer O que fazer quando o WhatsApp restringe contatos novos. Beta
Glossário da API de WhatsApp: termos e siglas Os termos da documentação, de A a Z. Consulta
Versões da API de WhatsApp: v1.0, v1.1 e v1.2 O que mudou em cada versão. Consulta

Enviar e receber

Página O que resolve Situação
Enviar imagem, vídeo e áudio no WhatsApp via API Imagem, vídeo, áudio, voz, documento e figurinha. Imagem, documento, voz e figurinha provados; vídeo em beta
Reagir, editar, apagar e status: API de WhatsApp Enquete, reação, editar, apagar, ler, 'digitando' e status (stories). Provado, exceto estrela, presença e status (em beta)
Botões e listas no WhatsApp via API Botões de resposta, link, copiar e ligar com POST /messages/interactive; lista e carrossel não funcionam. Envio provado em 12/11/2026; lista e carrossel não funcionam
Verificar número com WhatsApp pela API Conferir se o número tem WhatsApp e consultar perfil. Parte provada
Criar e administrar grupos de WhatsApp pela API Criar e administrar grupos, convites e pedidos de entrada. Listar provado; o resto em beta
Bloquear, silenciar e administrar grupos pela API Bloquear contatos, silenciar e apagar conversas, fixar mensagem, privacidade, grupos, comunidades, canais e evento. Beta
Ler conversas e baixar mídia no WhatsApp via API Ler o histórico, baixar o que o cliente mandou e etiquetar conversas. Leitura provada; etiquetas provadas em 12/11/2026
Agendar mensagem de WhatsApp pela API Uma mensagem por vez, até 30 dias à frente. Agendar uma mensagem provado em 12/11/2026

Avisos e controle

Página O que resolve Situação
Webhook da API de WhatsApp: eventos e assinatura Receber os avisos: cada evento em JSON e a assinatura. Mensagem provada; v1.2 em beta
Receber WhatsApp sem webhook e agrupar mensagens Receber sem endereço público (GET /events) e agrupar mensagens seguidas. Consulta (fila) provada em 12/11/2026; agrupar em beta
Segurança da API de WhatsApp: chave e IPs Chave, IPs permitidos, avisos assinados, dados guardados e o que fica de fora. IP permitido provado em 12/11/2026; sem auditoria externa
Aprovação humana de mensagens da API de WhatsApp Segurar o que bots e IA enviam até uma pessoa liberar. Provado em 12/11/2026
Não perturbe e recusar chamadas: API de WhatsApp Lista de não perturbe e recusa automática de chamadas. Não perturbe provado em 12/11/2026; recusa de chamada em beta
Equipe, papéis e métricas da API de WhatsApp Dar acesso a pessoas sem compartilhar a chave e acompanhar a atividade. Beta

Integrações

Página O que resolve Situação
Integrações da API de WhatsApp: n8n, Make, Zapier Cartão por ferramenta e o status honesto de cada uma. Hub; tudo em beta
13 modelos para a API de WhatsApp (Woo, Asaas) 13 modelos HTTP: Woo, Asaas, Hotmart, Sheets, CRM e IA. Modelos não testados em terceiros
WhatsApp no n8n: enviar e receber com a API Enviar e receber no n8n com os nós que já existem. Nós padrão do n8n
Nós n8n para a API de WhatsApp: instalar Pacote de nós da ProxyBox e 8 modelos de fluxo. Beta; não rodou num n8n real
Chatwoot com WhatsApp: ligar pela API Atendimento em equipe espelhado no Chatwoot. Beta; não provado com Chatwoot real
Guardar mídia do WhatsApp no S3, R2 ou MinIO Guardar a mídia recebida no seu bucket. Beta
MCP do WhatsApp para Claude e Cursor Operar a API por um assistente de IA, com confirmação. Beta
SDKs, OpenAPI e Postman da API de WhatsApp SDKs, OpenAPI 3.1, Postman e a página de status. SDKs não existem ainda; OpenAPI e Postman disponíveis

Bots e IA

Página O que resolve Situação
Bots de WhatsApp pela API: tipos e limites Visão geral: tipos, gatilhos, pausa e limites. Beta
Typebot no WhatsApp: ligar um fluxo à API Fluxo do Typebot respondendo pela instância. Beta
Bot de IA no WhatsApp com OpenAI, Groq, Ollama OpenAI, OpenRouter, Groq e Ollama. Beta
Bot de WhatsApp com Claude (Anthropic) Claude, da Anthropic. Beta
Bot de WhatsApp por n8n ou webhook próprio Seu fluxo n8n ou servidor decide a resposta. Beta
Dify e Flowise no WhatsApp: ligar um fluxo Dify e Flowise: app ou fluxo de IA. Beta

Conta e migração

Página O que resolve Situação
Migrar da Evolution API: mapa de rotas Mapa de rotas para quem vem da Evolution. sendText, sendButtons e whatsappNumbers provados em 12/11/2026
Migrar da Z-API: mapa de rotas Mapa de rotas para quem vem da Z-API. send-text provado em 12/11/2026; caminhos não confirmados
OpenAPI, Postman e status Onde ficam a especificação, a coleção do Postman e a página de status. Beta
Migrar da Wafly: mapa de rotas O que continua igual trocando a base e o que muda de nome. Beta
Referência da API de WhatsApp: todas as rotas Todas as rotas com exemplo, incluindo as da versão 1.4. Misto

O que a documentação não cobre?

  • Mensagem em massa. Não existe lista de transmissão nem envio para todos; a política de uso aceitável proíbe.
  • WebSocket e filas (RabbitMQ, SQS, Kafka). O aviso assinado e a consulta com espera cobrem o uso.
  • SDKs oficiais. Ainda não existem; veja o que há hoje em SDKs, OpenAPI e Postman.
  • Garantia contra bloqueio. Nenhum guia promete isso. As causas reais estão em WhatsApp banido: causas na API e no Business.

Como a documentação é mantida?

Cada página tem a data de atualização e o contrato por trás: o catálogo da versão 1.4, com 110 operações. Os exemplos de código foram escritos contra a API, que tem testes automáticos, mas não foram executados contra a API aberta ao público, porque ela ainda não abriu. Os formatos de terceiros (Typebot, Dify, Flowise, Chatwoot, Asaas, Z-API e outros) foram lidos nas páginas oficiais deles na data indicada em cada guia, e os pontos não confirmados aparecem escritos. Se você achar uma diferença entre a documentação e o comportamento da API, avise o suporte: durante o teste, a documentação segue a API.

Autoria: equipe técnica da ProxyBox. Atualizado em 12/11/2026, contra o catálogo da versão 1.2.

Perguntas frequentes

Por onde começo se nunca usei a API?
Pelos primeiros passos. Em dez minutos você cria a instância, conecta o número e envia a primeira mensagem. Se preferir testar sem número e sem pagar, comece pelo sandbox.
O que já foi provado em um número de verdade?
Em 10/11/2026 e 12/11/2026 (pela API pública): texto, imagem, documento, voz, áudio, figurinha, localização, contato, enquete, reação, editar, apagar para todos, ler conversas, baixar mídia recebida, contatos, foto, perfil e listar grupos. O restante da versão 1.2 está em beta; lista e carrossel de botões não funcionam.

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