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 é aceita no formato Evolution V2 e executada no seu número do Pilot Status. 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

Envie mensagens de todos os tipos por meio de um número conectado. Todo caminho termina com /{instance}, o nome de exibição do número (um parâmetro de caminho — nunca o coloque no corpo da requisição).

POST /message/sendTemplate/{instance} — Enviar template

Envia uma mensagem de template aprovado do WhatsApp para um destinatário.

Campo	Tipo	Obrigatório	Descrição
`number`	string	Não	Telefone do destinatário em E.164 sem `+`, ou um JID.
`name`	string	Sim	Nome do template aprovado.
`language`	string	Sim	Código de idioma/localidade do template (ex.: `pt_BR`).
`components`	array	Não	Componentes do template (parâmetros de cabeçalho/corpo/botão).
`webhookUrl`	string	Não	URL de webhook opcional por mensagem para callbacks de status.

{
  "number": "5511999999999",
  "name": "order_confirmation",
  "language": "pt_BR",
  "components": [
    {
      "type": "body",
      "parameters": [
        { "type": "text", "text": "Ismael" }
      ]
    }
  ],
  "webhookUrl": "https://example.com/webhooks/template"
}

POST /message/sendText/{instance} — Enviar texto

Envia uma mensagem de texto simples, opcionalmente com pré-visualização de link e menções.

Campo	Tipo	Obrigatório	Descrição
`number`	string	Sim	Telefone do destinatário em E.164 sem `+`, ou um JID.
`text`	string	Sim	Texto do corpo da mensagem.
`linkPreview`	boolean	Não	Se deve renderizar uma pré-visualização para URLs no texto.
`delay`	integer	Não	Atraso antes do envio, em milissegundos.
`quoted`	object	Não	Mensagem a citar/responder (`key`, `message`).
`everyOne`	boolean	Não	Mencionar todos no grupo.
`mentioned`	string[]	Não	Array de strings numéricas a mencionar.

{
  "number": "5511999999999",
  "text": "Hello from Pilot Status!",
  "linkPreview": true,
  "delay": 1200,
  "mentioned": ["5511988888888"]
}

POST /message/sendMedia/{instance} — Enviar mídia

Envia uma imagem, vídeo, documento ou arquivo de áudio por URL pública (base64 e upload de arquivo multipart também são suportados).

Campo	Tipo	Obrigatório	Descrição
`number`	string	Sim	Telefone do destinatário em E.164 sem `+`, ou um JID.
`mediatype`	string	Sim	Um entre `image`, `document`, `video`, `audio`.
`media`	string	Sim	URL pública (ou base64) do arquivo de mídia.
`mimetype`	string	Não	Tipo MIME da mídia (ex.: `image/png`).
`fileName`	string	Não	Nome do arquivo, usado para documentos.
`caption`	string	Não	Texto de legenda exibido com a mídia.
`delay`	integer	Não	Atraso antes do envio, em milissegundos.
`quoted`	object	Não	Mensagem a citar/responder (`key`, `message`).
`everyOne`	boolean	Não	Mencionar todos no grupo.
`mentioned`	string[]	Não	Array de strings numéricas a mencionar.

{
  "number": "5511999999999",
  "mediatype": "image",
  "media": "https://media.pilotstatus.com.br/example.png",
  "mimetype": "image/png",
  "fileName": "example.png",
  "caption": "Check this out"
}

POST /message/sendPtv/{instance} — Enviar nota de vídeo

Envia um PTV (nota de vídeo circular) por URL pública (base64 e upload de arquivo multipart também são suportados).

Campo	Tipo	Obrigatório	Descrição
`number`	string	Sim	Telefone do destinatário em E.164 sem `+`, ou um JID.
`video`	string	Sim	URL pública (ou base64) do arquivo de vídeo.
`delay`	integer	Não	Atraso antes do envio, em milissegundos.
`quoted`	object	Não	Mensagem a citar/responder (`key`, `message`).
`everyOne`	boolean	Não	Mencionar todos no grupo.
`mentioned`	string[]	Não	Array de strings numéricas a mencionar.

{
  "number": "5511999999999",
  "video": "https://media.pilotstatus.com.br/note.mp4",
  "delay": 800
}

POST /message/sendWhatsAppAudio/{instance} — Enviar áudio de voz

Envia um áudio de voz/PTT do WhatsApp por URL pública (base64 e upload de arquivo multipart também são suportados).

Campo	Tipo	Obrigatório	Descrição
`number`	string	Sim	Telefone do destinatário em E.164 sem `+`, ou um JID.
`audio`	string	Sim	URL pública (ou base64) do arquivo de áudio.
`delay`	integer	Não	Atraso antes do envio, em milissegundos.
`quoted`	object	Não	Mensagem a citar/responder (`key`, `message`).
`everyOne`	boolean	Não	Mencionar todos no grupo.
`mentioned`	string[]	Não	Array de strings numéricas a mencionar.

{
  "number": "5511999999999",
  "audio": "https://media.pilotstatus.com.br/voice.ogg"
}

POST /message/sendStatus/{instance} — Enviar status

Publica um status (story) como texto ou mídia por URL pública (upload de arquivo de mídia também é suportado).

