Empresa brasileira · Entrega automática · Suporte em português Seg a sex, 9h as 18h · PIX em reais
ProxyBox
API de WhatsApp · Conta e migração

Como migrar da Evolution API para a ProxyBox: mapa rota a rota

Mapa das rotas da Evolution API v2 para a ProxyBox: o que não migra, base compatível, erros, avisos no formato dela e botões.

12 min de leitura Atualizado em 14 de novembro de 2026

Recurso em beta: pode mudar. A base compatível com a Evolution e o formato de aviso evolution são da versão 1.1; a versão 1.2 acrescentou bots, Chatwoot, S3 e rotas no estilo da Z-API (veja migrar da Z-API). A base foi escrita a partir do código da Evolution 2.3.7; ainda não foi comparada com uma instalação real dela.

Resposta curta: para migrar, troque o endereço base por https://proxybox.com.br/api/whatsapp/evolution, troque o cabeçalho apikey pela chave da instância ProxyBox e use o slug da instância no lugar de {instance}. Corpos, nomes de campo e respostas seguem a Evolution v2 nas rotas cobertas; o que não existe responde 404 em português.

Quem já usa a Evolution tem código escrito para ela: um nó de n8n, um script, um sistema de pedidos. Este guia mostra como levar isso para a ProxyBox sem começar do zero.

O que não migra, antes de tudo?

Antes de qualquer mapa de rotas, o que não vem junto, para você não descobrir no meio da migração:

  • WebSocket, RabbitMQ, SQS, NATS, Kafka e Pusher. Não existem. O aviso assinado e a consulta com espera cobrem o recebimento, mas um fluxo que consome uma fila precisa ser refeito.
  • A configuração das integrações pelas rotas da Evolution (/chatwoot/set, /typebot, /openai e semelhantes). Chatwoot, Typebot, Dify, Flowise e OpenAI existem, mas são configurados na ProxyBox (bots e Chatwoot), e estão em beta.
  • Criar e apagar instância por API, a chave global do servidor e o controle do servidor e dos dados: aqui a instância nasce no painel e a chave abre uma instância só.
  • sendList (menu) e carrossel: o WhatsApp mostra "mensagem incompatível" e a rota responde 422 interactive_unsupported. Também não existem sendTemplate e sendPtv.
  • Rotas sem equivalente, que respondem 404 em português, e o ritmo sem limite: aqui valem 10 mensagens por minuto, 500 por dia e a trava de contato novo.

Quem depende de qualquer um desses pontos deve avaliar com calma; a página Evolution hospedada ou contratada compara os dois caminhos.

Quando faz sentido migrar?

Faz sentido quando você cansou de manter o servidor, a atualização e o IP, quer um IP brasileiro de provedor dedicado por número sem montar proxy, ou quer uma chave por número. Para quem prefere continuar na Evolution, o proxy para Evolution API resolve só o IP.

Não faz sentido se o fluxo depende de filas e transportes da Evolution (RabbitMQ, SQS, NATS, Kafka, Pusher, WebSocket): eles não existem na ProxyBox, que oferece o aviso assinado e a consulta com espera. As integrações de Chatwoot, Typebot, Dify, Flowise, OpenAI e armazenamento S3 passaram a existir na versão 1.2, mas são configuradas na ProxyBox (painel ou /integrations), não pelas rotas /chatwoot/set e semelhantes da Evolution; veja bots e Chatwoot. Também ficam de fora a mensagem em massa e a publicação em canal.

Quais são os dois caminhos?

1. Base compatível. Em https://proxybox.com.br/api/whatsapp/evolution, as rotas têm o formato da Evolution. A chave é a da instância (pbwa_…, também aceita Authorization: Bearer), e {instance} é o slug que aparece no painel e em GET /instance. O slug precisa ser o dono da chave; outro slug devolve 404, e a chave nunca alcança outra instância.

2. Rotas nativas. A base https://proxybox.com.br/api/whatsapp/v1, descrita nos outros guias, com nomes de campo simples e iguais em todas as rotas. É a melhor escolha para código novo e para o que a Evolution não tem (agendamento, consultas de perfil, não perturbe).

As duas têm as mesmas travas: ritmo por minuto e por dia, pausa entre mensagens, trava de contato novo e limites de consulta e de grupo. A Evolution não limita; aqui, passou do limite, volta 429 ou 409.

Vai trocar de provedor? Rode as suas chamadas no sandbox antes de mudar a URL: é grátis e nada sai para o WhatsApp.

Testar grátis

O que muda no corpo das chamadas?

Na Evolution Na ProxyBox nativa Na base compatível
number to number, como na Evolution
quoted.key.id reply_to quoted, como na Evolution
mentioned, mentionsEveryOne mentions ("everyone" para todos) como na Evolution
mediatype, media, fileName a rota define o tipo; media é objeto media é endereço https ou base64; mimetype é só informativo
delay não existe; a pausa é automática (3 a 10 s) aceito: soma uma pausa extra de até 5 s; não mostra "digitando…"
key com remoteJid, fromMe, id id na rota e chat no corpo como na Evolution

