Komunika API Reference

API RESTful para enviar mensagens WhatsApp, capturar leads e automatizar funis. Arquitectura orientada a eventos, escalável e com latências mínimas.

Autenticação

Gere uma API Key no painel (/dashboard/api-keys). Formato: kmnk_xxxxxxxxxxxxxxxxxxxx

Inclua no cabeçalho de cada requisição:

# Opção 1: X-API-Key (Recomendado)
X-API-Key: kmnk_abc123def456ghi789

# Opção 2: Bearer Token
Authorization: Bearer kmnk_abc123def456ghi789

Padrões de Resposta e Erros

Erro (JSON)

{
  "error": "Bad Request",
  "message": "Content is required for text messages",
  "statusCode": 400
}

Enviar Mensagem

Texto simples

{
  "instanceId": "id-da-instancia",
  "to": "258840000000",
  "type": "text",
  "content": "Olá! A sua encomenda #1234 já saiu para entrega."
}

Documento (fatura PDF)

{
  "instanceId": "id-da-instancia",
  "to": "258840000000",
  "type": "document",
  "content": "Aqui está a sua fatura mensal.",
  "mediaUrl": "https://seu-sistema.com/faturas/1234.pdf"
}

Resposta (201)

{ "success": true, "messageId": "BAE5ABCDEF12345" }

Status da Instância

Resposta (200)

{
  "success": true,
  "data": {
    "instanceId": "id-da-instancia",
    "name": "Suporte Principal",
    "status": "connected",
    "phone": "258840000000"
  }
}

Captura de Contactos

Corpo (JSON)

{
  "phone": "258840000000",
  "name": "Maria Costa",
  "email": "maria@exemplo.com",
  "tags": ["Checkout", "Vip"],
  "customFields": { "utm_source": "FacebookAds", "produto_id": "99" }
}

Resposta (201)

{
  "success": true,
  "message": "Contact captured successfully",
  "data": {
    "id": "cuid_987",
    "phone": "258840000000",
    "name": "Maria Costa",
    "tags": ["Visitante da Landing Page", "Checkout", "Vip"]
  }
}

Listar Funis Ativos

Resposta (200)

{
  "success": true,
  "data": [
    { "id": "cuid_funil_001", "name": "Funil de Boas-Vindas", "isActive": true },
    { "id": "cuid_funil_002", "name": "Recuperação de Carrinho", "isActive": true }
  ]
}

Iniciar Funil Manualmente

Corpo

{
  "phone": "258840000000",
  "name": "Carlos",
  "customFields": { "ordem_codigo": "ORD-555" }
}

Resposta (201)

{
  "success": true,
  "message": "Lead added to funnel successfully",
  "data": { "contact": { "id": "cuid_123", "phone": "258840000000" } }
}

Webhooks (Eventos Outbound)

Configure endpoints no painel (/dashboard/webhooks) para receber eventos em tempo real sem polling.

Segurança (HMAC-SHA256)

Se configurar um Webhook Secret, o Komunika assina payloads com HMAC-SHA256 no header X-Komunika-Signature.

Verificação (Node.js)

const crypto = require('crypto');

app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const secret = 'SEU_WEBHOOK_SECRET';
  const expected = crypto.createHmac('sha256', secret).update(req.body).digest('hex');
  
  if (req.headers['x-komunika-signature'] !== expected) {
    return res.status(401).send('Assinatura Inválida');
  }
  
  const payload = JSON.parse(req.body.toString());
  console.log('Evento:', payload.event);
  res.status(200).send('OK');
});

Estrutura Base

{
  "event": "nome.do.evento",
  "timestamp": "2026-04-24T02:00:31.309Z",
  "companyId": "cuid_da_sua_empresa",
  "data": { ... }
}

📌 message.received

Disparado quando uma nova mensagem chega via WhatsApp.

{
  "event": "message.received",
  "timestamp": "2026-04-24T12:00:00.000Z",
  "data": {
    "whatsappMessageId": "BAE5C123...",
    "conversationId": "cuid_conversacao_123",
    "senderType": "contact",
    "senderName": "João Silva",
    "type": "text",
    "content": "Olá, queria saber mais sobre as vossas integrações.",
    "mediaUrl": null,
    "status": "delivered"
  }
}

📌 contact.created

Disparado quando um novo contacto é inserido na base de dados.

{
  "event": "contact.created",
  "data": {
    "id": "cuid_456",
    "phone": "258840000000",
    "name": "Maria",
    "tags": ["Visitante da Landing Page"],
    "customFields": {}
  }
}

📌 conversation.status_changed

Disparado quando um agente fecha ou abre um ticket de atendimento.

{
  "event": "conversation.status_changed",
  "data": {
    "conversationId": "cuid_conversacao_123",
    "contactId": "cuid_456",
    "oldStatus": "pending",
    "newStatus": "resolved",
    "agentId": "cuid_agente_789"
  }
}

Rate Limits

Se exceder, a API retorna 429 Too Many Requests. Recomendamos backoff exponencial.