Campo	Tipo	Obrigatório	Descrição
`type`	string	Sim	Um entre `text`, `image`, `audio`, `video`.
`content`	string	Sim	Texto do status, ou a URL pública da mídia.
`caption`	string	Não	Legenda para status de mídia.
`backgroundColor`	string	Não	Cor de fundo para status de texto (ex.: `#25D366`).
`font`	integer	Não	Índice de fonte para status de texto (0–5).
`statusJidList`	string[]	Não	JIDs de destinatários (strings numéricas) autorizados a ver o status.
`allContacts`	boolean	Não	Publicar para todos os contatos em vez de uma lista de JIDs.

{
  "type": "text",
  "content": "We are online!",
  "backgroundColor": "#25D366",
  "font": 2,
  "allContacts": true
}

POST /message/sendSticker/{instance} — Enviar figurinha

Envia uma figurinha por URL pública (base64 e upload de arquivo multipart também são suportados).

Campo	Tipo	Obrigatório	Descrição
`number`	string	Sim	Telefone do destinatário em E.164 sem `+`, ou um JID.
`sticker`	string	Sim	URL pública (ou base64) da imagem da figurinha.
`delay`	integer	Não	Atraso antes do envio, em milissegundos.
`quoted`	object	Não	Mensagem a citar/responder (`key`, `message`).
`everyOne`	boolean	Não	Mencionar todos no grupo.
`mentioned`	string[]	Não	Array de strings numéricas a mencionar.

{
  "number": "5511999999999",
  "sticker": "https://media.pilotstatus.com.br/sticker.webp"
}

POST /message/sendLocation/{instance} — Enviar localização

Envia um marcador de localização geográfica com nome e endereço.

Campo	Tipo	Obrigatório	Descrição
`number`	string	Sim	Telefone do destinatário em E.164 sem `+`, ou um JID.
`latitude`	number	Sim	Latitude da localização.
`longitude`	number	Sim	Longitude da localização.
`name`	string	Sim	Nome de exibição do local.
`address`	string	Sim	Endereço do local.
`delay`	integer	Não	Atraso antes do envio, em milissegundos.
`quoted`	object	Não	Mensagem a citar/responder (`key`, `message`).
`everyOne`	boolean	Não	Mencionar todos no grupo.
`mentioned`	string[]	Não	Array de strings numéricas a mencionar.

{
  "number": "5511999999999",
  "latitude": -23.55052,
  "longitude": -46.633308,
  "name": "Pilot Status HQ",
  "address": "Av. Paulista, 1000, São Paulo"
}

POST /message/sendContact/{instance} — Enviar contato

Envia um ou mais cartões de contato (vCards).

Campo	Tipo	Obrigatório	Descrição
`number`	string	Sim	Telefone do destinatário em E.164 sem `+`, ou um JID.
`contact`	array	Sim	Array de objetos de contato (veja os campos abaixo).
`contact[].fullName`	string	Sim	Nome completo do contato.
`contact[].phoneNumber`	string	Sim	Número de telefone do contato.
`contact[].wuid`	string	Não	Identificador de usuário do WhatsApp (string numérica).
`contact[].organization`	string	Não	Organização do contato.
`contact[].email`	string	Não	Endereço de e-mail do contato.
`contact[].url`	string	Não	URL do site do contato.

{
  "number": "5511999999999",
  "contact": [
    {
      "fullName": "Ismael Nascimento",
      "wuid": "5511988888888",
      "phoneNumber": "5511988888888",
      "organization": "Pilot Status",
      "email": "contato@pilotstatus.com.br",
      "url": "https://pilotstatus.com.br"
    }
  ]
}

POST /message/sendReaction/{instance} — Enviar reação

Reage a uma mensagem existente com um emoji.

Campo	Tipo	Obrigatório	Descrição
`key`	object	Sim	Chave da mensagem alvo (`id`, `remoteJid`, `fromMe` — todos obrigatórios).
`reaction`	string	Sim	Emoji com o qual reagir.

{
  "key": {
    "id": "BAE5F6A1B2C3D4E5",
    "remoteJid": "5511999999999@s.whatsapp.net",
    "fromMe": false
  },
  "reaction": "👍"
}

POST /message/sendPoll/{instance} — Enviar enquete

Envia uma enquete com opções selecionáveis.

Campo	Tipo	Obrigatório	Descrição
`number`	string	Sim	Telefone do destinatário em E.164 sem `+`, ou um JID.
`name`	string	Sim	Pergunta/título da enquete.
`selectableCount`	integer	Sim	Quantas opções podem ser selecionadas (0–10).
`values`	string[]	Sim	Opções da enquete (2–10 strings únicas).
`delay`	integer	Não	Atraso antes do envio, em milissegundos.
`quoted`	object	Não	Mensagem a citar/responder (`key`, `message`).
`everyOne`	boolean	Não	Mencionar todos no grupo.
`mentioned`	string[]	Não	Array de strings numéricas a mencionar.

{
  "number": "5511999999999",
  "name": "Which plan do you prefer?",
  "selectableCount": 1,
  "values": ["Starter", "Pro", "Enterprise"]
}

POST /message/sendList/{instance} — Enviar lista

Envia uma mensagem de lista interativa com seções e linhas selecionáveis.

Campo	Tipo	Obrigatório	Descrição
`number`	string	Sim	Telefone do destinatário em E.164 sem `+`, ou um JID.
`title`	string	Sim	Título da lista.
`footerText`	string	Sim	Texto de rodapé exibido abaixo da lista.
`buttonText`	string	Sim	Rótulo do botão que abre a lista.
`sections`	array	Sim	Array de objetos de seção (veja os campos abaixo).
`sections[].title`	string	Sim	Título da seção.
`sections[].rows`	array	Sim	Linhas, cada uma com `title`, `rowId` (obrigatórios) e `description` opcional.
`description`	string	Não	Texto de descrição/corpo da lista.
`delay`	integer	Não	Atraso antes do envio, em milissegundos.
`quoted`	object	Não	Mensagem a citar/responder (`key`, `message`).
`everyOne`	boolean	Não	Mencionar todos no grupo.
`mentioned`	string[]	Não	Array de strings numéricas a mencionar.

