Camada de Compatibilidade Evolution V2 — Referência da API

A Camada de API Evolution V2 do Pilot Status é uma ponte de compatibilidade transparente para aplicações construídas sobre a Evolution API V2. Alterar sua base URL para o endpoint da camada do Pilot Status é tudo o que é necessário para migrar sua infraestrutura — seus corpos de requisição, parsing de respostas, handlers de webhook e cabeçalhos de autenticação permanecem exatamente como estão.

Base URL

Atualize a variável de ambiente da sua base URL ou a configuração do seu cliente HTTP para o seguinte:

https://pilotstatus.com.br/api/layer/evolution-v2/

Cada caminho que você chama atualmente no seu servidor Evolution V2 é anexado a esta base URL sem qualquer modificação.

Autenticação

Passe sua chave de API do Pilot Status no cabeçalho apikey, exatamente como a Evolution V2 espera:

apikey: YOUR_API_KEY

Você não precisa alterar nenhuma lógica de autenticação na sua aplicação — apenas o valor da chave de API precisa ser substituído pela sua chave do Pilot Status.

Operações suportadas

Cada operação abaixo é encaminhada para a instância Evolution API V2 subjacente do seu número. Em cada caminho, {instance} é o último segmento do caminho e resolve para o nome de exibição que você deu ao número no painel do Pilot Status. Operações de envio e de mensagem são balanceadas entre as instâncias conectadas do número (sendReaction é a exceção — não é balanceada). Qualquer caminho que não esteja neste catálogo retorna 404; caminhos globais (de servidor) retornam 403 — veja Bloqueado (global) abaixo.

Instância

Método	Caminho
`POST`	`/instance/restart/{instance}`
`GET`	`/instance/connect/{instance}`
`GET`	`/instance/connectionState/{instance}`
`POST`	`/instance/setPresence/{instance}`
`DELETE`	`/instance/logout/{instance}`
`DELETE`	`/instance/delete/{instance}`

Mensagem

Todos os endpoints de mensagem são POST /message/<ação>/{instance} e são balanceados entre as instâncias conectadas (exceto sendReaction).

Ação	Caminho
Enviar template	`POST /message/sendTemplate/{instance}`
Enviar texto	`POST /message/sendText/{instance}`
Enviar mídia	`POST /message/sendMedia/{instance}`
Enviar PTV (nota de vídeo)	`POST /message/sendPtv/{instance}`
Enviar áudio	`POST /message/sendWhatsAppAudio/{instance}`
Enviar status	`POST /message/sendStatus/{instance}`
Enviar sticker	`POST /message/sendSticker/{instance}`
Enviar localização	`POST /message/sendLocation/{instance}`
Enviar contato	`POST /message/sendContact/{instance}`
Enviar reação (não balanceada)	`POST /message/sendReaction/{instance}`
Enviar enquete	`POST /message/sendPoll/{instance}`
Enviar lista	`POST /message/sendList/{instance}`
Enviar botões	`POST /message/sendButtons/{instance}`
Enviar carrossel	`POST /message/sendCarousel/{instance}`

Chat

Método	Caminho
`POST`	`/chat/whatsappNumbers/{instance}`
`POST`	`/chat/markMessageAsRead/{instance}`
`POST`	`/chat/archiveChat/{instance}`
`POST`	`/chat/markChatUnread/{instance}`
`DELETE`	`/chat/deleteMessageForEveryone/{instance}`
`POST`	`/chat/getBase64FromMediaMessage/{instance}`
`POST`	`/chat/updateMessage/{instance}`
`POST`	`/chat/sendPresence/{instance}`
`POST`	`/chat/updateBlockStatus/{instance}`
`GET`	`/chat/findChatByRemoteJid/{instance}`
`POST`	`/chat/findContacts/{instance}`
`POST`	`/chat/findMessages/{instance}`
`POST`	`/chat/findStatusMessage/{instance}`
`POST`	`/chat/findChats/{instance}`

