Referência da API v2

Integre o WhatsApp à sua aplicação em minutos. A API v2 é compatível com Evolution API — se você já tem código funcionando no padrão Evolution, basta trocar a base URL para usar a Whatsmiau Cloud.

Base URL:https://api.whatsmiau.dev/v2

Identificador das instâncias: o instanceName que você escolhe ao criar é o identificador usado em todas as rotas subsequentes (:name). Não é preciso consultar nenhum ID interno.

Autenticação

Todas as requisições usam API Key via header apikey. Gere suas chaves no Dashboard. As chaves são escopadas por conta — você só acessa suas próprias instâncias.

GET

Verificar Credenciais

/instance/fetchInstances

Teste se sua chave de API é válida listando suas instâncias.

curl -X GET https://api.whatsmiau.dev/v2/instance/fetchInstances \
  -H "apikey: SUA_CHAVE_AQUI"

Instâncias

Gerencie suas sessões do WhatsApp. Cada instância representa um número de telefone conectado.

POST

Criar Instância

/instance/create

Cria uma nova instância com configuração completa: webhook, comportamento (rejeição de chamada, marcar como lido, sincronização de histórico) e opcionalmente proxy (Enterprise). O 'instanceName' que você escolher será o identificador usado em todas as outras chamadas — não existe mais ObjectID separado.

instanceNamestringObrigatório

Identificador único da instância dentro da sua conta. Será usado como :name em todos os outros endpoints, então não pode ser alterado depois. Aceita letras sem acento, números, ponto, hífen e underline, até 40 caracteres, com pelo menos uma letra ou número. Nomes fora dessa regra são recusados com status 400.

rejectCallbooleanOpcional

Rejeita automaticamente chamadas recebidas.

msgCallstringOpcional

Mensagem enviada automaticamente ao rejeitar uma chamada.

groupsIgnorebooleanOpcional

Ignora eventos de grupos no webhook.

alwaysOnlinebooleanOpcional

Mantém a conta sempre online no WhatsApp.

readMessagesbooleanOpcional

Marca automaticamente as mensagens como lidas.

syncFullHistorybooleanOpcional

Sincroniza o histórico completo do WhatsApp ao conectar.

saveMediabooleanOpcional

Se false, a mídia recebida não é armazenada (o webhook fica sem mediaUrl). Default: true (armazena).

webhook.enabledbooleanOpcional

Ativa o webhook na criação. O webhook só é configurado se uma URL válida também for fornecida.

webhook.urlstringOpcional

URL HTTPS pública que receberá os eventos. Bloqueado: localhost, IPs privados e redes internas (proteção SSRF).

webhook.headersobjectOpcional

Headers HTTP enviados junto com cada evento (ex: Authorization). Aceita até 20, nomes únicos ignorando maiúsculas, e exige URL https.

webhook.eventsstring[]Opcional

Lista de eventos para filtrar. Se omitida, nenhum evento é entregue

webhook.base64booleanOpcional

Se true, mídias nos eventos vêm codificadas em base64.

proxyHoststringOpcional

Proxy: host público (Enterprise).

proxyPortstringOpcional

Proxy: porta (Enterprise).

proxyProtocolstringOpcional

Proxy: "http", "https" ou "socks5" (Enterprise).

proxyUsernamestringOpcional

Proxy: usuário (Enterprise).

proxyPasswordstringOpcional

Proxy: senha (Enterprise).

migrationobjectOpcional

Migração de sessão Baileys já autenticada. Restrito ao plano Enterprise. Estrutura: { creds: object, preKeys: array }. Resposta inclui migration: { jid, preKeysImported, connected }.

curl -X POST https://api.whatsmiau.dev/v2/instance/create \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "instanceName": "Marketing01"
}'

curl -X POST https://api.whatsmiau.dev/v2/instance/create \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "instanceName": "Marketing01",
  "rejectCall": true,
  "msgCall": "Não atendemos ligações neste número.",
  "alwaysOnline": true,
  "readMessages": true,
  "webhook": {
    "enabled": true,
    "url": "https://meusite.com/webhook",
    "events": ["messages.upsert", "connection.update"]
  }
}'

const response = await fetch(
  "https://api.whatsmiau.dev/v2/instance/create",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "apikey": "SUA_CHAVE_AQUI"
    },
    body: JSON.stringify({
      instanceName: "Marketing01",
      rejectCall: true,
      alwaysOnline: true,
      webhook: {
        enabled: true,
        url: "https://meusite.com/webhook",
        events: ["messages.upsert", "connection.update"]
      }
    })
  }
);
const data = await response.json();
console.log(data.id);          // "Marketing01"
console.log(data.state);       // "connecting"

GET

Listar Instâncias

/instance/fetchInstances

Retorna todas as instâncias da sua conta com o estado atual. Uma suspensão nunca é causada apenas por exceder o limite do plano. Itens suspensos vêm com state: 'closed', suspended: true e suspension_reason.

curl -X GET https://api.whatsmiau.dev/v2/instance/fetchInstances \
  -H "apikey: SUA_CHAVE"

{
  "id": "Marketing01",
  "instanceName": "Marketing01",
  "state": "closed",
  "suspended": true,
  "suspension_reason": "billing_past_due"
}

GET

Conectar Instância

/instance/connect/:name

Inicia a conexão e retorna o QR Code (base64) + pairing code quando disponível. Se o acesso estiver suspenso, retorna HTTP 423 com suspension_reason; uma decisão administrativa só pode ser revertida no painel Admin.

namestringObrigatório

Nome da instância (o mesmo "instanceName" usado ao criar).

numberstringOpcional

Número de telefone com DDI para receber pairing code em vez de QR Code (ex: 5511999998888).

curl -X GET https://api.whatsmiau.dev/v2/instance/connect/Marketing01 \
  -H "apikey: SUA_CHAVE"

{
  "id": "Marketing01",
  "connected": false,
  "base64": "data:image/png;base64,iVBORw0KGgoAAAANS...",
  "pairingCode": "ABCD-1234"
}

{
  "error": "instance suspended",
  "suspension_reason": "administrative"
}

GET

QR Code como PNG

/instance/connect/:name/image

Retorna o QR Code como imagem PNG pura (Content-Type: image/png). Útil para incorporar em páginas HTML via <img />. Retorna 204 No Content se a instância já estiver conectada.

namestringObrigatório

Nome da instância.

curl -X GET https://api.whatsmiau.dev/v2/instance/connect/Marketing01/image \
  -H "apikey: SUA_CHAVE" \
  -o qr.png

GET

Estado da Conexão

/instance/connectionState/:name

Retorna o estado atual da instância. Valores: 'open', 'closed', 'connecting' e 'qr-code'. Quando suspensa, retorna 'closed', suspended: true e suspension_reason: administrative, billing_past_due, billing_ended ou billing.

namestringObrigatório

Nome da instância.

curl -X GET https://api.whatsmiau.dev/v2/instance/connectionState/Marketing01 \
  -H "apikey: SUA_CHAVE"

{
  "id": "Marketing01",
  "state": "open",
  "instance": {
    "instanceName": "Marketing01",
    "state": "open"
  }
}

{
  "id": "Marketing01",
  "state": "closed",
  "suspended": true,
  "suspension_reason": "billing_ended",
  "instance": {
    "instanceName": "Marketing01",
    "state": "closed"
  }
}

PUT

Atualizar Instância

/instance/update/:name

Atualiza webhook, comportamento e/ou proxy de uma instância existente. Todos os campos são opcionais: envie apenas os que deseja alterar, os demais permanecem inalterados. 'syncFullHistory' não é alterável por este endpoint. Campos de proxy são restritos ao plano Enterprise.

namestringObrigatório

Nome da instância (path param).

rejectCallbooleanOpcional

Rejeita automaticamente chamadas recebidas.

msgCallstringOpcional

Mensagem enviada automaticamente ao rejeitar uma chamada. Envie "" para remover a mensagem.

groupsIgnorebooleanOpcional

Ignora eventos de grupos no webhook.

alwaysOnlinebooleanOpcional

Mantém a conta sempre online no WhatsApp.

readMessagesbooleanOpcional

Marca automaticamente as mensagens como lidas.

saveMediabooleanOpcional

Se false, a mídia recebida não é armazenada (o webhook fica sem mediaUrl). Default: true (armazena).

webhook.enabledbooleanOpcional

Ativa/desativa o webhook.

webhook.urlstringOpcional

URL HTTPS que receberá os eventos. Bloqueado: localhost, IPs privados e redes internas.

webhook.headersobjectOpcional

Headers HTTP enviados junto com cada evento (ex: Authorization). Aceita até 20, nomes únicos ignorando maiúsculas, e exige URL https.

webhook.eventsstring[]Opcional

Filtro de eventos (ex: messages.upsert, connection.update).

webhook.base64booleanOpcional

Se true, mídias nos eventos vêm codificadas em base64.

proxyHoststringOpcional

Host público do proxy (Enterprise).

proxyPortstringOpcional

Porta do proxy (Enterprise).

proxyProtocolstringOpcional

"http", "https" ou "socks5" (Enterprise).

proxyUsernamestringOpcional

Usuário do proxy (Enterprise).

proxyPasswordstringOpcional

Senha do proxy (Enterprise).

curl -X PUT https://api.whatsmiau.dev/v2/instance/update/Marketing01 \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "rejectCall": true,
  "msgCall": "Não atendemos ligações neste número.",
  "alwaysOnline": true,
  "readMessages": true
}'

curl -X PUT https://api.whatsmiau.dev/v2/instance/update/Marketing01 \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "webhook": {
    "enabled": true,
    "url": "https://meusite.com/webhook",
    "events": ["messages.upsert", "connection.update"]
  }
}'

DELETE

Desconectar (Logout)

/instance/logout/:name