{
  "number": "5511999999999",
  "title": "Our menu",
  "description": "Pick an item",
  "footerText": "Pilot Status",
  "buttonText": "View options",
  "sections": [
    {
      "title": "Drinks",
      "rows": [
        { "title": "Coffee", "description": "Fresh brewed", "rowId": "drink_coffee" },
        { "title": "Tea", "description": "Green tea", "rowId": "drink_tea" }
      ]
    }
  ]
}

POST /message/sendButtons/{instance} — Enviar botões

Envia uma mensagem de botões interativos. O type de cada botão é um entre reply, copy, url, call, pix.

Campo	Tipo	Obrigatório	Descrição
`number`	string	Sim	Telefone do destinatário em E.164 sem `+`, ou um JID.
`buttons`	array	Não	Array de objetos de botão (veja os campos abaixo).
`buttons[].type`	string	Sim	Tipo do botão: `reply`, `copy`, `url`, `call` ou `pix`.
`buttons[].displayText`	string	Não	Texto exibido no botão.
`buttons[].id`	string	Não	Identificador do botão (para `reply`).
`buttons[].url`	string	Não	URL a abrir (para `url`).
`buttons[].phoneNumber`	string	Não	Número de telefone a ligar (para `call`).
`buttons[].currency`	string	Não	Moeda (para `pix`).
`buttons[].name`	string	Não	Nome do recebedor/chave (para `pix`).
`buttons[].keyType`	string	Não	Tipo de chave Pix: `phone`, `email`, `cpf`, `cnpj`, `random`.
`buttons[].key`	string	Não	Valor da chave Pix (para `pix`).
`title`	string	Não	Título da mensagem.
`description`	string	Não	Texto do corpo da mensagem.
`footer`	string	Não	Texto de rodapé.
`thumbnailUrl`	string	Não	URL de uma imagem de miniatura.
`delay`	integer	Não	Atraso antes do envio, em milissegundos.
`quoted`	object	Não	Mensagem a citar/responder (`key`, `message`).
`everyOne`	boolean	Não	Mencionar todos no grupo.
`mentioned`	string[]	Não	Array de strings numéricas a mencionar.

{
  "number": "5511999999999",
  "title": "How can we help?",
  "description": "Choose an option below",
  "footer": "Pilot Status",
  "buttons": [
    { "type": "reply", "displayText": "Talk to sales", "id": "sales" },
    { "type": "url", "displayText": "Visit site", "url": "https://pilotstatus.com.br" },
    { "type": "call", "displayText": "Call us", "phoneNumber": "5511967435133" }
  ]
}

POST /message/sendCarousel/{instance} — Enviar carrossel

Envia um carrossel de cartões, cada um com texto, uma miniatura opcional e seus próprios botões.

Campo	Tipo	Obrigatório	Descrição
`number`	string	Sim	Telefone do destinatário em E.164 sem `+`, ou um JID.
`cards`	array	Não	Array de objetos de cartão (veja os campos abaixo).
`cards[].text`	string	Não	Texto do corpo do cartão.
`cards[].thumbnailUrl`	string	Não	URL da imagem de miniatura do cartão.
`cards[].footerText`	string	Não	Texto de rodapé do cartão.
`cards[].buttons`	array	Não	Botões do cartão (mesmo formato de sendButtons).
`title`	string	Não	Título do carrossel.
`description`	string	Não	Texto do corpo do carrossel.
`footer`	string	Não	Texto de rodapé do carrossel.
`delay`	integer	Não	Atraso antes do envio, em milissegundos.
`everyOne`	boolean	Não	Mencionar todos no grupo.
`mentioned`	string[]	Não	Array de strings numéricas a mencionar.

{
  "number": "5511999999999",
  "title": "Featured products",
  "description": "Swipe to browse",
  "footer": "Pilot Status",
  "cards": [
    {
      "text": "Starter plan",
      "thumbnailUrl": "https://media.pilotstatus.com.br/starter.png",
      "footerText": "Best for small teams",
      "buttons": [
        { "type": "url", "displayText": "Learn more", "url": "https://pilotstatus.com.br/starter" }
      ]
    }
  ]
}

Chat

Gerencie conversas, mensagens, contatos, presença e status de bloqueio de um número conectado. Em todos os caminhos, {instance} é o nome de exibição do número (um parâmetro de caminho), nunca um campo do corpo.

POST /chat/whatsappNumbers/{instance} — Verificar números de WhatsApp

Verifica se um ou mais números estão registrados no WhatsApp.

Campo	Tipo	Obrigatório	Descrição
`numbers`	string[]	Sim	Array de strings numéricas de telefone (E.164 sem símbolos) a serem verificadas.

{
  "numbers": ["5511999999999", "5521988888888"]
}

POST /chat/markMessageAsRead/{instance} — Marcar mensagens como lidas

Marca uma ou mais mensagens como lidas (envia confirmações de leitura).