Dois exemplos do mesmo texto:

bash
# Evolution
curl -X POST "https://seu-servidor/message/sendText/minha-instancia" \
  -H "apikey: CHAVE_DA_EVOLUTION" -H "Content-Type: application/json" \
  -d '{"number":"5547999999999","text":"Olá!"}'

# ProxyBox, base compatível (troca endereço e chave; slug no lugar do nome)
curl -X POST "https://proxybox.com.br/api/whatsapp/evolution/message/sendText/atendimento-da-loja" \
  -H "apikey: pbwa_SUA_CHAVE" -H "Content-Type: application/json" \
  -d '{"number":"5547999999999","text":"Olá!"}'

# ProxyBox, rota nativa
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/messages/text" \
  -H "apikey: pbwa_SUA_CHAVE" -H "Content-Type: application/json" \
  -d '{"to":"5547999999999","text":"Olá!"}'

Como ficam as rotas de mensagens?

Respostas de envio no formato messageRaw da Evolution, com status HTTP 201. PENDING significa aceita na fila de envio, não "entregue": a entrega chega por messages.update.

Evolution v2 ProxyBox nativa Diferença na base compatível
POST /message/sendText POST /messages/text Número com +, espaço, traço ou grupo @g.us
POST /message/sendMedia /messages/image, /video, /document Sem mediatype, deduz de mimetype. Envio por arquivo (multipart) é recusado com 400
POST /message/sendWhatsAppAudio /messages/audio (voice verdadeiro) Sem conversor de áudio no servidor: 501
POST /message/sendSticker /messages/sticker
POST /message/sendLocation /messages/location name e address não são enviados; aqui são opcionais
POST /message/sendContact /messages/contact Só o primeiro contato é enviado; a resposta leva o cabeçalho X-ProxyBox-Notice
POST /message/sendPoll /messages/poll name, values e selectableCount viram question, options e max_answers
POST /message/sendReaction /messages/{id}/reaction Reação vazia remove
DELETE /chat/deleteMessageForEveryone /messages/{id}/revoke Aceita também o caminho message/
POST /chat/updateMessage /messages/{id}/edit Até 15 minutos; aceita PUT e POST
sendButtons POST /messages/interactive Funciona na base compatível (provado em aparelho real em 12/11/2026): botões de resposta, link, copiar e ligar
sendList — Recusado: 422 interactive_unsupported (lista não funciona hoje)
sendStatus POST /status/* Mapeado; precisa ligar status_enabled; não provado em aparelho
sendTemplate, sendPtv Não existem 404 em português

Como ficam botões, listas e status?

Resposta curta: sendButtons funciona (provado em aparelho real em 12/11/2026), sendList não funciona e é recusado, e sendStatus está mapeado mas não foi provado.

Evolution Na ProxyBox Situação
sendButtons {number, title, description, footer, buttons[]} Vira POST /messages/interactive: to = number; body = description (com o title em negrito antes, se houver); footer; botão reply vira {type:"reply", id, text:displayText}, url vira {type:"url", text, url}, call vira {type:"call", text, phone}, copy vira {type:"copy", text, code}; botão pix não existe Provado em 12/11/2026
sendList Recusado com 422 interactive_unsupported O WhatsApp mostra "mensagem incompatível"
sendStatus {type, content, caption} Vira POST /status/text, /status/image ou /status/video Precisa ligar status_enabled (403 status_disabled até lá); 3 por dia; não provado

Também foram provados na base compatível, em 12/11/2026, sendText e whatsappNumbers. Lembre que o status vai para todos os contatos do número. Veja botões e status. Quando a resposta de um botão chega, o aviso message.received leva type igual a button_reply; no formato evolution ele vira buttonsResponseMessage dentro de messages.upsert. O aviso do toque recebido ainda não foi provado em aparelho.

Como ficam conversas, contatos e grupos?

Evolution v2 ProxyBox nativa Diferença na base compatível
POST /chat/whatsappNumbers POST /contacts/check Até 50 números; conta nos 300 por dia
POST /chat/markMessageAsRead POST /messages/{id}/read Até 30 por chamada; mensagens suas são puladas
POST /chat/sendPresence POST /typing e POST /presence recording aparece como "digitando"
POST /chat/fetchProfilePictureUrl GET /contacts/{phone}/avatar Sem foto: null
POST /chat/findMessages GET /chats/{chat}/messages Exige where.key.remoteJid: sem ele, 400
POST /chat/findChats GET /chats Até 100; sem última mensagem nem não lidas
POST /chat/getBase64FromMediaMessage GET /messages/{id}/media?as=json Exige a conversa; até 16 MB; mídia antiga pode falhar
POST /group/create POST /groups subject até 25 caracteres; conta nos 10 grupos por dia
GET /group/fetchAllGroups GET /groups Com participantes, só dos 30 primeiros
GET /group/findGroupInfos e /group/participants GET /groups/{id} Sem dono, data, foto nem comunidade
POST /group/updateParticipant /groups/{id}/participants/add, remove, promote, demote Até 50; falha por pessoa vem como "400"
POST /group/updateGroupSubject, updateGroupDescription, updateGroupPicture PUT /groups/{id}/name, topic, photo
POST /group/updateSetting PUT /groups/{id}/announce e locked
GET /group/inviteCode GET /groups/{id}/invite-link
POST ou DELETE /group/leaveGroup POST /groups/{id}/leave
inviteInfo, acceptInviteCode, revokeInviteCode, sendInvite, toggleEphemeral existem só na nativa (preview, join, invite-link?reset=true) Sem rota na base compatível

E as rotas da instância, do aviso e dos ajustes?

Evolution v2 Na ProxyBox
GET /instance/connectionState open (conectada), connecting (QR, conectando, preparando) ou close (desconectada, pausada, erro)
GET /instance/connect Devolve o QR em base64 (e pairingCode com ?number=); conectada devolve o estado. Duas chamadas em menos de 2 segundos: 429. Na nativa: GET /instance/qr e POST /instance/pair-code
GET /instance/fetchInstances Lista com uma instância; sem token nem segredo
PUT ou POST /instance/restart, DELETE /instance/logout Reconecta e desconecta o aparelho
POST /instance/create, DELETE /instance/delete 403 em português: a instância nasce e é cancelada no painel
POST /webhook/set, GET /webhook/find Liga ao mesmo aviso da instância (https obrigatório) e grava o formato evolution. byEvents, base64 e headers são aceitos e ignorados
GET /settings/find, POST /settings/set Guardados, sem efeito no WhatsApp (rejectCall, groupsIgnore, alwaysOnline, readMessages…). Para recusar chamadas de verdade, use recusar chamadas na API nativa
GET /proxy/find, POST /proxy/set find diz se há IP próprio; set devolve 403: o IP é gerenciado pela ProxyBox e trocado no painel

Como ficam os erros?

Os erros seguem o formato da Evolution: {"status":404,"error":"Not Found","response":{"message":["…"]}}. O código de erro nativo vira este HTTP:

Erro nativo HTTP na base compatível
invalid_request, media_unavailable, media_too_large 400
instance_paused, forbidden, not_group_admin 403
not_found 404
not_connected, new_contacts_locked 409 (o segundo com Retry-After)
rate_limited, daily_limit 429 (com Retry-After)
unsupported 501
engine_unavailable 502
timeout 504

Número sem WhatsApp devolve 400 com {"jid":"…","exists":false,"number":"…"} na primeira posição da mensagem, como a Evolution 2.3. Versões novas dela podem devolver 201 PENDING nesse caso; confira o comportamento esperado do seu código.

Como ficam os avisos?

No painel, em Aviso automático, escolha o format: proxybox (padrão), evolution ou zapi. No segundo, os mesmos fatos chegam como messages.upsert, send.message, messages.update, messages.edited, messages.delete, connection.update, qrcode.updated, group-participants.update, groups.upsert, call e logout.instance, num envelope {event, instance, data, destination, date_time, sender, server_url, apikey}.

Três diferenças que quebram código escrito para a Evolution: apikey vem sempre nulo (valide pelo cabeçalho X-ProxyBox-Signature, que acompanha o aviso no formato evolution e é calculado sobre o corpo que sai); o nome do evento vem em minúsculas com ponto; o arquivo da mídia nunca vai junto (baixe pela rota de mídia). O JSON de cada evento está em aviso automático.

Qual plano de migração em etapas?

  1. Contrate uma instância de teste e conecte um número que você possa perder. A primeira mensagem leva minutos.
  2. Troque o aviso. Aponte-o para um receptor de teste, em formato evolution, e compare com o que a Evolution entrega hoje.
  3. Troque um fluxo por vez. Comece pelo texto. Depois mídia, depois grupos.
  4. Ajuste o ritmo. O padrão é 10 mensagens por minuto e 500 por dia. Um fluxo antigo que enviava mais rápido recebe 429; use Retry-After e Idempotency-Key. Veja erros e limites.
  5. Mantenha a Evolution no ar até todos os fluxos de um número passarem. Nunca conecte o mesmo número nas duas ao mesmo tempo.
  6. Conecte o número definitivo só no fim, depois de desconectar da Evolution.

Quais cuidados tomar?

Trocar de plataforma não limpa o histórico do número: se ele já foi denunciado, continua sendo. Trocar o IP de um número que conecta de um servidor estrangeiro para um IP brasileiro é uma mudança de origem que o WhatsApp vê; faça no horário de menor uso, com o celular do número à mão, caso peça o QR de novo (veja conectar por QR, código e passkey). Respeite as regras de uso aceitável.

Veja também

Índice completo: documentação. Sobre o produto: conheça a API de WhatsApp da ProxyBox.

Autoria: equipe técnica da ProxyBox. Atualizado em 12/11/2026. Mapa baseado no código da Evolution 2.3.7, lido em 10/11/2026; seção de botões e status atualizada em 12/11/2026 com a prova em aparelho.

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