MiraFunnel API v1

API pública para automação de WhatsApp, CRM e campanhas de prospecção.

URL Basehttps://api.mirafunnel.com.br/api/v1

ProtocoloHTTPS (TLS 1.2+)

FormatoJSON

Autenticação

Todas as requisições devem incluir o header X-API-Key com sua chave de API.

Headers

X-API-Key: mira_sk_your_api_key_here
Content-Type: application/json

Gere suas chaves em Dashboard → Configurações → API Keys ou via endpoint POST /api/v1/api-keys.

⚠️ Nunca exponha sua API key no frontend. Use apenas em chamadas server-side.

Paginação

Endpoints que retornam listas suportam paginação via query params:

Query Params

?page=1&limit=25&sort=createdAt&order=desc

A resposta inclui o objeto pagination:

Response

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 142,
    "pages": 6
  }
}

Rate Limits

100 requisições por minuto por API key. Headers de resposta:

Header	Descrição
`X-RateLimit-Limit`	Limite total
`X-RateLimit-Remaining`	Requisições restantes
`X-RateLimit-Reset`	Timestamp de reset
`X-Request-Id`	ID único da requisição

Messages

POST/messages/send

Enviar mensagem (text, image, video, audio, document).

Request Body

{
  "instanceId": "uuid-da-instancia",
  "to": "5511999999999",
  "type": "text",
  "content": {
    "text": "Olá! Como posso ajudar?"
  }
}

cURL

curl -X POST https://api.mirafunnel.com.br/api/v1/messages/send \
  -H "X-API-Key: mira_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"instanceId":"uuid","to":"5511999999999","type":"text","content":{"text":"Olá!"}}'

Tipos suportados:

type	content
`text`	`{ "text": "mensagem" }`
`image`	`{ "media": "url", "caption": "legenda" }`
`video`	`{ "media": "url", "caption": "legenda" }`
`audio`	`{ "media": "url" }`
`document`	`{ "media": "url", "fileName": "doc.pdf" }`

POST/messages/send-buttons

Enviar mensagem com botões interativos (máx. 3).

Body

{ "instanceId": "uuid", "to": "55...", "title": "Escolha", "buttons": [{"buttonText": "Opção 1"}, {"buttonText": "Opção 2"}] }

POST/messages/send-list

Enviar lista de opções (menu dropdown).

POST/messages/send-poll

Criar enquete/votação.

POST/messages/send-reaction

Enviar reação emoji a uma mensagem.

Body

{ "instanceId": "uuid", "to": "55...", "messageId": "msg-id", "emoji": "👍" }

POST/messages/send-location

Enviar localização.

Body

{ "instanceId": "uuid", "to": "55...", "latitude": -23.55, "longitude": -46.63, "name": "São Paulo" }

POST/messages/mark-read

Marcar mensagens como lidas.

POST/messages/check-number

Verificar se números possuem WhatsApp.

Body

{ "instanceId": "uuid", "numbers": ["5511999999999", "5521888888888"] }

POST/messages/typing

Enviar indicador de digitação.

Instances

GET/instances

Listar todas as instâncias WhatsApp.

POST/instances

Criar nova instância. Body: { "name": "Minha Instância" }

GET/instances/:id/status

Status de conexão da instância.

GET/instances/:id/qrcode

Obter QR Code para conexão.

POST/instances/:id/connect

Conectar/reconectar instância.

POST/instances/:id/disconnect

Desconectar (logout).

PUT/instances/:id

Renomear instância. Body: { "name": "Novo Nome" }

DELETE/instances/:id

Eliminar instância permanentemente.

Contacts

GET/contacts?page=1&limit=25

Listar contatos (paginado).

GET/contacts/search?q=João

Busca full-text por nome, telefone ou email.

GET/contacts/:id

Detalhes do contato + conversas recentes.

POST/contacts

Criar ou atualizar contato (upsert por telefone).

Body

{ "phone": "5511999999999", "name": "João Silva", "email": "joao@email.com", "tags": ["lead", "vip"] }

PUT/contacts/:id

Atualizar contato.

DELETE/contacts/:id

Eliminar contato.

Conversations

GET/conversations?status=open&instanceId=uuid

Listar conversas (filtros: status, instanceId).

GET/conversations/:id

Detalhes da conversa.

GET/conversations/:id/messages?page=1&limit=50

Histórico de mensagens.

PUT/conversations/:id/assign?agentId=uuid

Atribuir conversa a um agente.

PUT/conversations/:id/resolve

Resolver/encerrar conversa.

Campaigns

GET/campaigns

Listar campanhas.

GET/campaigns/:id

Detalhes + métricas.

POST/campaigns

Criar campanha de disparo.

Body