Campo	Tipo	Obrigatório	Descrição
`readMessages`	array	Sim	Array de objetos de chave de mensagem a serem marcados como lidos.
`readMessages[].id`	string	Sim	Identificador da mensagem.
`readMessages[].fromMe`	boolean	Sim	Indica se a mensagem foi enviada por este número.
`readMessages[].remoteJid`	string	Sim	JID da conversa à qual a mensagem pertence.

{
  "readMessages": [
    {
      "id": "BAE5F5A632EAE722",
      "fromMe": false,
      "remoteJid": "5511999999999@s.whatsapp.net"
    }
  ]
}

POST /chat/archiveChat/{instance} — Arquivar ou desarquivar conversa

Arquiva ou desarquiva uma conversa.

Campo	Tipo	Obrigatório	Descrição
`archive`	boolean	Sim	`true` para arquivar, `false` para desarquivar.
`chat`	string	Não	JID da conversa a ser arquivada.
`lastMessage`	object	Não	Referência à última mensagem da conversa.
`lastMessage.key`	object	Não	Chave da mensagem com `id`, `remoteJid`, `fromMe`.
`lastMessage.messageTimestamp`	integer	Não	Timestamp Unix da última mensagem.

{
  "archive": true,
  "chat": "5511999999999@s.whatsapp.net",
  "lastMessage": {
    "key": {
      "id": "BAE5F5A632EAE722",
      "remoteJid": "5511999999999@s.whatsapp.net",
      "fromMe": false
    },
    "messageTimestamp": 1720540800
  }
}

POST /chat/markChatUnread/{instance} — Marcar conversa como não lida

Marca uma conversa como não lida.

Campo	Tipo	Obrigatório	Descrição
`lastMessage`	object	Sim	Referência à última mensagem da conversa.
`lastMessage.key`	object	Sim	Chave da mensagem com `id`, `remoteJid`, `fromMe`.
`lastMessage.messageTimestamp`	integer	Não	Timestamp Unix da última mensagem.
`chat`	string	Não	JID da conversa a ser marcada como não lida.

{
  "lastMessage": {
    "key": {
      "id": "BAE5F5A632EAE722",
      "remoteJid": "5511999999999@s.whatsapp.net",
      "fromMe": false
    },
    "messageTimestamp": 1720540800
  },
  "chat": "5511999999999@s.whatsapp.net"
}

DELETE /chat/deleteMessageForEveryone/{instance} — Apagar mensagem para todos

Apaga uma mensagem para todos os participantes da conversa.

Campo	Tipo	Obrigatório	Descrição
`id`	string	Sim	Identificador da mensagem a ser apagada.
`fromMe`	boolean	Sim	Indica se a mensagem foi enviada por este número.
`remoteJid`	string	Sim	JID da conversa à qual a mensagem pertence.
`participant`	string	Não	JID do participante (para mensagens de grupo).

{
  "id": "BAE5F5A632EAE722",
  "fromMe": true,
  "remoteJid": "1203630000000000000@g.us",
  "participant": "5511999999999@s.whatsapp.net"
}

POST /chat/getBase64FromMediaMessage/{instance} — Obter mídia como base64

Baixa uma mensagem de mídia e a retorna como uma string base64.

Campo	Tipo	Obrigatório	Descrição
`message`	object	Sim	Objeto de mensagem completo, ou um objeto contendo apenas `key` para que possa ser buscada.
`message.key`	object	Não	Chave da mensagem com `id`, `remoteJid`, `fromMe`.
`convertToMp4`	boolean	Não	Converte a mídia para MP4 quando aplicável.

{
  "message": {
    "key": {
      "id": "BAE5F5A632EAE722",
      "remoteJid": "5511999999999@s.whatsapp.net",
      "fromMe": false
    }
  },
  "convertToMp4": false
}

POST /chat/updateMessage/{instance} — Editar mensagem enviada

Edita o texto de uma mensagem enviada anteriormente por este número.

Campo	Tipo	Obrigatório	Descrição
`number`	string	Sim	Número/conversa de destino para o qual a mensagem foi enviada.
`text`	string	Sim	Novo texto da mensagem.
`key`	object	Sim	Chave da mensagem a ser editada (`id`, `remoteJid`, `fromMe`).

{
  "number": "5511999999999",
  "text": "Edited message text",
  "key": {
    "id": "BAE5F5A632EAE722",
    "remoteJid": "5511999999999@s.whatsapp.net",
    "fromMe": true
  }
}

POST /chat/sendPresence/{instance} — Enviar atualização de presença

Envia um indicador de presença (digitando, gravando, etc.) para uma conversa.

Campo	Tipo	Obrigatório	Descrição
`number`	string	Sim	Número do destinatário.
`presence`	string	Sim	Um dos valores `unavailable`, `available`, `composing`, `recording`, `paused`.
`delay`	number	Sim	Duração em milissegundos para manter a presença ativa.

{
  "number": "5511999999999",
  "presence": "composing",
  "delay": 2000
}

POST /chat/updateBlockStatus/{instance} — Bloquear ou desbloquear contato

Bloqueia ou desbloqueia um contato.

Campo	Tipo	Obrigatório	Descrição
`number`	string	Sim	Número do contato a ser bloqueado/desbloqueado.
`status`	string	Sim	`block` ou `unblock`.

{
  "number": "5511999999999",
  "status": "block"
}

GET /chat/findChatByRemoteJid/{instance} — Buscar conversa por JID

Retorna a conversa correspondente ao JID remoto informado. Passe remoteJid como parâmetro de consulta obrigatório (ex.: ?remoteJid=5511999999999@s.whatsapp.net); não há corpo de requisição.Sem corpo de requisição.