Encerra a sessão WhatsApp mas mantém a instância criada. Para reconectar depois, basta chamar /instance/connect/:name novamente. Para remover permanentemente, use Deletar Instância.

namestringObrigatório

Nome da instância.

curl -X DELETE https://api.whatsmiau.dev/v2/instance/logout/Marketing01 \
  -H "apikey: SUA_CHAVE"

DELETE

Deletar Instância

/instance/delete/:name

Remove permanentemente a instância no Core e, somente após essa confirmação, no Manager. Aceita o nome público, o ID completo do Core ou o ID interno retornado pelas APIs legadas. Pode responder 404 (não encontrada), 409 (exclusão já em andamento) ou 502 (Core não confirmou; o registro foi preservado para nova tentativa).

namestringObrigatório

Nome da instância (o mesmo "instanceName" usado ao criar).

curl -X DELETE https://api.whatsmiau.dev/v2/instance/delete/Marketing01 -H "apikey: SUA_CHAVE"

Mensagens

Envie mensagens de texto, imagens, vídeos, áudios e documentos para qualquer número do WhatsApp.

POST

Enviar Texto

/message/sendText/:instance

Envia uma mensagem de texto simples. Suporta emojis.

numberstringObrigatório

Número do destinatário com DDI e DDD (ex: 5511999998888).

textstringObrigatório

O texto a ser enviado.

delaynumberOpcional

Atraso em milissegundos antes de enviar (máx: 110000).

linkPreviewbooleanOpcional

Exibe uma prévia do link com título, descrição e imagem obtidos da página. A URL deve estar no texto. Quando aparece no início, é substituída pela prévia, mantendo o restante da mensagem.

linkPreviewImagestringOpcional

Customização do card: imagem (URL http(s) ou base64 puro ou data URI). A imagem é limitada a 5 MiB; enviada em base64, o limite é da requisição inteira (4 MiB), o que dá ~3 MiB de imagem. Ao enviar, o card é montado com os seus valores e a página não é buscada.

linkPreviewTitlestringOpcional

Customização do card: título. Vazio com linkPreviewImage envia um card só com a imagem.

linkPreviewDescriptionstringOpcional

Customização do card: descrição.

linkPreviewLargebooleanOpcional

Envia a imagem em tamanho cheio para o card grande (padrão: true). Use false para o card pequeno. Vale para o card automático e o customizado.

mentionsEveryOnebooleanOpcional

Mencionar todos em grupos. O texto precisa conter o literal @all para o destaque aparecer.

mentionedstring[]Opcional

Lista de JIDs a mencionar.

quotedobjectOpcional

Mensagem a ser respondida (key.id obrigatório; em grupos, informe key.participant com o número de quem enviou a mensagem, senão a citação não é exibida).

curl -X POST https://api.whatsmiau.dev/v2/message/sendText/Marketing01 \
  -H "apikey: KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "number": "5511999998888",
  "text": "Olá! 👋",
  "delay": 1200
}'

fetch('https://api.whatsmiau.dev/v2/message/sendText/Marketing01', {
  method: 'POST',
  headers: { 'apikey': 'KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    number: "5511999998888",
    text: "Olá! 👋"
  })
})

POST

Enviar Mídia

/message/sendMedia/:instance

Envia imagens, vídeos ou documentos via URL pública.

numberstringObrigatório

Número do destinatário.

mediatypestringObrigatório

"image", "video" ou "document".

mediastringObrigatório

URL pública do arquivo.

captionstringOpcional

Legenda da mídia.

fileNamestringOpcional

Nome do arquivo (para documentos).

mimetypestringOpcional

MIME type do arquivo.

delaynumberOpcional

Atraso em milissegundos (máx: 110000).

quotedobjectOpcional

Mensagem a ser respondida (key.id obrigatório; em grupos, informe key.participant com o número de quem enviou a mensagem, senão a citação não é exibida).

mentionsEveryOnebooleanOpcional

Mencionar todos em grupos. O texto precisa conter o literal @all para o destaque aparecer.

mentionedstring[]Opcional

Lista de JIDs a mencionar.

curl -X POST https://api.whatsmiau.dev/v2/message/sendMedia/Marketing01 \
  -H "apikey: KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "number": "5511999998888",
  "mediatype": "image",
  "media": "https://example.com/image.png",
  "caption": "Confira!"
}'

POST

Enviar Áudio (PTT)

/message/sendWhatsAppAudio/:instance

Envia um arquivo de áudio como se fosse gravado na hora (Push-To-Talk).

numberstringObrigatório

Número do destinatário.

audiostringObrigatório

URL pública do arquivo MP3/OGG.

delaynumberOpcional

Atraso em milissegundos (máx: 110000).

encodingbooleanOpcional

Re-encodar o áudio antes de enviar.

quotedobjectOpcional

Mensagem a ser respondida (key.id obrigatório; em grupos, informe key.participant com o número de quem enviou a mensagem, senão a citação não é exibida).

mentionsEveryOnebooleanOpcional

Mencionar todos em grupos. O texto precisa conter o literal @all para o destaque aparecer.

mentionedstring[]Opcional

Lista de JIDs a mencionar.

curl -X POST https://api.whatsmiau.dev/v2/message/sendWhatsAppAudio/Marketing01 \
  -H "apikey: KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "number": "5511999998888",
  "audio": "https://example.com/voice.mp3"
}'

POST

Enviar Lista

/message/sendList/:instance

Envia uma mensagem interativa com lista de opções para o usuário selecionar. Ideal para menus, catálogos e formulários simples.

numberstringObrigatório

Número do destinatário (ex: 5511999998888).

titlestringOpcional

Título da mensagem.

descriptionstringObrigatório

Descrição/corpo da mensagem.

buttonTextstringOpcional

Texto do botão que abre a lista.

footerTextstringOpcional

Texto do rodapé.

sectionsarrayObrigatório

Seções da lista, cada uma com title e rows[].

sections[].titlestringOpcional

Título da seção.

sections[].rows[].titlestringObrigatório

Título da opção.

sections[].rows[].descriptionstringOpcional

Descrição da opção.

sections[].rows[].rowIdstringObrigatório

ID único da opção (retornado no webhook).

curl -X POST https://api.whatsmiau.dev/v2/message/sendList/Marketing01 \
  -H "apikey: KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "number": "5511999998888",
  "title": "Nossos Planos",
  "description": "Escolha o plano ideal para você:",
  "buttonText": "Ver opções",
  "footerText": "Whatsmiau Cloud",
  "sections": [
    {
      "title": "Planos",
      "rows": [
        { "title": "Starter", "description": "R$ 30/mês - 1 instância", "rowId": "plan_starter" },
        { "title": "Pro", "description": "R$ 90/mês - 5 instâncias", "rowId": "plan_pro" },
        { "title": "Enterprise", "description": "R$ 200/mês - 15 instâncias", "rowId": "plan_enterprise" }
      ]
    }
  ]
}'

const response = await fetch(
  "https://api.whatsmiau.dev/v2/message/sendList/Marketing01",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "apikey": "SUA_CHAVE_AQUI"
    },
    body: JSON.stringify({
      number: "5511999998888",
      title: "Nossos Planos",
      description: "Escolha o plano ideal para você:",
      buttonText: "Ver opções",
      sections: [
        {
          title: "Planos",
          rows: [
            { title: "Starter", description: "R$ 30/mês", rowId: "plan_starter" },
            { title: "Pro", description: "R$ 90/mês", rowId: "plan_pro" }
          ]
        }
      ]
    })
  }
);

POST

Enviar Botões

/message/sendButtons/:instance

Envia uma mensagem com botões interativos de resposta rápida. Suporta botões de resposta (reply) e botões PIX.

numberstringObrigatório

Número do destinatário (ex: 5511999998888).

titlestringOpcional

Título da mensagem.

descriptionstringObrigatório

Corpo da mensagem.

footerstringOpcional

Texto do rodapé.

buttonsarrayObrigatório

Lista de botões (máximo 3).

buttons[].typestringObrigatório

"reply" para resposta rápida ou "pix" para pagamento.

buttons[].displayTextstringObrigatório

Texto exibido no botão.

buttons[].idstringOpcional

ID do botão (retornado no webhook ao clicar). Usado com type "reply".

buttons[].currencystringOpcional

Moeda do PIX (ex: "BRL"). Obrigatório quando type é "pix".

buttons[].namestringOpcional

Nome do recebedor PIX. Obrigatório quando type é "pix".

buttons[].keyTypestringOpcional

Tipo da chave PIX: "email", "cpf", "cnpj", "phone" ou "random". Obrigatório quando type é "pix".

buttons[].keystringOpcional

Chave PIX do recebedor. Obrigatório quando type é "pix".

curl -X POST https://api.whatsmiau.dev/v2/message/sendButtons/Marketing01 \
  -H "apikey: KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "number": "5511999998888",
  "title": "Confirmar Pedido",
  "description": "Deseja confirmar o pedido #1234?",
  "footer": "Whatsmiau Cloud",
  "buttons": [
    { "type": "reply", "displayText": "Sim, confirmar", "id": "confirm_yes" },
    { "type": "reply", "displayText": "Não, cancelar", "id": "confirm_no" }
  ]
}'

const response = await fetch(
  "https://api.whatsmiau.dev/v2/message/sendButtons/Marketing01",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "apikey": "SUA_CHAVE_AQUI"
    },
    body: JSON.stringify({
      number: "5511999998888",
      title: "Confirmar Pedido",
      description: "Deseja confirmar o pedido #1234?",
      buttons: [
        { type: "reply", displayText: "Sim, confirmar", id: "confirm_yes" },
        { type: "reply", displayText: "Não, cancelar", id: "confirm_no" }
      ]
    })
  }
);

POST

Enviar Figurinha

/message/sendSticker/:instance