Perfil

Método	Caminho
`POST`	`/chat/fetchProfilePictureUrl/{instance}`
`POST`	`/chat/fetchBusinessProfile/{instance}`
`POST`	`/chat/fetchProfile/{instance}`
`POST`	`/chat/updateProfileName/{instance}`
`POST`	`/chat/updateProfileStatus/{instance}`
`POST`	`/chat/updateProfilePicture/{instance}`
`DELETE`	`/chat/removeProfilePicture/{instance}`
`GET`	`/chat/fetchPrivacySettings/{instance}`
`POST`	`/chat/updatePrivacySettings/{instance}`

Grupo

Método	Caminho
`POST`	`/group/create/{instance}`
`POST`	`/group/updateGroupSubject/{instance}`
`POST`	`/group/updateGroupPicture/{instance}`
`POST`	`/group/updateGroupDescription/{instance}`
`GET`	`/group/findGroupInfos/{instance}`
`GET`	`/group/fetchAllGroups/{instance}`
`GET`	`/group/participants/{instance}`
`GET`	`/group/inviteCode/{instance}`
`GET`	`/group/inviteInfo/{instance}`
`GET`	`/group/acceptInviteCode/{instance}`
`POST`	`/group/sendInvite/{instance}`
`POST`	`/group/revokeInviteCode/{instance}`
`POST`	`/group/updateParticipant/{instance}`
`POST`	`/group/updateSetting/{instance}`
`POST`	`/group/updateMemberAddMode/{instance}`
`POST`	`/group/toggleEphemeral/{instance}`
`DELETE`	`/group/leaveGroup/{instance}`

Etiqueta (Label)

Método	Caminho
`GET`	`/label/findLabels/{instance}`
`POST`	`/label/handleLabel/{instance}`

Template

Método	Caminho
`POST`	`/template/create/{instance}`
`POST`	`/template/edit/{instance}`
`DELETE`	`/template/delete/{instance}`
`GET`	`/template/find/{instance}`

Configurações e Proxy

Método	Caminho
`POST`	`/settings/set/{instance}`
`GET`	`/settings/find/{instance}`
`POST`	`/proxy/set/{instance}`
`GET`	`/proxy/find/{instance}`

Chamada e Business

Método	Caminho
`POST`	`/call/offer/{instance}`
`POST`	`/business/getCatalog/{instance}`
`POST`	`/business/getCollections/{instance}`

Integrações / chatbots

Cada integração de chatbot — evolutionBot, typebot, openai, dify, flowise, n8n e evoai — expõe o mesmo conjunto de endpoints (substitua {name} pelo nome da integração):

Método	Caminho
`POST`	`/{name}/create/{instance}`
`GET`	`/{name}/find/{instance}`
`GET`	`/{name}/fetch/{id}/{instance}`
`PUT`	`/{name}/update/{id}/{instance}`
`DELETE`	`/{name}/delete/{id}/{instance}`
`POST`	`/{name}/settings/{instance}`
`GET`	`/{name}/fetchSettings/{instance}`
`POST`	`/{name}/changeStatus/{instance}`
`GET`	`/{name}/fetchSessions/{id}/{instance}`
`POST`	`/{name}/ignoreJid/{instance}`

Extras específicos por integração:

Método	Caminho
`POST`	`/typebot/start/{instance}`
`POST` / `GET`	`/openai/creds/{instance}`
`DELETE`	`/openai/creds/{id}/{instance}`
`GET`	`/openai/getModels/{instance}`
`POST`	`/chatwoot/set/{instance}`
`GET`	`/chatwoot/find/{instance}`
`POST`	`/chatwoot/webhook/{instance}`

Brokers de eventos

Cada broker — webhook, websocket, rabbitmq, nats, pusher, sqs e kafka — expõe set/find (substitua {name} pelo nome do broker):

Método	Caminho
`POST`	`/{name}/set/{instance}`
`GET`	`/{name}/find/{instance}`