POST /chat/findContacts/{instance} — Buscar contatos

Pesquisa os contatos armazenados, opcionalmente filtrados por uma cláusula where. Envie um corpo vazio para retornar todos os contatos.

Campo	Tipo	Obrigatório	Descrição
`where`	object	Não	Filtro com qualquer um dos campos `_id`, `id`, `pushName`, `remoteJid`.

{
  "where": {
    "id": "5511999999999@s.whatsapp.net"
  }
}

POST /chat/findMessages/{instance} — Buscar mensagens

Pesquisa as mensagens armazenadas, opcionalmente filtradas por uma cláusula where e limitadas por limit.

Campo	Tipo	Obrigatório	Descrição
`where`	object	Não	Filtro com `_id`, `key` (`id`, `remoteJid`, `fromMe`) ou `message`.
`limit`	integer	Não	Número máximo de mensagens a serem retornadas.

{
  "where": {
    "key": {
      "remoteJid": "5511999999999@s.whatsapp.net"
    }
  },
  "limit": 20
}

POST /chat/findStatusMessage/{instance} — Buscar status de mensagens

Pesquisa atualizações de status de entrega/leitura de mensagens, opcionalmente filtradas por uma cláusula where e limitadas por limit.

Campo	Tipo	Obrigatório	Descrição
`where`	object	Não	Filtro com `_id`, `remoteJid`, `id`, `fromMe`, `participant` ou `status`.
`where.status`	string	Não	Um dos valores `ERROR`, `PENDING`, `SERVER_ACK`, `DELIVERY_ACK`, `READ`, `PLAYED`.
`limit`	integer	Não	Número máximo de registros a serem retornados.

{
  "where": {
    "remoteJid": "5511999999999@s.whatsapp.net",
    "status": "READ"
  },
  "limit": 20
}

POST /chat/findChats/{instance} — Buscar conversas

Retorna as conversas armazenadas, opcionalmente filtradas por uma cláusula where. Envie um corpo vazio para retornar todas as conversas.

Campo	Tipo	Obrigatório	Descrição
`where`	object	Não	Filtro com qualquer um dos campos `_id`, `id`, `pushName`, `remoteJid`.

{
  "where": {
    "remoteJid": "5511999999999@s.whatsapp.net"
  }
}

Perfil

Leia e atualize o próprio perfil do número conectado (nome, status, foto), inspecione os perfis de outros usuários e gerencie as configurações de privacidade. Em todos os caminhos, {instance} é o nome de exibição do número — nunca o envie no corpo da requisição.

POST /chat/fetchProfilePictureUrl/{instance} — Obter URL da foto de perfil

Obtém a URL da foto de perfil de um contato do WhatsApp.

Campo	Tipo	Obrigatório	Descrição
`number`	string	Sim	Número de telefone ou JID cuja URL da foto de perfil deve ser obtida.

{
  "number": "5511999999999"
}

POST /chat/fetchBusinessProfile/{instance} — Obter perfil comercial

Obtém o perfil do WhatsApp Business (categoria, descrição, e-mail, site) de um número.

Campo	Tipo	Obrigatório	Descrição
`number`	string	Sim	Número de telefone ou JID da conta comercial a inspecionar.

{
  "number": "5511999999999"
}

POST /chat/fetchProfile/{instance} — Obter perfil do contato

Obtém o perfil completo (nome, status, foto, indicador de conta comercial) de um contato.

Campo	Tipo	Obrigatório	Descrição
`number`	string	Sim	Número de telefone ou JID cujo perfil deve ser obtido.

{
  "number": "5511999999999"
}

POST /chat/updateProfileName/{instance} — Atualizar o próprio nome de exibição

Atualiza o próprio nome de exibição do WhatsApp do número conectado.

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Novo nome de exibição para o número conectado.

{
  "name": "Pilot Status Support"
}

POST /chat/updateProfileStatus/{instance} — Atualizar o próprio texto de status

Atualiza o próprio texto de “recado” / status do número conectado.

Campo	Tipo	Obrigatório	Descrição
`status`	string	Sim	Novo texto de status/recado para o número conectado.

{
  "status": "Available for support 24/7"
}

POST /chat/updateProfilePicture/{instance} — Atualizar a própria foto de perfil

Atualiza a própria foto de perfil do número conectado a partir de uma URL ou imagem em base64.

Campo	Tipo	Obrigatório	Descrição
`picture`	string	Sim	Imagem como uma URL pública ou uma string codificada em base64.

{
  "picture": "https://example.com/avatar.png"
}

DELETE /chat/removeProfilePicture/{instance} — Remover a própria foto de perfil

Remove a própria foto de perfil do número conectado. Atinge o número identificado pelo parâmetro de caminho {instance}.Sem corpo de requisição.

GET /chat/fetchPrivacySettings/{instance} — Obter configurações de privacidade

Retorna as configurações de privacidade atuais do número conectado. Atinge o número identificado pelo parâmetro de caminho {instance}.Sem corpo de requisição.

POST /chat/updatePrivacySettings/{instance} — Atualizar configurações de privacidade

Atualiza as configurações de privacidade do número conectado; todos os seis campos são obrigatórios.