Envia uma figurinha (sticker) a partir de uma URL pública. O arquivo precisa estar em formato WebP para uso direto; outros formatos podem ser convertidos automaticamente.

numberstringObrigatório

Número do destinatário (ex: 5511999998888).

stickerstringObrigatório

URL pública do arquivo WebP.

delaynumberOpcional

Atraso em milissegundos antes de enviar (máx: 110000).

notConvertStickerbooleanOpcional

Se true, não tenta converter o arquivo antes de enviar.

quotedobjectOpcional

Mensagem a ser respondida (key.id obrigatório; em grupos, informe key.participant com o número de quem enviou a mensagem, senão a citação não é exibida).

mentionsEveryOnebooleanOpcional

Mencionar todos em grupos. O texto precisa conter o literal @all para o destaque aparecer.

mentionedstring[]Opcional

Lista de JIDs a mencionar.

curl -X POST https://api.whatsmiau.dev/v2/message/sendSticker/Marketing01 \
  -H "apikey: KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "number": "5511999998888",
  "sticker": "https://example.com/sticker.webp"
}'

POST

Enviar Localização

/message/sendLocation/:instance

Envia um pin de localização geográfica. Funciona com coordenadas em graus decimais.

numberstringObrigatório

Número do destinatário (ex: 5511999998888).

latitudenumberObrigatório

Latitude em graus decimais (ex: -23.55052).

longitudenumberObrigatório

Longitude em graus decimais (ex: -46.633308).

namestringOpcional

Nome/rótulo do local (ex: "Av. Paulista, 1000").

addressstringOpcional

Endereço textual complementar.

delaynumberOpcional

Atraso em milissegundos (máx: 110000).

quotedobjectOpcional

Mensagem a ser respondida (key.id obrigatório; em grupos, informe key.participant com o número de quem enviou a mensagem, senão a citação não é exibida).

curl -X POST https://api.whatsmiau.dev/v2/message/sendLocation/Marketing01 \
  -H "apikey: KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "number": "5511999998888",
  "latitude": -23.55052,
  "longitude": -46.633308,
  "name": "MASP",
  "address": "Av. Paulista, 1578"
}'

POST

Enviar Contato

/message/sendContact/:instance

Envia um ou mais cartões de contato (vCard). Para múltiplos contatos, envie um único array — o WhatsApp agrupa automaticamente.

numberstringObrigatório

Número do destinatário (ex: 5511999998888).

contactarrayObrigatório

Lista de contatos a enviar.

contact[].fullNamestringObrigatório

Nome completo do contato.

contact[].phoneNumberstringObrigatório

Número de telefone do contato.

contact[].wuidstringOpcional

WhatsApp UID do contato (se souber).

contact[].organizationstringOpcional

Organização/empresa.

contact[].emailstringOpcional

E-mail do contato.

contact[].urlstringOpcional

Website do contato.

delaynumberOpcional

Atraso em milissegundos (máx: 110000).

quotedobjectOpcional

Mensagem a ser respondida (key.id obrigatório; em grupos, informe key.participant com o número de quem enviou a mensagem, senão a citação não é exibida).

curl -X POST https://api.whatsmiau.dev/v2/message/sendContact/Marketing01 \
  -H "apikey: KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "number": "5511999998888",
  "contact": [
    {
      "fullName": "Ivo Silva",
      "phoneNumber": "5511999997777",
      "organization": "Verboo",
      "email": "ivo@verboo.com.br"
    }
  ]
}'

POST

Enviar Enquete

/message/sendPoll/:instance

Cria uma enquete com opções para o destinatário votar. O voto chega via webhook como evento pollUpdateMessage.

numberstringObrigatório

Número do destinatário (ex: 5511999998888).

namestringObrigatório

Pergunta da enquete.

valuesstring[]Obrigatório

Opções de resposta (mínimo 2, máximo 12).

selectableCountnumberOpcional

Quantas opções o usuário pode escolher. 0 = apenas 1 voto (padrão). Use 1..N para múltipla escolha.

delaynumberOpcional

Atraso em milissegundos (máx: 110000).

quotedobjectOpcional

Mensagem a ser respondida (key.id obrigatório; em grupos, informe key.participant com o número de quem enviou a mensagem, senão a citação não é exibida).

curl -X POST https://api.whatsmiau.dev/v2/message/sendPoll/Marketing01 \
  -H "apikey: KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "number": "5511999998888",
  "name": "Qual o melhor horário?",
  "values": ["Manhã", "Tarde", "Noite"],
  "selectableCount": 1
}'

POST

Enviar Vídeo Redondo (PTV)

/message/sendPtv/:instance

Envia uma mensagem de vídeo circular curto (Push-To-Video), similar ao áudio PTT mas com vídeo. Use arquivos curtos (<= 60s) em MP4.

numberstringObrigatório

Número do destinatário (ex: 5511999998888).

videostringObrigatório

URL pública do arquivo MP4.

delaynumberOpcional

Atraso em milissegundos (máx: 110000).

quotedobjectOpcional

Mensagem a ser respondida (key.id obrigatório; em grupos, informe key.participant com o número de quem enviou a mensagem, senão a citação não é exibida).

mentionsEveryOnebooleanOpcional

Mencionar todos em grupos. O texto precisa conter o literal @all para o destaque aparecer.

mentionedstring[]Opcional

Lista de JIDs a mencionar.

curl -X POST https://api.whatsmiau.dev/v2/message/sendPtv/Marketing01 \
  -H "apikey: KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "number": "5511999998888",
  "video": "https://example.com/short.mp4"
}'

POST

Enviar Status

/message/sendStatus/:instance

Publica um status (broadcast) visível para todos os contatos ou apenas para uma lista específica. Suporta texto, imagem, áudio e vídeo.

typestringObrigatório

"text", "image", "audio" ou "video".

contentstringObrigatório

Texto do status OU URL pública do arquivo de mídia.

captionstringOpcional

Legenda (apenas para imagem/vídeo).

backgroundColorstringOpcional

Cor de fundo em HEX para status de texto (ex: "#FF5733").

fontnumberOpcional

Índice da fonte para texto (0-5).

allContactsbooleanOpcional

Se true, envia para todos os contatos.

statusJidListstring[]Opcional

Lista de JIDs específicos que vão ver o status (ignorado se allContacts=true).

curl -X POST https://api.whatsmiau.dev/v2/message/sendStatus/Marketing01 \
  -H "apikey: KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "text",
  "content": "Estamos com desconto hoje! 🎉",
  "backgroundColor": "#FF5733",
  "font": 2,
  "allContacts": true
}'

curl -X POST https://api.whatsmiau.dev/v2/message/sendStatus/Marketing01 \
  -H "apikey: KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "image",
  "content": "https://example.com/promo.jpg",
  "caption": "Promoção relâmpago!",
  "statusJidList": ["5511999998888@s.whatsapp.net"]
}'

Chat & Presença

Gerencie o estado do chat, reações e verificações de número.

POST

Enviar Reação

/message/sendReaction/:instance

Reage a uma mensagem específica com um emoji.

reactionstringObrigatório

Emoji da reação (ex: 👍, ❤️). String de 1 caractere.

keyobjectObrigatório

Chave da mensagem alvo.

remoteJidstringObrigatório

JID do chat (ex: 5511...@s.whatsapp.net).

idstringObrigatório

ID da mensagem alvo.

fromMebooleanObrigatório

Se a mensagem foi enviada por você.

curl -X POST https://api.whatsmiau.dev/v2/message/sendReaction/Marketing01 \
  -H "apikey: KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "reaction": "👍",
  "key": {
    "remoteJid": "5511999998888@s.whatsapp.net",
    "id": "3EB0XXXXXXXX",
    "fromMe": false
  }
}'

POST

Enviar Presença

/chat/sendPresence/:instance

Simula o status de presença (digitando, gravando áudio, online) em um chat.

numberstringObrigatório

Número do chat alvo (ex: 5511999998888).

presencestringObrigatório

"composing" (digitando) ou "available" (online).

typestringOpcional

"text" ou "audio". Define o tipo de presença.

delaynumberOpcional

Duração em milissegundos (máx: 110000).

curl -X POST https://api.whatsmiau.dev/v2/chat/sendPresence/Marketing01 \
  -H "apikey: KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "number": "5511999998888",
  "presence": "composing",
  "type": "text",
  "delay": 3000
}'

POST

Marcar como Lido

/chat/markMessageAsRead/:instance

Marca mensagens específicas como lidas.

readMessagesobject[]Obrigatório

Array de mensagens a marcar como lidas.

remoteJidstringObrigatório

JID do chat (ex: 5511...@s.whatsapp.net).

idstringObrigatório

ID da mensagem.

senderstringOpcional

JID do remetente (obrigatório em grupos).

curl -X POST https://api.whatsmiau.dev/v2/chat/markMessageAsRead/Marketing01 \
  -H "apikey: KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "readMessages": [
    {
      "remoteJid": "5511999998888@s.whatsapp.net",
      "id": "3EB0XXXXXXXX"
    }
  ]
}'

POST

Verificar Número

/chat/whatsappNumbers/:instance

Verifica se um número está registrado no WhatsApp.

numbersstring[]Obrigatório

Lista de números para verificar.

curl -X POST https://api.whatsmiau.dev/v2/chat/whatsappNumbers/Marketing01 \
  -H "apikey: KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "numbers": ["5511999998888"]
}'

POST

Editar Mensagem

/chat/updateMessage/:instance

Edita o texto de uma mensagem enviada por você.

numberstringObrigatório

Número do chat alvo (ex: 5511999998888).

textstringObrigatório

Novo texto da mensagem.

keyobjectObrigatório

Chave da mensagem original a ser editada.

remoteJidstringObrigatório

JID do chat (ex: 5511...@s.whatsapp.net).

idstringObrigatório

ID da mensagem original.

fromMebooleanObrigatório