Armazenamento (S3)

Método	Caminho
`POST`	`/s3/getMedia/{instance}`
`POST`	`/s3/getMediaUrl/{instance}`

Bloqueado (global)

Caminhos globais (de servidor) não fazem parte da camada de migração e sempre retornam 403. Isso inclui: GET / (raiz), POST /verify-creds, GET /manager, GET /metrics, GET /assets/*, POST /instance/create e GET /instance/fetchInstances. Provisione e gerencie seus números pelo painel do Pilot Status ou pela API nativa. Qualquer caminho não listado neste catálogo retorna 404.

Eventos

A camada encaminha os eventos recebidos para o webhook que você configurou para o número, no formato nativo da própria Evolution API V2 (nomes de eventos em minúsculas, separados por ponto):

Evento	Evento
`messages.upsert`	`messages.edited`
`messages.update`	`messages.delete`
`send.message`	`send.message.update`
`connection.update`	`qrcode.updated`
`logout.instance`	`contacts.upsert`
`contacts.update`	`chats.upsert`
`chats.update`	`chats.delete`
`presence.update`	`groups.upsert`
`groups.update`	`group-participants.update`
`call`	`typebot.start`
`typebot.change-status`	`labels.edit`
`labels.association`

Além disso, o Pilot Status pode entregar seus próprios eventos normalizados junto com os nativos: os eventos do ciclo de vida de chamada call.ringing, call.connected, call.ended e call.missed, além dos eventos de ciclo de vida do número number.created, number.connected, number.disconnected e number.removed.

Exemplo: enviar texto via camada Evolution V2

A requisição abaixo é uma chamada padrão de envio de texto da Evolution V2 roteada através da camada do Pilot Status. Observe que o corpo da requisição usa o formato da Evolution V2 sem alterações.

curl -X POST 'https://pilotstatus.com.br/api/layer/evolution-v2/message/sendText/MyInstance' \
  -H 'apikey: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "number": "5511999999999",
    "text": "Hello from Pilot Status via API Layer! 👋"
  }'

Substitua MyInstance pelo nome de exibição que você atribuiu ao seu número no painel do Pilot Status.

Mapeamento de nome de instância

Na Evolution V2, cada instância representa uma conexão do WhatsApp identificada por um nome. O Pilot Status usa a mesma convenção — o nome da instância no caminho da sua URL mapeia para o nome de exibição que você atribuiu ao seu número ao conectá-lo através do painel do Pilot Status. Por exemplo, se você nomeou seu número como SupportLine no painel, suas requisições devem usar:

POST /message/sendText/SupportLine

Se você tiver múltiplos números, cada um tem seu próprio nome de exibição e se comporta como uma instância separada — consistente com a forma como a Evolution V2 gerencia múltiplas instâncias.

Para novos projetos, considere usar a API nativa do Pilot Status — ela oferece acesso completo a todos os recursos, incluindo integração oficial com a Meta e análises avançadas.

Para orientações gerais de migração e uma visão geral de todos os provedores suportados, veja a visão geral da API Layer.

​Base URL

​Autenticação

​Operações suportadas

​Instância

​Mensagem

​Chat

​Perfil

​Grupo

​Etiqueta (Label)

​Template

​Configurações e Proxy

​Chamada e Business

​Integrações / chatbots

​Brokers de eventos

​Armazenamento (S3)

​Bloqueado (global)

​Eventos

​Exemplo: enviar texto via camada Evolution V2

​Mapeamento de nome de instância

Base URL

Autenticação

Operações suportadas

Instância

Mensagem

Chat

Perfil

Grupo

Etiqueta (Label)

Template

Configurações e Proxy

Chamada e Business

Integrações / chatbots

Brokers de eventos

Armazenamento (S3)

Bloqueado (global)

Eventos

Exemplo: enviar texto via camada Evolution V2

Mapeamento de nome de instância