Campo	Tipo	Obrigatório	Descrição
`readreceipts`	string	Sim	Visibilidade das confirmações de leitura: `all` ou `none`.
`profile`	string	Sim	Visibilidade da foto de perfil: `all`, `contacts`, `contact_blacklist` ou `none`.
`status`	string	Sim	Visibilidade do status/recado: `all`, `contacts`, `contact_blacklist` ou `none`.
`online`	string	Sim	Visibilidade da presença online: `all` ou `match_last_seen`.
`last`	string	Sim	Visibilidade do visto por último: `all`, `contacts`, `contact_blacklist` ou `none`.
`groupadd`	string	Sim	Quem pode adicionar a grupos: `all`, `contacts`, `contact_blacklist` ou `none`.

{
  "readreceipts": "all",
  "profile": "contacts",
  "status": "contacts",
  "online": "all",
  "last": "contacts",
  "groupadd": "contacts"
}

Grupo

Crie e gerencie grupos do WhatsApp. Todo caminho termina com /{instance}, o nome de exibição do número, passado como parâmetro de caminho (nunca no corpo).

POST /group/create/{instance} — Criar grupo

Cria um novo grupo do WhatsApp com um assunto e uma lista inicial de participantes.

Campo	Tipo	Obrigatório	Descrição
`subject`	string	Sim	Nome/assunto do grupo.
`participants`	string[]	Sim	Números de telefone (apenas dígitos) a adicionar como membros.
`description`	string	Não	Descrição do grupo.
`profilePicture`	string	Não	URL da foto de perfil do grupo.
`promoteParticipants`	boolean	Não	Promover a administradores os participantes adicionados.

{
  "subject": "Equipe de Vendas",
  "participants": ["5511999999999", "5511888888888"],
  "description": "Grupo interno da equipe",
  "profilePicture": "https://example.com/group.png",
  "promoteParticipants": false
}

POST /group/updateGroupSubject/{instance} — Atualizar assunto

Altera o nome/assunto de um grupo existente.

Campo	Tipo	Obrigatório	Descrição
`groupJid`	string	Sim	JID do grupo (também pode ser enviado como parâmetro de consulta `groupJid`).
`subject`	string	Sim	Novo assunto do grupo.

{
  "groupJid": "120363000000000000@g.us",
  "subject": "Novo nome do grupo"
}

POST /group/updateGroupPicture/{instance} — Atualizar foto

Define a foto de perfil do grupo a partir de uma URL de imagem.

Campo	Tipo	Obrigatório	Descrição
`groupJid`	string	Sim	JID do grupo (também pode ser enviado como parâmetro de consulta `groupJid`).
`image`	string	Sim	URL da nova foto do grupo.

{
  "groupJid": "120363000000000000@g.us",
  "image": "https://example.com/group.png"
}

POST /group/updateGroupDescription/{instance} — Atualizar descrição

Atualiza o texto da descrição do grupo.

Campo	Tipo	Obrigatório	Descrição
`groupJid`	string	Sim	JID do grupo (também pode ser enviado como parâmetro de consulta `groupJid`).
`description`	string	Sim	Nova descrição do grupo.

{
  "groupJid": "120363000000000000@g.us",
  "description": "Descrição atualizada do grupo"
}

GET /group/findGroupInfos/{instance} — Obter informações do grupo

Retorna os metadados de um único grupo. Passe o JID do grupo como parâmetro de consulta groupJid (ex.: ?groupJid=120363000000000000@g.us).Sem corpo de requisição.

GET /group/fetchAllGroups/{instance} — Listar todos os grupos

Retorna todos os grupos aos quais o número pertence. O parâmetro de consulta obrigatório getParticipants ("true" ou "false") controla se a lista de participantes de cada grupo é incluída.Sem corpo de requisição.

GET /group/participants/{instance} — Listar participantes

Retorna a lista de participantes de um grupo. Passe o JID do grupo como parâmetro de consulta groupJid.Sem corpo de requisição.

GET /group/inviteCode/{instance} — Obter código de convite

Retorna o código/link de convite atual de um grupo. Passe o JID do grupo como parâmetro de consulta groupJid.Sem corpo de requisição.

GET /group/inviteInfo/{instance} — Obter informações do convite

Retorna as informações do grupo por trás de um código de convite. Passe o código como parâmetro de consulta inviteCode (ex.: ?inviteCode=F1EX5QZxO181L3TMVP31gY).Sem corpo de requisição.

GET /group/acceptInviteCode/{instance} — Aceitar convite

Entra em um grupo usando um código de convite. Passe o código como parâmetro de consulta inviteCode.Sem corpo de requisição.

POST /group/sendInvite/{instance} — Enviar convite

Envia o link de convite do grupo para um ou mais números de telefone.

Campo	Tipo	Obrigatório	Descrição
`groupJid`	string	Sim	JID do grupo.
`description`	string	Sim	Texto da mensagem enviada junto com o convite.
`numbers`	string[]	Sim	Números de telefone (apenas dígitos) para os quais enviar o convite.

{
  "groupJid": "120363000000000000@g.us",
  "description": "Entre no nosso grupo!",
  "numbers": ["5511999999999", "5511888888888"]
}

POST /group/revokeInviteCode/{instance} — Revogar convite

Revoga o link de convite atual e gera um novo.

Campo	Tipo	Obrigatório	Descrição
`groupJid`	string	Sim	JID do grupo (também pode ser enviado como parâmetro de consulta `groupJid`).

{
  "groupJid": "120363000000000000@g.us"
}

POST /group/updateParticipant/{instance} — Atualizar participantes

Adiciona, remove, promove ou rebaixa participantes do grupo.