Se a mensagem foi enviada por você.

curl -X POST https://api.whatsmiau.dev/v2/chat/updateMessage/Marketing01 \
  -H "apikey: KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "number": "5511999998888",
  "text": "Mensagem editada",
  "key": {
    "remoteJid": "5511999998888@s.whatsapp.net",
    "id": "3EB0XXXXXXXX",
    "fromMe": true
  }
}'

POST

Buscar Foto de Perfil

/chat/fetchProfilePictureUrl/:instance

Retorna a URL da foto de perfil em resolução cheia de um número, contato ou grupo. Retorna profilePictureUrl como null quando o alvo não tem foto ou a escondeu.

numberstringObrigatório

Número do contato (ex: 5511999998888), JID completo (5511...@s.whatsapp.net) ou JID de grupo (120363...@g.us).

curl -X POST https://api.whatsmiau.dev/v2/chat/fetchProfilePictureUrl/Marketing01 \
  -H "apikey: KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "number": "5511999998888"
}'

DELETE

Deletar Mensagem

/chat/deleteMessageForEveryone/:instance

Revoga (apaga para todos) uma mensagem enviada ou recebida em um chat individual ou grupo.

idstringObrigatório

ID da mensagem a ser deletada.

remoteJidstringObrigatório

JID do chat (ex: 5511999998888@s.whatsapp.net ou grupo@g.us).

fromMebooleanObrigatório

Se a mensagem foi enviada por você (true) ou recebida (false).

participantstringOpcional

JID do remetente original. Obrigatório ao deletar mensagem de outro participante em grupos.

curl -X DELETE https://api.whatsmiau.dev/v2/chat/deleteMessageForEveryone/Marketing01 \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "3EB0XXXXXXXX",
  "remoteJid": "5511999998888@s.whatsapp.net",
  "fromMe": true
}'

curl -X DELETE https://api.whatsmiau.dev/v2/chat/deleteMessageForEveryone/Marketing01 \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "3EB0XXXXXXXX",
  "remoteJid": "120363XXXXX@g.us",
  "fromMe": false,
  "participant": "5511999998888"
}'

POST

Sincronizar Mensagens do Chat

/chat/syncMessages/:instance

Solicita o histórico de mensagens de um chat diretamente do dispositivo principal do usuário. Requer que a conta do WhatsApp (número) esteja com uma sessão autenticada e conectada aos servidores no dispositivo primário. A busca é retroativa a partir da mensagem âncora informada (`id`), que é obrigatória. O limite máximo por requisição é de 500 mensagens.

numberstringObrigatório

Número do contato (ex: 5511999998888), JID completo (5511...@s.whatsapp.net) ou JID de grupo (120363...@g.us).

idstringObrigatório

ID de uma mensagem conhecida do chat (de um webhook anterior). Define a âncora: retorna as mensagens anteriores a ela.

countnumberOpcional

Quantidade de mensagens por página. Padrão: 50.

sincestringOpcional

Data limite (YYYY-MM-DD ou RFC3339). Pagina o histórico até atingir essa data.

fromMebooleanOpcional

Se a mensagem âncora foi enviada por você (true) ou recebida (false). Recomenda-se enviar para maior confiabilidade na localização da âncora pelo celular.

curl -X POST https://api.whatsmiau.dev/v2/chat/syncMessages/Marketing01 \
  -H "apikey: KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "number": "5511999998888@s.whatsapp.net",
  "id": "3EB0XXXXXXXX",
  "fromMe": true,
  "count": 50
}'

Uso recomendado: esta rota recupera o histórico de mensagens por chat. Recomendamos que esta rota não seja utilizada para extração em massa de histórico.

Ligações

Experimental

Inicie e controle ligações de áudio diretas (1:1) e transporte o áudio em tempo real por WebSocket. Os endpoints seguem o contrato Evolution; não há rotas equivalentes sob /z-api nem callback traduzido para esse formato.

O operador da infraestrutura deve configurar CALLS_ENABLED=true no core. Depois de habilitar a opção, reconecte a instância antes de iniciar uma ligação.

Use o header apikey ou um Bearer JWT nos endpoints REST. No WebSocket de áudio, envie apikey durante o handshake; credenciais em query string não são aceitas.

POST

Iniciar ligação de áudio

/instance/:instance/calls

Cria uma ligação de áudio direta para um número ou JID do WhatsApp. Retorna HTTP 201 com o ID da ligação; as chaves capitalizadas da resposta fazem parte do contrato de compatibilidade. Use o evento call ou a listagem para acompanhar o estado.

numberstringObrigatório

Número com DDI e DDD ou JID do WhatsApp do destinatário.

curl -X POST https://api.whatsmiau.dev/v2/instance/Atendimento01/calls \
  -H "apikey: SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{"number":"5511999999999"}'

{
  "ID": "ABCD1234",
  "Recipient": "5511999999999@s.whatsapp.net"
}

GET

Listar ligações

/instance/:instance/calls

Lista as sessões de ligação mantidas pela instância, com estado e ações permitidas. Dados de mídia, SDP, relays e chaves de sessão nunca fazem parte da resposta.

curl https://api.whatsmiau.dev/v2/instance/Atendimento01/calls \
  -H "apikey: SUA_CHAVE_AQUI"

[
  {
    "ID": "ABCD1234",
    "Peer": "5511999999999@s.whatsapp.net",
    "Direction": "incoming",
    "Media": "audio",
    "State": "ringing",
    "Reason": "",
    "CanAnswer": true,
    "CanReject": true,
    "CanHangup": true,
    "CreatedAt": "2026-08-15T12:00:00Z",
    "UpdatedAt": "2026-08-15T12:00:01Z"
  }
]

POST

Atender ligação

/instance/:instance/calls/:callID/answer

Atende uma ligação recebida que esteja tocando. Consulte CanAnswer na sessão antes de executar a ação.

curl -X POST https://api.whatsmiau.dev/v2/instance/Atendimento01/calls/ABCD1234/answer \
  -H "apikey: SUA_CHAVE_AQUI"

{
  "status": "ok"
}

POST

Rejeitar ligação

/instance/:instance/calls/:callID/reject

Rejeita uma ligação recebida que esteja tocando. Consulte CanReject na sessão antes de executar a ação.

curl -X POST https://api.whatsmiau.dev/v2/instance/Atendimento01/calls/ABCD1234/reject \
  -H "apikey: SUA_CHAVE_AQUI"

{
  "status": "ok"
}

POST

Encerrar ligação

/instance/:instance/calls/:callID/hangup

Encerra uma ligação tocando, sendo conectada ou ativa. Consulte CanHangup na sessão antes de executar a ação.

curl -X POST https://api.whatsmiau.dev/v2/instance/Atendimento01/calls/ABCD1234/hangup \
  -H "apikey: SUA_CHAVE_AQUI"

{
  "status": "ok"
}

GET

Áudio da ligação via WebSocket

/instance/:instance/calls/:callID/audio

Abre uma ponte de áudio bidirecional. Cada mensagem deve ser binária e conter exatamente 3.840 bytes: 960 amostras float32 little-endian, PCM mono a 16 kHz, equivalentes a 60 ms. Texto, tamanhos diferentes e mensagens agregando vários frames encerram a conexão. O WebSocket transporta apenas PCM — SDP, mídia criptografada, relays e chaves não são expostos.

npx wscat \
  -c "wss://api.whatsmiau.dev/v2/instance/Atendimento01/calls/ABCD1234/audio" \
  -H "apikey: SUA_CHAVE_AQUI"

import WebSocket from "ws";

const socket = new WebSocket(
  "wss://api.whatsmiau.dev/v2/instance/Atendimento01/calls/ABCD1234/audio",
  { headers: { apikey: "SUA_CHAVE_AQUI" } }
);

socket.on("message", (pcm, isBinary) => {
  if (!isBinary || pcm.length !== 3840) return;
  // pcm contém 960 amostras float32 LE, mono, 16 kHz.
});

// Envie exatamente um frame de 3.840 bytes por mensagem.
socket.send(framePCMFloat32LE);

A API nativa WebSocket dos navegadores não permite definir o header apikey. Para aplicações web, faça o handshake em um backend autorizado e retransmita o áudio ao navegador sem expor sua chave. Uma conexão pública pode durar até 60 minutos; trate o fechamento e reconecte enquanto a sessão continuar ativa.

Webhooks

Configure webhooks para receber eventos em tempo real via HTTP POST.

POST

Configurar Webhook

/webhook/set/:instance

Define ou atualiza a configuração de webhook para uma instância. Permite configurar URL de destino, eventos que serão enviados e formato do payload.

webhook.enabledbooleanOpcional

Ativa ou desativa o webhook.

webhook.urlstringOpcional

URL que receberá os eventos via POST.

webhook.headersobjectOpcional

Headers HTTP enviados junto com cada evento (ex: Authorization). Aceita até 20, nomes únicos ignorando maiúsculas, e exige URL https.

webhook.eventsstring[]Opcional

Lista de eventos para filtrar. Se omitida, nenhum evento é entregue

webhook.base64booleanOpcional

Se true, codifica o payload em base64.

curl -X POST https://api.whatsmiau.dev/v2/webhook/set/MinhaInstancia \
  -H "Content-Type: application/json" \
  -H "apikey: SUA_CHAVE_AQUI" \
  -d '{
    "webhook": {
      "enabled": true,
      "url": "https://meusite.com/webhook",
      "events": ["messages.upsert", "connection.update", "call"]
    }
  }'

const response = await fetch(
  "https://api.whatsmiau.dev/v2/webhook/set/MinhaInstancia",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "apikey": "SUA_CHAVE_AQUI"
    },
    body: JSON.stringify({
      webhook: {
        enabled: true,
        url: "https://meusite.com/webhook",
        events: ["messages.upsert", "connection.update", "call"]
      }
    })
  }
);