{
  "name": "Campanha Black Friday",
  "messageTemplate": "Olá {{name}}! Aproveite nossa promoção.",
  "instanceId": "uuid",
  "messageType": "text",
  "scheduledFor": "2026-11-29T10:00:00Z",
  "recurrence": "daily",
  "dailyLimit": 100
}

POST/campaigns/:id/recipients

Adicionar destinatários (batch até 1000).

Body

{ "recipients": [{ "phone": "5511999999999", "name": "João" }, { "phone": "5521888888888", "name": "Maria" }] }

PUT/campaigns/:id/start

Iniciar campanha.

PUT/campaigns/:id/pause

Pausar campanha.

Funnels

GET/funnels

Listar funis ativos.

GET/funnels/:id/stats

Estatísticas por estágio do funil.

POST/funnels/:id/add-lead

Injetar lead no funil (entra no primeiro estágio).

Body

{ "phone": "5511999999999", "name": "João Silva", "email": "joao@email.com" }

Groups

GET/groups

Listar grupos WhatsApp.

GET/groups/:id

Detalhes do grupo.

POST/groups/:id/messages

Enviar mensagem ao grupo.

POST/groups/:id/participants

Adicionar participantes.

DELETE/groups/:id/participants

Remover participantes.

Labels

GET/labels

Listar etiquetas sincronizadas.

POST/labels/sync

Sincronizar etiquetas do WhatsApp Business.

POST/labels/:id/triggers

Criar trigger: quando etiqueta for aplicada, adicionar contato a campanha.

Analytics

GET/analytics/overview

Métricas gerais da empresa.

Response

{ "contacts": 1542, "conversations": 389, "instances": 3, "campaigns": 12, "messages": 8721 }

GET/analytics/messages?days=7

Volume de mensagens enviadas/recebidas.

GET/analytics/campaigns

Performance de campanhas com delivery stats.

Webhooks

Receba notificações em tempo real quando eventos ocorrem na sua conta.

Gerenciamento

GET/webhooks

Listar webhooks configurados.

GET/webhooks/events

Listar eventos disponíveis.

POST/webhooks

Criar webhook.

Body

{ "url": "https://seusite.com/webhook", "events": ["message.received", "campaign.completed"] }

PUT/webhooks/:id

Atualizar webhook.

DELETE/webhooks/:id

Eliminar webhook.

Segurança — Verificação de Assinatura

Cada delivery inclui uma assinatura HMAC-SHA256 no header X-Mira-Signature:

Node.js — Verificação

const crypto = require('crypto');

function verifySignature(body, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(body))
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Eventos Disponíveis — 15 Eventos

Evento	Descrição
`message.received`	Nova mensagem recebida
`message.sent`	Mensagem enviada via API
`message.delivered`	Mensagem entregue
`message.read`	Mensagem lida
`message.failed`	Falha no envio
`contact.created`	Novo contato criado
`contact.updated`	Contato atualizado
`conversation.assigned`	Conversa atribuída a agente
`conversation.resolved`	Conversa resolvida
`conversation.reopened`	Conversa reaberta
`instance.connected`	Instância conectada
`instance.disconnected`	Instância desconectada
`campaign.started`	Campanha iniciada
`campaign.completed`	Campanha concluída
`label.associated`	Etiqueta aplicada a contato

Payload de Exemplo

Webhook Payload

{
  "event": "message.received",
  "timestamp": "2026-04-29T23:55:00.000Z",
  "data": {
    "messageId": "msg-uuid",
    "conversationId": "conv-uuid",
    "from": "5511999999999",
    "type": "text",
    "content": "Olá, quero saber mais!",
    "instanceId": "inst-uuid"
  }
}

Headers do delivery:

Header	Descrição
`X-Mira-Event`	Nome do evento
`X-Mira-Signature`	HMAC-SHA256 do body
`X-Mira-Delivery`	UUID único do delivery
`User-Agent`	MiraFunnel-Webhook/1.0

⚠️ Webhooks são desativados automaticamente após 10 falhas consecutivas. Responda com status 2xx.

API Keys

GET/api-keys

Listar chaves (mascaradas).

POST/api-keys

Gerar nova chave. Body: { "name": "Produção", "scopes": ["messages", "contacts"] }

DELETE/api-keys/:id

Revogar chave.

⚠️ A chave completa é exibida apenas uma vez na criação. Guarde-a em local seguro.

Códigos de Erro

Código	Significado
`400`	Bad Request — Parâmetros inválidos ou ausentes
`401`	Unauthorized — API key ausente, inválida ou expirada
`403`	Forbidden — Sem permissão para este recurso
`404`	Not Found — Recurso não encontrado
`409`	Conflict — Recurso já existe
`429`	Too Many Requests — Rate limit excedido
`500`	Internal Server Error — Erro interno

Formato de Erro

{
  "statusCode": 400,
  "message": "instanceId e to são obrigatórios",
  "error": "Bad Request"
}