Campo	Tipo	Obrigatório	Descrição
`groupJid`	string	Sim	JID do grupo (também pode ser enviado como parâmetro de consulta `groupJid`).
`action`	string	Sim	Um de `add`, `remove`, `promote`, `demote`.
`participants`	string[]	Sim	Números de telefone (apenas dígitos) aos quais aplicar a ação.

{
  "groupJid": "120363000000000000@g.us",
  "action": "add",
  "participants": ["5511999999999"]
}

POST /group/updateSetting/{instance} — Atualizar configuração

Atualiza as permissões de mensagens e edição de um grupo.

Campo	Tipo	Obrigatório	Descrição
`groupJid`	string	Sim	JID do grupo (também pode ser enviado como parâmetro de consulta `groupJid`).
`action`	string	Sim	Um de `announcement`, `not_announcement`, `locked`, `unlocked`.

{
  "groupJid": "120363000000000000@g.us",
  "action": "announcement"
}

POST /group/updateMemberAddMode/{instance} — Atualizar modo de adição de membros

Controla quem pode adicionar novos membros ao grupo.

Campo	Tipo	Obrigatório	Descrição
`groupJid`	string	Sim	JID do grupo (também pode ser enviado como parâmetro de consulta `groupJid`).
`mode`	string	Sim	Um de `admin_add`, `all_member_add`.

{
  "groupJid": "120363000000000000@g.us",
  "mode": "admin_add"
}

POST /group/toggleEphemeral/{instance} — Alternar mensagens temporárias

Ativa ou desativa as mensagens temporárias do grupo.

Campo	Tipo	Obrigatório	Descrição
`groupJid`	string	Sim	JID do grupo (também pode ser enviado como parâmetro de consulta `groupJid`).
`expiration`	integer	Sim	Segundos até as mensagens desaparecerem: `0` (desligado), `86400` (24h), `604800` (7d) ou `7776000` (90d).

{
  "groupJid": "120363000000000000@g.us",
  "expiration": 604800
}

DELETE /group/leaveGroup/{instance} — Sair do grupo

Remove o número conectado do grupo. Passe o JID do grupo como parâmetro de consulta groupJid.Sem corpo de requisição.

Etiqueta (Label)

Gerencie as etiquetas de conversas do WhatsApp de um número conectado.

GET /label/findLabels/{instance} — Listar etiquetas

Retorna todas as etiquetas definidas no número identificado pelo parâmetro de caminho {instance} (o nome de exibição do número).Sem corpo de requisição.

POST /label/handleLabel/{instance} — Adicionar ou remover etiqueta

Adiciona ou remove uma etiqueta em uma conversa do número identificado pelo parâmetro de caminho {instance}.

Campo	Tipo	Obrigatório	Descrição
`number`	string	Sim	Número de telefone do destinatário em formato internacional (não vazio).
`labelId`	string	Sim	Identificador da etiqueta a aplicar ou remover (não vazio).
`action`	string	Sim	Operação a executar; `add` ou `remove`.

{
  "number": "5511999999999",
  "labelId": "1",
  "action": "add"
}

Template

Gerencie templates de mensagem do WhatsApp (HSMs) para um número conectado. Em todos os caminhos, {instance} é o nome de exibição do número.

POST /template/create/{instance} — Criar template

Cria um novo template de mensagem para a instância.

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome único do template (minúsculas, underscores).
`category`	string	Sim	Categoria do template: `AUTHENTICATION`, `MARKETING` ou `UTILITY`.
`language`	string	Sim	Código de idioma/localidade (ex.: `pt_BR`, `en_US`).
`components`	array	Sim	Objetos de componente do template (cabeçalho, corpo, rodapé, botões).
`allowCategoryChange`	boolean	Não	Permite que a Meta reatribua a categoria durante a revisão.
`webhookUrl`	string	Não	URL notificada sobre mudanças de status do template.

{
  "name": "order_confirmation",
  "category": "UTILITY",
  "language": "pt_BR",
  "allowCategoryChange": true,
  "components": [
    {
      "type": "BODY",
      "text": "Ola {{1}}, seu pedido {{2}} foi confirmado."
    }
  ],
  "webhookUrl": "https://example.com/webhooks/template-status"
}

POST /template/edit/{instance} — Editar template

Atualiza um template existente identificado pelo seu ID de template da Meta.

Campo	Tipo	Obrigatório	Descrição
`templateId`	string	Sim	ID do template da Meta a ser editado.
`category`	string	Não	Nova categoria: `AUTHENTICATION`, `MARKETING` ou `UTILITY`.
`allowCategoryChange`	boolean	Não	Permite que a Meta reatribua a categoria durante a revisão.
`ttl`	number	Não	Tempo de vida para templates de autenticação, em segundos.
`components`	array	Não	Objetos de componente do template para substituição.

{
  "templateId": "1234567890123456",
  "category": "UTILITY",
  "allowCategoryChange": false,
  "ttl": 600,
  "components": [
    {
      "type": "BODY",
      "text": "Ola {{1}}, seu pedido {{2}} esta a caminho."
    }
  ]
}

DELETE /template/delete/{instance} — Excluir template

Exclui um template pelo nome (opcionalmente delimitado pelo seu ID de HSM).

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome do template a ser excluído.
`hsmId`	string	Não	ID específico de HSM/template para direcionar a uma única versão de idioma.

{
  "name": "order_confirmation",
  "hsmId": "1234567890123456"
}

GET /template/find/{instance} — Listar templates

