Referência da API

Integre o WhatsApp à sua aplicação em minutos. Nossa API segue os padrões RESTful, autenticação via Bearer Token ou API Key, e respostas em JSON.

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

Autenticação

Todas as requisições autenticadas usam API Key via header apikey. Gere suas chaves no Dashboard.

GET

Verificar Credenciais

/evolution/instances

Teste se sua chave de API é válida fazendo uma requisição simples de listagem.

curl -X GET https://api.whatsmiau.dev/evolution/instances \
  -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

/evolution/instance/create

Cria uma nova instância. Se 'qrcode' for true, ela já estará pronta para leitura.

Parâmetros

instanceNamestringObrigatório

Nome único para identificar a instância.

qrcodebooleanOpcional

Se verdadeiro, retorna o QR Code imediatamente (se suportado).

tokenstringOpcional

Token personalizado para a instância (opcional).

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

Conectar Instância

/evolution/instance/connect/:id

Recupera o QR Code (base64) para conectar uma instância criada.

Parâmetros

idstringObrigatório

ObjectID da instância (retornado em GET /evolution/instances).

curl -X GET https://api.whatsmiau.dev/evolution/instance/connect/64f1a2b3c4d5e6f7a8b9c0d1 \
  -H "apikey: SUA_CHAVE"
DELETE

Deletar Instância

/evolution/instance/:id

Remove permanentemente uma instância e limpa a sessão.

Parâmetros

idstringObrigatório

ObjectID da instância (retornado em GET /evolution/instances).

curl -X DELETE https://api.whatsmiau.dev/evolution/instance/64f1a2b3c4d5e6f7a8b9c0d1 \
  -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.

Parâmetros

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: 300000).

linkPreviewbooleanOpcional

Exibir preview de links.

mentionsEveryOnebooleanOpcional

Mencionar todos em grupos.

mentionedstring[]Opcional

Lista de JIDs a mencionar.

quotedobjectOpcional

Mensagem a ser respondida (key.id obrigatório).

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

Enviar Mídia

/message/sendMedia/:instance

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

Parâmetros

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: 300000).

quotedobjectOpcional

Mensagem a ser respondida (key.id obrigatório).

mentionsEveryOnebooleanOpcional

Mencionar todos em grupos.

mentionedstring[]Opcional

Lista de JIDs a mencionar.

curl -X POST https://api.whatsmiau.dev/message/sendMedia/Marketing01 \
  -H "apikey: KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "number": "551199998888",
  "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).

Parâmetros

numberstringObrigatório

Número do destinatário.

audiostringObrigatório

URL pública do arquivo MP3/OGG.

delaynumberOpcional

Atraso em milissegundos (máx: 300000).

encodingbooleanOpcional

Re-encodar o áudio antes de enviar.

quotedobjectOpcional

Mensagem a ser respondida (key.id obrigatório).

mentionsEveryOnebooleanOpcional

Mencionar todos em grupos.

mentionedstring[]Opcional

Lista de JIDs a mencionar.

curl -X POST https://api.whatsmiau.dev/message/sendWhatsAppAudio/Marketing01 \
  -H "apikey: KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "number": "551199998888",
  "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.

Parâmetros

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/message/sendList/Marketing01 \
  -H "apikey: KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "number": "551199998888",
  "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" }
      ]
    }
  ]
}'
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.

Parâmetros

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/message/sendButtons/Marketing01 \
  -H "apikey: KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "number": "551199998888",
  "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" }
  ]
}'

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.

Parâmetros

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/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.

Parâmetros

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: 300000).

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

Marcar como Lido

/chat/markMessageAsRead/:instance

Marca mensagens específicas como lidas.

Parâmetros

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/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.

Parâmetros

numbersstring[]Obrigatório

Lista de números para verificar.

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

Deletar Mensagem

/chat/deleteMessageForEveryone/:instance

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

Parâmetros

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/chat/deleteMessageForEveryone/Marketing01 \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "3EB0XXXXXXXX",
  "remoteJid": "5511999998888@s.whatsapp.net",
  "fromMe": true
}'

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, headers customizados e formato do payload.

Parâmetros

webhook.enabledbooleanOpcional

Ativa ou desativa o webhook.

webhook.urlstringOpcional

URL que receberá os eventos via POST.

webhook.eventsstring[]Opcional

Lista de eventos para filtrar (ex: messages.upsert, connection.update).

webhook.headersobjectOpcional

Headers HTTP customizados enviados junto com cada evento.

webhook.byEventsbooleanOpcional

Se true, envia um POST por evento. Se false, agrupa.

webhook.base64booleanOpcional

Se true, codifica o payload em base64.

curl -X POST https://api.whatsmiau.dev/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"],
      "headers": {
        "Authorization": "Bearer meu_token"
      }
    }
  }'
GET

Consultar Webhook

/webhook/find/:instance

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

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

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.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

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

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

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"
  }
}