GET

Consultar Webhook

/webhook/find/:instance

Retorna a configuração atual de webhook para uma instância.

curl -X GET https://api.whatsmiau.dev/v2/webhook/find/MinhaInstancia \
  -H "apikey: SUA_CHAVE_AQUI"

const response = await fetch(
  "https://api.whatsmiau.dev/v2/webhook/find/MinhaInstancia",
  {
    headers: {
      "apikey": "SUA_CHAVE_AQUI"
    }
  }
);
const data = await response.json();
console.log(data.webhook);

Eventos de Webhook

Todos os eventos são enviados como HTTP POST para a URL configurada, dentro de um envelope padrão. O campo data varia conforme o tipo de evento.

Envelope

{
  event: string           // Tipo do evento (ex: "messages.upsert")
  instance: string        // ID da instância
  data: T                 // Payload específico do evento (ver abaixo)
  date_time: string       // Timestamp ISO 8601
  sender: string          // Remetente (quando aplicável)
  server_url: string      // URL do servidor
}

EVENT

messages.upsert

Disparado quando uma nova mensagem é recebida ou enviada. Inclui mensagens de texto, imagens, vídeos, áudios, documentos, reações, contatos, listas e botões.

Campos do payload (data)

keyobject

Identificador da mensagem.

remoteJid string

JID do chat (ex: 5511999999999@s.whatsapp.net).

fromMe boolean

Se a mensagem foi enviada por você.

id string

ID único da mensagem.

participant string?

JID do remetente em grupos.

pushName string

Nome de exibição do remetente.

status string

"sent" ou "received".

messageobject

Conteúdo da mensagem. Apenas um dos campos abaixo estará presente por vez:

conversation string?

Mensagem de texto simples.

imageMessage ImageMessage?

Imagem com url, mimetype, caption, width, height.

videoMessage VideoMessage?

Vídeo com url, mimetype, caption, seconds.

audioMessage AudioMessage?

Áudio com url, mimetype, seconds, ptt (voz).

documentMessage DocumentMessage?

Documento com url, mimetype, fileName, title.

reactionMessage ReactionMessage?

Reação com key (mensagem alvo) e text (emoji).

contactMessage ContactMessage?

Contato com displayName e vCard.

listResponseMessage ListResponseMessage?

Resposta de lista com title e singleSelectReply.selectedRowId.

mediaUrl string?

URL pública da mídia (imagem, áudio, vídeo, documento) após upload no storage.

messageType string

Tipo da mensagem (ex: "conversation", "imageMessage", "audioMessage").

messageTimestamp number

Unix timestamp em segundos.

instanceId string

ID da instância que recebeu a mensagem.

contextInfoobject?

Contexto da mensagem (presente quando é resposta, menção ou mensagem efêmera).

stanzaId string?

ID da mensagem original (quando é resposta).

participant string?

JID do autor da mensagem original.

quotedMessage Message?

Conteúdo da mensagem citada (mesma estrutura de message).

mentionedJid string[]?

Lista de JIDs mencionados na mensagem.

expiration number?

Tempo de expiração em segundos (mensagens efêmeras).

{
  "event": "messages.upsert",
  "instance": "Atendimento01",
  "date_time": "2026-03-30T14:32:00Z",
  "data": {
    "key": {
      "remoteJid": "5511999999999@s.whatsapp.net",
      "fromMe": false,
      "id": "3EB04A2D1F75..."
    },
    "pushName": "Maria Silva",
    "status": "received",
    "message": {
      "conversation": "Olá! Gostaria de saber o status do meu pedido."
    },
    "messageType": "conversation",
    "messageTimestamp": 1743349920,
    "instanceId": "Atendimento01",
    "source": "android"
  }
}

{
  "event": "messages.upsert",
  "instance": "Atendimento01",
  "date_time": "2026-03-30T14:35:00Z",
  "data": {
    "key": {
      "remoteJid": "5511999999999@s.whatsapp.net",
      "fromMe": false,
      "id": "3EB04B3C2E86..."
    },
    "pushName": "Maria Silva",
    "status": "received",
    "message": {
      "imageMessage": {
        "mimetype": "image/jpeg",
        "caption": "Foto do produto",
        "height": 1080,
        "width": 1920,
        "fileLength": "245832"
      },
      "mediaUrl": "https://storage.whatsmiau.io/media/3EB04B3C2E86.jpg"
    },
    "messageType": "imageMessage",
    "messageTimestamp": 1743350100,
    "instanceId": "Atendimento01"
  }
}

{
  "event": "messages.upsert",
  "instance": "Atendimento01",
  "date_time": "2026-03-30T14:40:00Z",
  "data": {
    "key": {
      "remoteJid": "5511999999999@s.whatsapp.net",
      "fromMe": false,
      "id": "3EB04C4D3F97..."
    },
    "pushName": "Maria Silva",
    "status": "received",
    "message": {
      "audioMessage": {
        "mimetype": "audio/ogg; codecs=opus",
        "seconds": 12,
        "ptt": true,
        "fileLength": "18432"
      },
      "mediaUrl": "https://storage.whatsmiau.io/media/3EB04C4D3F97.ogg"
    },
    "messageType": "audioMessage",
    "messageTimestamp": 1743350400,
    "instanceId": "Atendimento01"
  }
}

{
  "event": "messages.upsert",
  "instance": "Atendimento01",
  "date_time": "2026-03-30T14:42:00Z",
  "data": {
    "key": {
      "remoteJid": "5511999999999@s.whatsapp.net",
      "fromMe": false,
      "id": "3EB04E6F5BA9..."
    },
    "pushName": "Maria Silva",
    "status": "received",
    "message": {
      "reactionMessage": {
        "key": {
          "remoteJid": "5511999999999@s.whatsapp.net",
          "fromMe": true,
          "id": "3EB04A2D1F75..."
        },
        "text": "👍"
      }
    },
    "messageType": "reactionMessage",
    "messageTimestamp": 1743350520,
    "instanceId": "Atendimento01"
  }
}

EVENT

messages.edited

Disparado quando uma mensagem é editada. O campo key identifica a mensagem original e editedMessage traz o conteúdo novo.

Campos do payload (data)

key object

Chave da mensagem original (remoteJid, id, fromMe).

editedMessage object

Conteúdo novo da mensagem.

messageType string

Tipo da mensagem (ex: conversation).

pushName string

Nome de exibição de quem editou.

status "received" | "sent"

Se a edição foi recebida ou enviada pela instância.

messageTimestamp number

Timestamp da edição.

source string

Sempre "whatsapp".

instanceId string

ID da instância.

{
  "event": "messages.edited",
  "instance": "Atendimento01",
  "date_time": "2026-03-30T16:00:00Z",
  "data": {
    "key": {
      "remoteJid": "5511999999999@s.whatsapp.net",
      "id": "3EB04A2D1F75...",
      "fromMe": false
    },
    "editedMessage": {
      "conversation": "Texto editado"
    },
    "messageType": "conversation",
    "instanceId": "Atendimento01",
    "pushName": "Pedro Client",
    "status": "received",
    "messageTimestamp": 1708123456,
    "source": "whatsapp"
  }
}

EVENT

messages.update

Disparado quando o status de entrega de uma mensagem muda. Ocorre quando a mensagem é entregue no dispositivo do destinatário (DELIVERY_ACK) ou quando é lida (READ).

Campos do payload (data)

messageId string

ID interno da mensagem.

keyId string

ID da chave da mensagem.

remoteJid string

JID do chat.

fromMe boolean

Se a mensagem foi enviada por você.

participant string

JID do participante (em grupos).

status "DELIVERY_ACK" | "READ"

Novo status da mensagem.

instanceId string

ID da instância.

{
  "event": "messages.update",
  "instance": "Atendimento01",
  "date_time": "2026-03-30T14:33:00Z",
  "data": {
    "messageId": "3EB04A2D1F75...",
    "keyId": "3EB04A2D1F75...",
    "remoteJid": "5511999999999@s.whatsapp.net",
    "fromMe": true,
    "participant": "",
    "status": "DELIVERY_ACK",
    "instanceId": "Atendimento01"
  }
}

{
  "event": "messages.update",
  "instance": "Atendimento01",
  "date_time": "2026-03-30T14:45:00Z",
  "data": {
    "messageId": "3EB04A2D1F75...",
    "keyId": "3EB04A2D1F75...",
    "remoteJid": "5511999999999@s.whatsapp.net",
    "fromMe": true,
    "participant": "",
    "status": "READ",
    "instanceId": "Atendimento01"
  }
}

EVENT

messages.set

Disparado durante a sincronização do histórico completo ao conectar a instância. O WhatsApp envia lotes (batches) de mensagens antigas. Este evento é emitido para cada lote recebido. O payload é um array de mensagens no mesmo formato do messages.upsert.

Para receber este evento, é necessário habilitar a opção Sincronizar Histórico no momento da criação de uma nova instância (parâmetro syncFullHistory: true) e adicionar o evento messages.set na lista de eventos do webhook.

Campos extras do envelope

isLatest boolean

Indica se é o último lote da sincronização (true quando progress ≥ 100).

progress number

Percentual da sincronização (0–100). Útil para mostrar barra de progresso.

Campos do payload (data[])

Cada item do array segue o mesmo formato de mensagem do evento messages.upsert.

key object

Chave da mensagem (remoteJid, id, fromMe).

pushName string

Nome de exibição do remetente.

message object

Conteúdo da mensagem (mesmo formato do messages.upsert).

messageType string

Tipo da mensagem (conversation, imageMessage, etc).

messageTimestamp number

Timestamp Unix da mensagem original.

instanceId string

ID da instância.