Retorna todos os templates registrados para a instância. O nome de exibição da instância é obtido a partir do caminho.Sem corpo de requisição.

Configurações e Proxy

Configure as opções de comportamento por número e o proxy de saída para a instância conectada.

POST /settings/set/{instance} — Atualizar configurações

Define as opções de comportamento da instância indicada no parâmetro de caminho {instance}.

Campo	Tipo	Obrigatório	Descrição
`rejectCall`	boolean	Sim	Rejeita automaticamente as chamadas recebidas no WhatsApp.
`msgCall`	string	Não	Mensagem enviada a quem liga quando uma chamada é rejeitada.
`groupsIgnore`	boolean	Sim	Ignora mensagens vindas de grupos.
`alwaysOnline`	boolean	Sim	Mantém a presença da conexão como sempre online.
`readMessages`	boolean	Sim	Marca automaticamente as mensagens recebidas como lidas.
`readStatus`	boolean	Sim	Marca automaticamente as atualizações de status/stories como lidas.
`syncFullHistory`	boolean	Sim	Sincroniza todo o histórico de mensagens ao conectar.
`wavoipToken`	string	Não	Token WAVOIP usado para habilitar o tratamento de chamadas de voz.

{
  "rejectCall": true,
  "msgCall": "Sorry, I can't take calls right now.",
  "groupsIgnore": false,
  "alwaysOnline": true,
  "readMessages": false,
  "readStatus": false,
  "syncFullHistory": false,
  "wavoipToken": ""
}

GET /settings/find/{instance} — Ler configurações

Retorna as configurações atuais da instância indicada no parâmetro de caminho {instance}.Sem corpo de requisição.

POST /proxy/set/{instance} — Configurar proxy

Define o proxy de saída da instância indicada no parâmetro de caminho {instance}.

Campo	Tipo	Obrigatório	Descrição
`enabled`	boolean	Sim	Indica se o proxy está habilitado para esta instância.
`host`	string	Sim	Nome do host ou endereço IP do proxy.
`port`	string	Sim	Porta do proxy.
`protocol`	string	Sim	Protocolo do proxy (ex.: `http`, `https`, `socks5`).
`username`	string	Não	Nome de usuário para autenticação no proxy.
`password`	string	Não	Senha para autenticação no proxy.

{
  "enabled": true,
  "host": "proxy.example.com",
  "port": "8080",
  "protocol": "http",
  "username": "proxyuser",
  "password": "proxypass"
}

GET /proxy/find/{instance} — Ler proxy

Retorna a configuração de proxy atual da instância indicada no parâmetro de caminho {instance}.Sem corpo de requisição.

Chamada e Business

Ofereça uma chamada no WhatsApp e leia o catálogo de produtos e as coleções de um número business conectado.

POST /call/offer/{instance} — Oferecer uma chamada

Oferece uma chamada de voz ou vídeo a um número destinatário por uma duração de toque limitada.

Campo	Tipo	Obrigatório	Descrição
`number`	string	Sim	Número de telefone do destinatário no formato internacional.
`callDuration`	integer	Sim	Por quanto tempo a chamada toca, em segundos (1–15).
`isVideo`	boolean	Não	`true` para chamada de vídeo, `false` para voz.

{
  "number": "5511999999999",
  "callDuration": 10,
  "isVideo": false
}

POST /business/getCatalog/{instance} — Buscar catálogo de produtos

Busca o catálogo de produtos de um número business do WhatsApp.

Campo	Tipo	Obrigatório	Descrição
`number`	string	Não	Número de telefone business cujo catálogo será buscado; por padrão, usa o próprio número da instância.
`limit`	number	Não	Número máximo de produtos a retornar.

{
  "number": "5511999999999",
  "limit": 50
}

POST /business/getCollections/{instance} — Buscar coleções

Busca as coleções do catálogo de um número business do WhatsApp.

Campo	Tipo	Obrigatório	Descrição
`number`	string	Não	Número de telefone business cujas coleções serão buscadas; por padrão, usa o próprio número da instância.
`limit`	number	Não	Número máximo de coleções a retornar.

{
  "number": "5511999999999",
  "limit": 20
}

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)

Recupere as mídias armazenadas no bucket S3/MinIO do número conectado ({instance} é o nome de exibição do número).

POST /s3/getMedia/{instance} — Listar mídias armazenadas

Retorna os registros de mídia armazenados para a instância, opcionalmente filtrados pelos campos informados.

Campo	Tipo	Obrigatório	Descrição
`id`	string	Não	Identificador do registro de mídia para filtrar.
`type`	string	Não	Tipo de mídia para filtrar (ex.: `image`, `video`, `audio`, `document`).
`messageId`	integer	Não	Identificador da mensagem à qual a mídia pertence.

{
  "id": "5f3e1d2c-8b7a-4c6d-9e0f-1a2b3c4d5e6f",
  "type": "image",
  "messageId": 12345
}

POST /s3/getMediaUrl/{instance} — Obter URL de mídia pré-assinada

Resolve um registro de mídia pelo id e retorna uma URL de download pré-assinada temporária junto com os metadados da mídia.

Campo	Tipo	Obrigatório	Descrição
`id`	string	Sim	Identificador do registro de mídia (string numérica).
`expiry`	string	Não	Tempo de vida da URL pré-assinada, em segundos (string numérica, ex.: `"3600"`).

{
  "id": "12345",
  "expiry": "3600"
}

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.

Visão Geral

Mensagens

Modelos

Números

Conversas & Dados

Webhooks

Chamadas de Voz