Recurso em beta: pode mudar. A base compatível com a Evolution e o formato de aviso
evolutionsã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,/openaie 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 responde422 interactive_unsupported. Também não existemsendTemplateesendPtv.- 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átisO 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:
# 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?
- Contrate uma instância de teste e conecte um número que você possa perder. A primeira mensagem leva minutos.
- Troque o aviso. Aponte-o para um receptor de teste, em formato
evolution, e compare com o que a Evolution entrega hoje. - Troque um fluxo por vez. Comece pelo texto. Depois mídia, depois grupos.
- 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-AftereIdempotency-Key. Veja erros e limites. - 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.
- 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
- Migrar da Z-API: mapa de rotas
- Botões no WhatsApp via API: resposta e ação
- Bots de WhatsApp pela API: tipos e limites
- Chatwoot com WhatsApp: ligar pela API
Í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.