{
  "event": "messages.set",
  "instance": "Atendimento01",
  "date_time": "2026-07-04T10:00:00Z",
  "isLatest": false,
  "progress": 45,
  "data": [
    {
      "key": {
        "remoteJid": "5511999999999@s.whatsapp.net",
        "id": "3EB04A2D1F75...",
        "fromMe": false
      },
      "pushName": "5511999999999",
      "message": {
        "conversation": "Olá, tudo bem?"
      },
      "messageType": "conversation",
      "messageTimestamp": 1719878400,
      "instanceId": "Atendimento01"
    }
  ]
}

{
  "event": "messages.set",
  "instance": "Atendimento01",
  "date_time": "2026-07-04T10:02:30Z",
  "isLatest": true,
  "progress": 100,
  "data": []
}

EVENT

connection.update

Disparado quando o estado da conexão muda. Ocorre ao conectar com sucesso (escaneou QR Code), ao desconectar (logout, perda de sessão) ou em falhas de conexão.

Campos do payload (data)

instance string

ID da instância.

wuid string

WhatsApp UID (número conectado). Presente apenas quando state = "open".

profileName string

Nome do perfil do WhatsApp. Presente apenas quando state = "open".

profilePictureUrl string?

URL da foto de perfil (quando disponível).

state "open" | "close"

Estado atual da conexão.

statusReason number

Código do motivo (200 = sucesso, outros = erro).

{
  "event": "connection.update",
  "instance": "Atendimento01",
  "date_time": "2026-03-30T10:00:00Z",
  "data": {
    "instance": "Atendimento01",
    "wuid": "5511999998888@s.whatsapp.net",
    "profileName": "Meu Negócio",
    "profilePictureUrl": "https://pps.whatsapp.net/v/t61...",
    "state": "open",
    "statusReason": 200
  }
}

{
  "event": "connection.update",
  "instance": "Atendimento01",
  "date_time": "2026-03-30T18:00:00Z",
  "data": {
    "instance": "Atendimento01",
    "wuid": "",
    "profileName": "",
    "state": "close",
    "statusReason": 408
  }
}

EVENT

contacts.upsert

Disparado quando um contato ou grupo é criado ou atualizado. Inclui mudanças de nome de exibição (push name), nome comercial, foto de perfil, informações de grupo e sincronização de histórico. O payload é um array de contatos.

Campos do payload (data[])

remoteJid string

JID do contato ou grupo.

remoteLid string

LID do contato (identificador alternativo).

pushName string

Nome de exibição do contato.

profilePicUrl string

URL da foto de perfil.

instanceId string

ID da instância.

Gatilhos: Mudança de push name, nome comercial (WhatsApp Business), foto de perfil, criação/atualização de grupo, sincronização de histórico de contatos.

{
  "event": "contacts.upsert",
  "instance": "Atendimento01",
  "date_time": "2026-03-30T15:00:00Z",
  "data": [
    {
      "remoteJid": "5511999999999@s.whatsapp.net",
      "remoteLid": "",
      "pushName": "Maria Silva",
      "profilePicUrl": "https://pps.whatsapp.net/v/t61...",
      "instanceId": "Atendimento01"
    }
  ]
}

{
  "event": "contacts.upsert",
  "instance": "Atendimento01",
  "date_time": "2026-03-30T15:05:00Z",
  "data": [
    {
      "remoteJid": "120363001234567890@g.us",
      "remoteLid": "",
      "pushName": "Grupo de Vendas",
      "profilePicUrl": "https://pps.whatsapp.net/v/t61...",
      "instanceId": "Atendimento01"
    }
  ]
}

EVENT

messages.delete

Disparado quando uma mensagem é apagada para todos (revoke). Ocorre quando o remetente apaga uma mensagem que já foi entregue — o WhatsApp envia um protocolo de revogação que dispara este evento.

Campos do payload (data)

id string

ID da mensagem apagada.

remoteJid string

JID do chat.

fromMe boolean

Se a mensagem apagada era sua.

participant string

JID do participante (em grupos).

status "DELETED"

Sempre "DELETED".

instanceId string

ID da instância.

{
  "event": "messages.delete",
  "instance": "Atendimento01",
  "date_time": "2026-03-30T16:00:00Z",
  "data": {
    "id": "3EB04A2D1F75...",
    "remoteJid": "5511999999999@s.whatsapp.net",
    "fromMe": false,
    "participant": "",
    "status": "DELETED",
    "instanceId": "Atendimento01"
  }
}

EVENT

group-participants.update

Disparado quando a composição de participantes de um grupo é alterada — adição, remoção, promoção ou rebaixamento de membros. O campo action indica qual tipo de alteração ocorreu.

Campos do payload (data)

id string

JID do grupo (ex: 120363429994246808@g.us).

author string

LID de quem executou a ação (ex: 158437669392517@lid).

action "add" | "remove" | "promote" | "demote"

Tipo da alteração ocorrida.

participants array

Lista de participantes afetados. Cada item contém:

id string

LID do participante.

phoneNumber string

Número do WhatsApp.

admin boolean | null

true se promovido a admin, false se rebaixado, null em add/remove.

participantsData array

Mesmos dados de participants em formato aninhado (compatibilidade Evolution API).

instanceId string

ID da instância.

{
  "event": "group-participants.update",
  "instance": "Atendimento01",
  "date_time": "2026-03-30T16:00:00Z",
  "data": {
    "id": "120363429994246808@g.us",
    "author": "158437669392517@lid",
    "participants": [
      {
        "id": "35026011992289@lid",
        "phoneNumber": "558599999999@s.whatsapp.net",
        "admin": false
      }
    ],
    "action": "promote",
    "participantsData": [
      {
        "jid": {
          "id": "35026011992289@lid",
          "phoneNumber": "558599999999@s.whatsapp.net",
          "admin": false
        }
      }
    ]
  },
  "sender": "558590909090@s.whatsapp.net"
}

EVENT

call

Somente Evolution

Disparado durante o ciclo de vida de uma ligação. Adicione call à lista de eventos do webhook para recebê-lo. Os status possíveis são offer, preaccept, accept, transport, relaylatency, reject e terminate.

Este é um evento de sinalização segura: não inclui conteúdo ou binários de áudio/vídeo, SDP, endpoints de relay, mídia criptografada nem chaves da chamada. Não há tradução nem entrega deste evento no formato Z-API.

Campos do payload (data)

callId string

ID usado nos endpoints de controle e áudio.

from string?

JID que originou o evento.

callCreator / callCreatorAlt string?

Identificadores do criador da ligação, quando disponíveis.

groupJid string?

JID do grupo em sinalizações de grupo.

status string

Transição do ciclo de vida da ligação.

media "audio" | "video" | ""

Tipo anunciado na oferta, quando conhecido.

isVideo / isGroup boolean?

Características da ligação.

remotePlatform / remoteVersion string?

Metadados do cliente remoto, quando informados.

reason string?

Motivo informado ao encerrar a ligação.

rtcMediaAvailable boolean

Permanece false; a mídia RTC bruta não é exposta no webhook.

{
  "event": "call",
  "instance": "Atendimento01",
  "date_time": "2026-08-15T12:00:00Z",
  "data": {
    "callId": "ABCD1234",
    "from": "5511999999999@s.whatsapp.net",
    "callCreator": "5511999999999@s.whatsapp.net",
    "status": "offer",
    "media": "audio",
    "isVideo": false,
    "isGroup": false,
    "rtcMediaAvailable": false
  }
}

{
  "event": "call",
  "instance": "Atendimento01",
  "date_time": "2026-08-15T12:05:00Z",
  "data": {
    "callId": "ABCD1234",
    "from": "5511999999999@s.whatsapp.net",
    "status": "terminate",
    "reason": "timeout",
    "isGroup": false,
    "rtcMediaAvailable": false
  }
}

Grupos

Crie, gerencie e administre grupos do WhatsApp. Todos os endpoints abaixo aceitam o nome curto da instância (ex: Marketing01) ou o ID completo no path.

POST

Criar Grupo

/group/create/:instance

Cria um novo grupo do WhatsApp. Você se torna admin automaticamente. Participantes precisam estar no formato 5511999998888 (com DDI).

subjectstringObrigatório

Nome do grupo (1 a 25 caracteres).

descriptionstringOpcional

Descrição/tópico inicial do grupo.

participantsstring[]Opcional

Lista de números a adicionar (com DDI, sem caracteres especiais).

promoteParticipantsbooleanOpcional

Promover todos os participantes adicionados a admin.

curl -X POST https://api.whatsmiau.dev/v2/group/create/Marketing01 \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "subject": "Time de Vendas",
  "description": "Canal interno do time de vendas",
  "participants": ["5511999998888", "5511988887777"],
  "promoteParticipants": false
}'

const r = await fetch("https://api.whatsmiau.dev/v2/group/create/Marketing01", {
  method: "POST",
  headers: { "apikey": "SUA_CHAVE", "Content-Type": "application/json" },
  body: JSON.stringify({
    subject: "Time de Vendas",
    participants: ["5511999998888"]
  })
});
const group = await r.json();
console.log(group.id); // "120363xxxxxxx@g.us"

POST

Atualizar Nome do Grupo

/group/updateGroupSubject/:instance

Altera o nome (subject) de um grupo existente. Requer permissão de admin.

groupJidstringObrigatório

JID do grupo (ex: 120363xxxxxxx@g.us).

subjectstringObrigatório

Novo nome do grupo (1 a 25 caracteres).

curl -X POST https://api.whatsmiau.dev/v2/group/updateGroupSubject/Marketing01 \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "groupJid": "120363xxxxxxx@g.us",
  "subject": "Time de Vendas 2026"
}'

POST

Atualizar Foto do Grupo

/group/updateGroupPicture/:instance

Define a foto do grupo. Aceita URL pública de JPEG ou imagem em base64. Requer permissão de admin.

groupJidstringObrigatório

JID do grupo (ex: 120363xxxxxxx@g.us).

imagestringObrigatório

URL pública de uma imagem JPEG ou imagem em base64 (data URI ou puro base64).

curl -X POST https://api.whatsmiau.dev/v2/group/updateGroupPicture/Marketing01 \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "groupJid": "120363xxxxxxx@g.us",
  "image": "https://example.com/logo.jpg"
}'

POST

Atualizar Descrição do Grupo

/group/updateGroupDescription/:instance

Altera o tópico/descrição do grupo. Envie string vazia para remover a descrição.

groupJidstringObrigatório

JID do grupo.

descriptionstringOpcional

Nova descrição. Use "" para limpar.

curl -X POST https://api.whatsmiau.dev/v2/group/updateGroupDescription/Marketing01 \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "groupJid": "120363xxxxxxx@g.us",
  "description": "Canal oficial de comunicação"
}'

GET

Buscar Informações do Grupo

/group/findGroupInfos/:instance?groupJid={jid}

Retorna metadados completos: nome, descrição, owner, lista de admins, configurações e contagem de membros.

groupJidstring (query)Obrigatório

JID do grupo.

curl -X GET "https://api.whatsmiau.dev/v2/group/findGroupInfos/Marketing01?groupJid=120363xxxxxxx@g.us" \
  -H "apikey: SUA_CHAVE"

GET

Listar Todos os Grupos

/group/fetchAllGroups/:instance?getParticipants={bool}

Retorna todos os grupos em que a instância participa. Use getParticipants=true para incluir a lista completa de membros (mais lento).

getParticipantsstring (query)Opcional

"true" para incluir participantes de cada grupo na resposta.

curl -X GET "https://api.whatsmiau.dev/v2/group/fetchAllGroups/Marketing01?getParticipants=false" \
  -H "apikey: SUA_CHAVE"

GET

Listar Participantes do Grupo

/group/participants/:instance?groupJid={jid}

Retorna apenas a lista de participantes de um grupo específico, com flags de admin e superAdmin.

groupJidstring (query)Obrigatório

JID do grupo.

curl -X GET "https://api.whatsmiau.dev/v2/group/participants/Marketing01?groupJid=120363xxxxxxx@g.us" \
  -H "apikey: SUA_CHAVE"

GET

Obter Link de Convite

/group/inviteCode/:instance?groupJid={jid}

Gera (ou recupera) o código de convite do grupo. O link completo é https://chat.whatsapp.com/{inviteCode}.

groupJidstring (query)Obrigatório

JID do grupo.

curl -X GET "https://api.whatsmiau.dev/v2/group/inviteCode/Marketing01?groupJid=120363xxxxxxx@g.us" \
  -H "apikey: SUA_CHAVE"

GET

Informações de um Convite

/group/inviteInfo/:instance?inviteCode={code}

Inspeciona um código de convite sem entrar no grupo. Útil para mostrar prévia (nome, descrição, número de membros) antes da entrada.

inviteCodestring (query)Obrigatório

Código de convite (a parte após /chat.whatsapp.com/).

curl -X GET "https://api.whatsmiau.dev/v2/group/inviteInfo/Marketing01?inviteCode=D3uG6n9xT2pQ" \
  -H "apikey: SUA_CHAVE"

GET

Aceitar Convite

/group/acceptInviteCode/:instance?inviteCode={code}

Faz a instância entrar em um grupo usando um código de convite.

inviteCodestring (query)Obrigatório

Código de convite do grupo.

curl -X GET "https://api.whatsmiau.dev/v2/group/acceptInviteCode/Marketing01?inviteCode=D3uG6n9xT2pQ" \
  -H "apikey: SUA_CHAVE"

POST

Enviar Convite via DM

/group/sendInvite/:instance

Envia o link de convite do grupo para uma lista de números em mensagens privadas. Substitui o fluxo manual de 'adicionar e tirar' para grupos com aprovação.

groupJidstringObrigatório

JID do grupo.

descriptionstringOpcional

Texto opcional enviado junto com o link.

numbersstring[]Obrigatório

Lista de números (com DDI) que receberão o convite.

curl -X POST https://api.whatsmiau.dev/v2/group/sendInvite/Marketing01 \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "groupJid": "120363xxxxxxx@g.us",
  "description": "Você foi convidado!",
  "numbers": ["5511999998888"]
}'

POST

Revogar Link de Convite

/group/revokeInviteCode/:instance

Invalida o código de convite atual e gera um novo. Use quando o link vazar publicamente. Requer permissão de admin.

groupJidstringObrigatório

JID do grupo.

curl -X POST https://api.whatsmiau.dev/v2/group/revokeInviteCode/Marketing01 \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "groupJid": "120363xxxxxxx@g.us"
}'

POST

Gerenciar Participantes

/group/updateParticipant/:instance

Adiciona, remove, promove ou rebaixa membros do grupo. Operações destrutivas (remove/demote) exigem que o JID esteja correto — IDs inválidos retornam erro 400.

groupJidstringObrigatório

JID do grupo.

actionstringObrigatório

Uma de: "add" (adicionar), "remove" (remover), "promote" (tornar admin), "demote" (rebaixar admin).

participantsstring[]Obrigatório

Lista de JIDs ou números (com DDI) afetados pela operação.

curl -X POST https://api.whatsmiau.dev/v2/group/updateParticipant/Marketing01 \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "groupJid": "120363xxxxxxx@g.us",
  "action": "add",
  "participants": ["5511999998888"]
}'

// Promover dois membros a admin
await fetch("https://api.whatsmiau.dev/v2/group/updateParticipant/Marketing01", {
  method: "POST",
  headers: { "apikey": "SUA_CHAVE", "Content-Type": "application/json" },
  body: JSON.stringify({
    groupJid: "120363xxxxxxx@g.us",
    action: "promote",
    participants: ["5511999998888@s.whatsapp.net"]
  })
});

POST

Configurações do Grupo

/group/updateSetting/:instance

Altera quem pode enviar mensagens e quem pode editar metadados (nome/descrição/foto). Use "announcement" para que apenas admins escrevam e "locked" para travar edição de metadados.

groupJidstringObrigatório

JID do grupo.

actionstringObrigatório

"announcement" (só admin envia), "not_announcement" (todos enviam), "locked" (só admin edita info), "unlocked" (todos editam).

curl -X POST https://api.whatsmiau.dev/v2/group/updateSetting/Marketing01 \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "groupJid": "120363xxxxxxx@g.us",
  "action": "announcement"
}'

POST

Mensagens Efêmeras

/group/toggleEphemeral/:instance

Define o tempo após o qual mensagens do grupo são apagadas automaticamente. Valores válidos: 0 (desativado), 86400 (24h), 604800 (7 dias), 7776000 (90 dias).

groupJidstringObrigatório

JID do grupo.

expirationnumberOpcional

Duração em segundos. Apenas um destes valores é aceito: 0 (desativado), 86400 (24h), 604800 (7 dias), 7776000 (90 dias). Omitir equivale a 0.

curl -X POST https://api.whatsmiau.dev/v2/group/toggleEphemeral/Marketing01 \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "groupJid": "120363xxxxxxx@g.us",
  "expiration": 604800
}'

DELETE

Sair do Grupo

/group/leaveGroup/:instance?groupJid={jid}

Remove a instância do grupo. Operação irreversível — para voltar, será necessário um novo convite.

groupJidstring (query)Obrigatório

JID do grupo do qual sair.

curl -X DELETE "https://api.whatsmiau.dev/v2/group/leaveGroup/Marketing01?groupJid=120363xxxxxxx@g.us" \
  -H "apikey: SUA_CHAVE"

Comunidades

Comunidades agrupam vários grupos sob um mesmo guarda-chuva. Cada comunidade tem um grupo de anúncios (criado automaticamente) e sub-grupos vinculados. Para gerenciar membros de um sub-grupo, use os endpoints de Grupos.

POST

Criar Comunidade

/community/create/:instance

Cria uma nova comunidade. Um grupo de anúncios é criado automaticamente como sub-grupo padrão.

subjectstringObrigatório

Nome da comunidade (1 a 25 caracteres).

descriptionstringOpcional

Descrição da comunidade.

curl -X POST https://api.whatsmiau.dev/v2/community/create/Marketing01 \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "subject": "Verzap",
  "description": "Comunidade oficial Verzap"
}'

POST

Criar Sub-grupo na Comunidade

/community/createSubGroup/:instance

Cria um novo grupo já vinculado a uma comunidade existente. É equivalente a criar um grupo + linkGroup em uma única chamada.

subjectstringObrigatório

Nome do sub-grupo (1 a 25 caracteres).

parentJidstringObrigatório

JID da comunidade pai.

participantsstring[]Opcional

Números a adicionar ao novo sub-grupo.

curl -X POST https://api.whatsmiau.dev/v2/community/createSubGroup/Marketing01 \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "subject": "Suporte",
  "parentJid": "120363xxxxxxx@g.us",
  "participants": ["5511999998888"]
}'

POST

Vincular Grupo Existente

/community/linkGroup/:instance

Anexa um grupo já existente a uma comunidade como sub-grupo. Você precisa ser admin de ambos.

parentJidstringObrigatório

JID da comunidade.

childJidstringObrigatório

JID do grupo a vincular.

curl -X POST https://api.whatsmiau.dev/v2/community/linkGroup/Marketing01 \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "parentJid": "120363aaaaaaa@g.us",
  "childJid": "120363bbbbbbb@g.us"
}'

POST

Desvincular Grupo

/community/unlinkGroup/:instance

Remove um sub-grupo da comunidade. O grupo continua existindo, mas deixa de fazer parte da comunidade.

parentJidstringObrigatório

JID da comunidade.

childJidstringObrigatório

JID do sub-grupo a desvincular.

curl -X POST https://api.whatsmiau.dev/v2/community/unlinkGroup/Marketing01 \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "parentJid": "120363aaaaaaa@g.us",
  "childJid": "120363bbbbbbb@g.us"
}'

GET

Listar Sub-grupos

/community/subGroups/:instance?communityJid={jid}

Retorna todos os sub-grupos vinculados a uma comunidade.

communityJidstring (query)Obrigatório

JID da comunidade pai.

curl -X GET "https://api.whatsmiau.dev/v2/community/subGroups/Marketing01?communityJid=120363xxxxxxx@g.us" \
  -H "apikey: SUA_CHAVE"

GET

Membros dos Grupos Vinculados

/community/linkedGroupsParticipants/:instance?communityJid={jid}

Retorna a união (deduplicada) de todos os membros dos sub-grupos da comunidade. Útil para campanhas de comunicação.

communityJidstring (query)Obrigatório

JID da comunidade.

curl -X GET "https://api.whatsmiau.dev/v2/community/linkedGroupsParticipants/Marketing01?communityJid=120363xxxxxxx@g.us" \
  -H "apikey: SUA_CHAVE"

POST

Aprovação de Entrada

/community/setJoinApprovalMode/:instance

Quando ativado, novos membros que entram por link de convite precisam ser aprovados por um admin antes de aparecerem nos sub-grupos.

communityJidstringObrigatório

JID da comunidade.

modebooleanOpcional

true para exigir aprovação de novos membros; false (padrão) para entrada livre via link de convite.

curl -X POST https://api.whatsmiau.dev/v2/community/setJoinApprovalMode/Marketing01 \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "communityJid": "120363xxxxxxx@g.us",
  "mode": true
}'

POST

Adição de Grupos à Comunidade

/community/setGroupAddMode/:instance

Define quem pode adicionar ou vincular grupos à comunidade: somente administradores ("admin_add") ou qualquer membro da comunidade ("all_member_add"). Essa configuração não altera quem pode adicionar pessoas aos grupos.

communityJidstringObrigatório

JID pai da comunidade. JIDs de grupos comuns ou subgrupos são rejeitados.

modestringObrigatório

"admin_add" restringe a ação aos administradores; "all_member_add" permite a qualquer membro da comunidade.

curl -X POST https://api.whatsmiau.dev/v2/community/setGroupAddMode/Marketing01 \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "communityJid": "120363xxxxxxx@g.us",
  "mode": "admin_add"
}'

GET

Solicitações Pendentes

/community/requestParticipants/:instance?communityJid={jid}

Lista os usuários que solicitaram entrar na comunidade e ainda aguardam aprovação (apenas se setJoinApprovalMode estiver ativo).

communityJidstring (query)Obrigatório

JID da comunidade.

curl -X GET "https://api.whatsmiau.dev/v2/community/requestParticipants/Marketing01?communityJid=120363xxxxxxx@g.us" \
  -H "apikey: SUA_CHAVE"

POST

Aprovar ou Rejeitar Solicitações

/community/requestParticipants/update/:instance

Processa solicitações pendentes em lote. Use action='approve' para deixar entrar ou 'reject' para negar.

communityJidstringObrigatório

JID da comunidade.

actionstringObrigatório

"approve" ou "reject".

participantsstring[]Opcional

Lista de JIDs a aprovar/rejeitar. Use a resposta de requestParticipants para obter os JIDs pendentes.

curl -X POST https://api.whatsmiau.dev/v2/community/requestParticipants/update/Marketing01 \
  -H "apikey: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
  "communityJid": "120363xxxxxxx@g.us",
  "action": "approve",
  "participants": ["5511999998888@s.whatsapp.net"]
}'

MCP — Model Context Protocol

novo

Conecte agentes de IA — como Hermes, Claude Desktop, Cursor, Continue ou Cline — diretamente ao seu WhatsApp. Em vez de codar wrappers em volta da API REST, o agente descobre automaticamente as ferramentas disponíveis e as executa por você.

Pool não é obrigatório para usar uma instância. Criar, conectar, enviar mensagens, configurar webhook e descobrir comunidades ao vivo funcionam sem pool. O upgrade pago por slot é exigido somente para reter e consultar dados salvos.

O que é uma instância?

É uma conexão/sessão independente do WhatsApp, normalmente vinculada a um número de telefone. Cada instância possui um id próprio. Use esse valor como instance ou instance_id nas outras tools.

O que é um pool?

É um pacote pago de retenção de dados. O pool contém slots; cada slot pode ser associado a uma instância para ativar a captura de conversas, mensagens, contatos, grupos e comunidades durante o período contratado. O pool_id identifica esse pacote, não a instância.

O que é um slot?

É uma unidade de capacidade dentro de um pool de histórico. Um slot atende uma instância por vez; associá-lo ativa history_enabled. Sem slot livre, só não é possível ativar histórico em outra instância. Criar, conectar, gerenciar e enviar mensagens pelo MCP continuam funcionando normalmente. O limite comum de instâncias do plano é separado.

Regra prática para agentes: chame list_instances e use o campo id. Se history_enabled for false, não tente ler dados salvos; list_communities e list_community_subgroups são exceções ao vivo e funcionam com a instância conectada. Ao criar uma instância, omita pool_id por padrão; só envie esse parâmetro quando o usuário já tiver fornecido um pool válido e quiser ativar histórico imediatamente.

Padrão aberto da Anthropic. O Model Context Protocol é o padrão da indústria para LLMs acessarem ferramentas externas. Suportado nativamente por Claude Desktop, Cursor, Continue, Cline e qualquer cliente compatível.

Endpoint:https://mcp.whatsmiau.dev

Quando há pool, a captura começa na associação e não recupera mensagens anteriores. Ela usa um webhook interno automático, sem depender do webhook da sua aplicação. Mensagens de áudio podem incluir media_url com o link já fornecido pelo storage. O MCP não copia os arquivos nem transcreve os áudios; a disponibilidade do link segue o storage de origem e pode ser menor que a retenção do histórico. Mensagens antigas sem URL não são recuperadas automaticamente. Ao cancelar, a captura e o acesso param; os dados ficam preservados e as mensagens continuam seguindo a expiração original.

Casos de uso

Atendimento automatizado: peça ao agente para responder leads no WhatsApp.
Notificações inteligentes: envie alertas formatados e contextuais a partir de prompts.
Operações sem código: criar, conectar e gerenciar instâncias falando em linguagem natural.

Como conectar

Use OAuth para entrar pelo navegador ou reutilize qualquer chave criada em Chaves de API. A mesma chave continua funcionando na API REST; os métodos são alternativos e você só precisa configurar um deles.

Qual cliente você vai usar?

OAuth — recomendado

O Hermes abre o navegador para você entrar na sua conta. Não é necessário criar nem colar uma chave.

hermes mcp add whatsmiau --url https://mcp.whatsmiau.dev --auth oauth
hermes mcp login whatsmiau
hermes mcp test whatsmiau

Sua chave de API

Reutilize a mesma chave da API REST. O comando pede a chave em seguida, sem gravá-la no histórico do terminal.

hermes mcp add whatsmiau --url https://mcp.whatsmiau.dev --auth header

Cursor, Continue ou Cline

{
  "mcpServers": {
    "whatsmiau": {
      "url": "https://mcp.whatsmiau.dev"
    }
  }
}

{
  "mcpServers": {
    "whatsmiau": {
      "url": "https://mcp.whatsmiau.dev",
      "headers": {
        "Authorization": "Bearer SUA_CHAVE_API"
      }
    }
  }
}

Validar a conexão

1.Reinicie ou recarregue seu cliente MCP.
2.Confirme que o servidor whatsmiau aparece conectado.
3.Envie: “liste minhas instâncias do WhatsApp”.

OAuth e API key são alternativas. Com um pacote MCP ativo, sua chave comum funciona tanto na API REST quanto neste endpoint.

Tools disponíveis

60 ferramentas expostas pelo servidor MCP, cobrindo instâncias, mensagens, chat, webhooks, grupos, comunidades, consultas opcionais ao histórico salvo e acesso à documentação ao vivo. O cliente MCP descobre os schemas (parâmetros, tipos) automaticamente via tools/list. Quando existe um endpoint REST correspondente, clique no card abaixo para ver os parâmetros completos e um exemplo cURL do endpoint correspondente.

Documentação

(1 tool)

get_docs

Pesquisa as docs publicadas e retorna seções completas com parâmetros, exemplos e links de origem.

Dados salvos

(6 tools)

Todas estas tools consultam o dataset retido e exigem uma instância associada a pool, indicada por history_enabled: true em list_instances. Sem pool, apenas essas leituras salvas e as consultas sensíveis explicitamente marcadas são recusadas; operações e descoberta de comunidades ao vivo continuam disponíveis.

list_conversations

Pagina conversas retidas com JID, prévia, horário e não lidas; exige history_enabled=true.

get_conversation_messages

Pagina as mensagens retidas de um chat_jid retornado por list_conversations. Áudios incluem media_url quando o link foi capturado; a ausência do campo indica que não há URL disponível no histórico.

search_messages

Pesquisa texto no histórico retido e devolve chat, remetente, horário, IDs e media_url quando disponível. Não pesquisa o conteúdo falado dos áudios.

list_contacts

Pagina o snapshot de contatos com JIDs, telefones e nomes/metadados conhecidos.

list_groups

Lista grupos comuns e subgrupos capturados, com políticas, comunidade pai e participantes conhecidos.

get_group_details

Busca um grupo ou comunidade pelo JID e mostra metadados, vínculo e participantes conhecidos.

Instâncias

(7 tools)

Mensagens

(12 tools)

Chat & Webhook

(7 tools)

Grupos

(17 tools)

Comunidades

(11 tools)

list_communities

Lista ao vivo todas as comunidades pai da instância conectada, sem exigir histórico, e devolve os JIDs usados pelas demais tools.