LunaDocs

Carregando a busca...

EnglishEntrar no console
Nesta página

SDK e n8n

Usar com IA

A API da Luna é HTTP comum com uma especificação OpenAPI, e você pode chamá-la de qualquer linguagem e de qualquer ferramenta. No n8n, o caminho que funciona hoje usa só os nós padrão: um Webhook para receber, um Code para conferir a assinatura e um HTTP Request para enviar. O SDK Node/TypeScript e o nó próprio do n8n estão em preparação.

A referência da API é o contrato. As ferramentas não têm regra de negócio: a janela de 24 horas, a capacidade do plano e o template aprovado são conferidos pela API, que responde com o motivo.

n8n hoje: os nós padrão#

Um fluxo de quatro peças, todas de fábrica no n8n: o Webhook recebe o evento da Luna (com o corpo bruto), o Code confere a assinatura, o Respond to Webhook devolve 200 ou 401, e o HTTP Request envia a resposta pela API. Você precisa de uma chave de API com messages:write e do número de origem (metaPhoneNumberId, de GET /v1/numbers).

1. O nó Webhook#

  • HTTP Method: POST. Path: luna (ou o que preferir).
  • Respond: “Using ‘Respond to Webhook’ Node”. É o que permite responder 401 a uma assinatura que não confere.
  • Em Options, ligue Raw Body. Este é o passo que costuma faltar: a assinatura é calculada sobre os bytes exatos do corpo, e sem essa opção o n8n entrega o JSON já aberto e a conta não bate. Com ela, o corpo chega como dado binário na propriedade data.
  • Ative o fluxo e copie a Production URL. Cadastre-a como endpoint da Luna (POST /v1/webhooks/endpoints, como em Primeiros passos) e guarde o secret da resposta: ele aparece uma única vez. A URL de teste do n8n não serve, porque só vive enquanto você escuta no editor.

2. O nó Code: conferir a assinatura#

Modo Run Once for All Items, linguagem JavaScript. O código faz a conferência que Receber eventos explica em palavras, e devolve valid (verdadeiro ou falso) e, se valer, o event já lido. Troque SECRET pelo segredo do passo anterior.

JavaScript
const crypto = require('crypto');

const SECRET = 'whsec_PASTE_YOUR_SECRET_HERE'; // cole aqui o segredo do seu endpoint (whsec_...). Em produção, guarde-o numa credencial ou numa variável.
const TOLERANCE_SECONDS = 300;

const header = $input.first().json.headers['x-luna-signature'] ?? ''; // o cabeçalho da assinatura (o nó Webhook escreve os nomes dos cabeçalhos em minúsculas)
const raw = await this.helpers.getBinaryDataBuffer(0, 'data'); // os bytes exatos que chegaram: o nó Webhook precisa estar com a opção Raw Body ligada

const m = /^t=(\d{1,15}),/.exec(header);
if (!m) return [{ json: { valid: false } }];
const t = Number(m[1]);

// recuse o que é velho demais (uma entrega capturada e repetida depois)
if (Math.abs(Math.floor(Date.now() / 1000) - t) > TOLERANCE_SECONDS) {
  return [{ json: { valid: false } }];
}

// refaça a conta com o seu segredo e compare com cada v1
const expected = crypto.createHmac('sha256', SECRET).update(t + '.').update(raw).digest();
let valid = false;
// na troca do segredo o cabeçalho traz dois valores v1: confira todos
for (const [, hex] of header.matchAll(/v1=([0-9a-fA-F]{64})/g)) {
  if (crypto.timingSafeEqual(Buffer.from(hex, 'hex'), expected)) valid = true;
}

// o próximo nó lê valid e, se for verdadeiro, o evento
return [{ json: { valid, event: valid ? JSON.parse(raw.toString('utf8')) : null } }];

3. O nó HTTP Request: enviar a resposta#

Depois de um nó “IF” que deixa passar só o que tem valid verdadeiro, e de outro que filtra event.event_type igual a message.received, o HTTP Request chama a API:

CampoValor
MethodPOST
URLhttps://api.lunahia.com.br/v1/messages
Cabeçalho AuthorizationBearer hlsn_... (a sua chave; no n8n, prefira uma credencial “Header Auth”)
Cabeçalho Idempotency-Keyresp- seguido do id da mensagem recebida: com ele, repetir a execução não envia duas respostas
Body (JSON)from (o seu número), to (o wa_id do evento) e text.body

Um fluxo pronto para importar#

O JSON abaixo é o fluxo inteiro: Webhook, Code, IF, as duas respostas, o filtro de mensagem recebida e o HTTP Request. Copie, e no n8n cole no canvas (Ctrl+V ou Cmd+V) ou use Import from File. Depois troque os três valores PASTE_...: o segredo no nó Code, a chave de API e o número no HTTP Request.

JSON
{
  "name": "Luna: responder mensagem recebida",
  "nodes": [
    {
      "parameters": {
        "httpMethod": "POST",
        "path": "luna",
        "responseMode": "responseNode",
        "options": {
          "rawBody": true
        }
      },
      "id": "5b0c1c1e-2f3a-4b5c-8d6e-7f8091a2b3c1",
      "name": "Webhook da Luna",
      "type": "n8n-nodes-base.webhook",
      "typeVersion": 2,
      "position": [
        0,
        300
      ],
      "webhookId": "9d8c7b6a-5e4f-4a3b-9c2d-1e0f9a8b7c6d"
    },
    {
      "parameters": {
        "jsCode": "const crypto = require('crypto');\n\nconst SECRET = 'whsec_PASTE_YOUR_SECRET_HERE'; // cole aqui o segredo do seu endpoint (whsec_...). Em produção, guarde-o numa credencial ou numa variável.\nconst TOLERANCE_SECONDS = 300;\n\nconst header = $input.first().json.headers['x-luna-signature'] ?? ''; // o cabeçalho da assinatura (o nó Webhook escreve os nomes dos cabeçalhos em minúsculas)\nconst raw = await this.helpers.getBinaryDataBuffer(0, 'data'); // os bytes exatos que chegaram: o nó Webhook precisa estar com a opção Raw Body ligada\n\nconst m = /^t=(\\d{1,15}),/.exec(header);\nif (!m) return [{ json: { valid: false } }];\nconst t = Number(m[1]);\n\n// recuse o que é velho demais (uma entrega capturada e repetida depois)\nif (Math.abs(Math.floor(Date.now() / 1000) - t) > TOLERANCE_SECONDS) {\n  return [{ json: { valid: false } }];\n}\n\n// refaça a conta com o seu segredo e compare com cada v1\nconst expected = crypto.createHmac('sha256', SECRET).update(t + '.').update(raw).digest();\nlet valid = false;\n// na troca do segredo o cabeçalho traz dois valores v1: confira todos\nfor (const [, hex] of header.matchAll(/v1=([0-9a-fA-F]{64})/g)) {\n  if (crypto.timingSafeEqual(Buffer.from(hex, 'hex'), expected)) valid = true;\n}\n\n// o próximo nó lê valid e, se for verdadeiro, o evento\nreturn [{ json: { valid, event: valid ? JSON.parse(raw.toString('utf8')) : null } }];"
      },
      "id": "6c1d2d2f-3a4b-4c5d-9e7f-8a9102b3c4d2",
      "name": "Verificar a assinatura",
      "type": "n8n-nodes-base.code",
      "typeVersion": 2,
      "position": [
        240,
        300
      ]
    },
    {
      "parameters": {
        "conditions": {
          "options": {
            "caseSensitive": true,
            "leftValue": "",
            "typeValidation": "strict",
            "version": 2
          },
          "conditions": [
            {
              "id": "a1b2c3d4-0001-4000-8000-000000000001",
              "leftValue": "={{ $json.valid }}",
              "rightValue": "",
              "operator": {
                "type": "boolean",
                "operation": "true",
                "singleValue": true
              }
            }
          ],
          "combinator": "and"
        },
        "options": {}
      },
      "id": "7d2e3e30-4b5c-4d6e-8f80-9b0213c4d5e3",
      "name": "Assinatura válida?",
      "type": "n8n-nodes-base.if",
      "typeVersion": 2.2,
      "position": [
        480,
        300
      ]
    },
    {
      "parameters": {
        "respondWith": "noData",
        "options": {
          "responseCode": 200
        }
      },
      "id": "8e3f4f41-5c6d-4e7f-9091-ac1324d5e6f4",
      "name": "Responder 200",
      "type": "n8n-nodes-base.respondToWebhook",
      "typeVersion": 1.1,
      "position": [
        720,
        200
      ]
    },
    {
      "parameters": {
        "respondWith": "noData",
        "options": {
          "responseCode": 401
        }
      },
      "id": "9f405052-6d7e-4f80-a1a2-bd2435e6f705",
      "name": "Responder 401",
      "type": "n8n-nodes-base.respondToWebhook",
      "typeVersion": 1.1,
      "position": [
        720,
        420
      ]
    },
    {
      "parameters": {
        "conditions": {
          "options": {
            "caseSensitive": true,
            "leftValue": "",
            "typeValidation": "strict",
            "version": 2
          },
          "conditions": [
            {
              "id": "a1b2c3d4-0002-4000-8000-000000000002",
              "leftValue": "={{ $('Verificar a assinatura').item.json.event.event_type === 'message.received' }}",
              "rightValue": "",
              "operator": {
                "type": "boolean",
                "operation": "true",
                "singleValue": true
              }
            }
          ],
          "combinator": "and"
        },
        "options": {}
      },
      "id": "a0516163-7e8f-4091-b2b3-ce3546f70816",
      "name": "É mensagem recebida?",
      "type": "n8n-nodes-base.if",
      "typeVersion": 2.2,
      "position": [
        960,
        200
      ]
    },
    {
      "parameters": {
        "method": "POST",
        "url": "https://api.lunahia.com.br/v1/messages",
        "sendHeaders": true,
        "headerParameters": {
          "parameters": [
            {
              "name": "Authorization",
              "value": "Bearer hlsn_PASTE_YOUR_KEY_HERE"
            },
            {
              "name": "Idempotency-Key",
              "value": "=resp-{{ $('Verificar a assinatura').item.json.event.message.id }}"
            }
          ]
        },
        "sendBody": true,
        "specifyBody": "json",
        "jsonBody": "={{ JSON.stringify({ from: 'PASTE_YOUR_NUMBER_ID_HERE', to: $('Verificar a assinatura').item.json.event.message.wa_id, text: { body: 'Recebi: ' + $('Verificar a assinatura').item.json.event.message.text } }) }}",
        "options": {}
      },
      "id": "b1627274-8f90-4102-83c4-df4657081927",
      "name": "Enviar a resposta",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.2,
      "position": [
        1200,
        100
      ]
    }
  ],
  "connections": {
    "Webhook da Luna": {
      "main": [
        [
          {
            "node": "Verificar a assinatura",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Verificar a assinatura": {
      "main": [
        [
          {
            "node": "Assinatura válida?",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Assinatura válida?": {
      "main": [
        [
          {
            "node": "Responder 200",
            "type": "main",
            "index": 0
          }
        ],
        [
          {
            "node": "Responder 401",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Responder 200": {
      "main": [
        [
          {
            "node": "É mensagem recebida?",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "É mensagem recebida?": {
      "main": [
        [
          {
            "node": "Enviar a resposta",
            "type": "main",
            "index": 0
          }
        ]
      ]
    }
  },
  "pinData": {},
  "settings": {
    "executionOrder": "v1"
  }
}

Para montar e testar o fluxo sem mandar mensagem de verdade, use uma chave de teste no HTTP Request: o envio não vai à Meta, e a Luna entrega ao seu webhook os estados sent, delivered e read com test: true. Veja Modo de teste. Um agente de IA que responde com um modelo no meio do fluxo segue o laço de Agente de IA.

Em breve: o SDK e o nó próprio#

SDK Node/TypeScript#

O SDK é o cliente tipado gerado da especificação, com três acréscimos: a URL de produção como padrão (criarLuna), o tratamento de erro (exigir devolve o corpo de uma resposta boa e lança LunaErro na recusa, com status, codigo e docsUrl) e a verificação da assinatura do webhook. Cada caminho e cada verbo vêm da especificação, então uma rota que a API não serve é erro de compilação.

Criar o cliente e enviarJavaScript
import { criarLuna, exigir } from '@helsen/sdk';

const luna = criarLuna({ apiKey: process.env.LUNA_API_KEY });

const envio = exigir(
  await luna.POST('/v1/messages', {
    body: { from: '1000000000000001', to: '5511900000000', type: 'text', text: { body: 'Olá!' } },
  }),
);
console.log(envio.id, envio.status);

Conferir a assinatura do webhook#

lerEvento confere a assinatura (x-luna-signature) sobre os bytes exatos do corpo e só então lê o JSON, devolvendo o evento tipado por event_type. Com assinatura que não confere, lança AssinaturaInvalida, e o corpo não é lido. verificarAssinatura só devolve true ou false. Durante a rotação do segredo, passe uma lista com o novo e o antigo. É o mesmo código que a Luna usa para assinar, então o resultado concorda com o do verificador de referência em Receber eventos.

Um servidor de webhook com o SDKJavaScript
import express from 'express';
import { lerEvento, AssinaturaInvalida, CABECALHO_DA_ASSINATURA } from '@helsen/sdk';

const app = express();

// O corpo precisa chegar como bytes, sem passar por express.json() antes.
app.post('/luna', express.raw({ type: 'application/json' }), (req, res) => {
  try {
    const evento = lerEvento(req.body, req.headers[CABECALHO_DA_ASSINATURA], process.env.LUNA_WEBHOOK_SECRET);
    if (evento.event_type === 'message.received') console.log(evento.message.text);
    res.sendStatus(200);
  } catch (erro) {
    if (erro instanceof AssinaturaInvalida) return res.sendStatus(401);
    throw erro;
  }
});

Um evento com test: true é de teste. Veja Modo de teste.

Nó do n8n#

O pacote traz uma credencial e dois nós. A credencial Luna API guarda a chave (hlsn_...) e a URL da API, e o botão de teste dela lê GET /v1/numbers, então a chave precisa do escopo numbers:read. O nó Luna envia texto, envia template e lista os números. O gatilho Luna Trigger inicia o fluxo quando a Luna entrega um evento.

Enviar uma mensagem#

  1. Crie a credencial com a sua chave de API.
  2. No nó Luna, escolha Mensagem e Enviar Texto, ou Enviar Template. Preencha o número de origem (o metaPhoneNumberId que Listar Números devolve), o telefone do destinatário (só dígitos) e o conteúdo.
  3. A saída é o 202 da API, com o id da mensagem. Se a API recusar (por exemplo 409, texto fora da janela de 24 horas), o nó falha com a resposta dela; com "Continuar em caso de erro" ligado, o erro vira um item.

Receber eventos no n8n#

  1. Ative o fluxo e copie a URL de produção do webhook do nó Luna Trigger.
  2. Cadastre essa URL como endpoint da Luna (POST /v1/webhooks/endpoints). A resposta traz o segredo uma única vez.
  3. Cole o segredo no campo "Segredo de Assinatura" do nó.

O nó confere a assinatura sobre os bytes exatos do corpo e responde 401, sem rodar o fluxo, quando ela não confere. Ele não cadastra o endpoint sozinho. Dá para filtrar por tipo de evento (separados por vírgula, vazio quer dizer todos) e descartar os eventos com test: true.

Montar o fluxo sem mandar mensagem de verdade#

Use uma chave de teste na credencial do n8n, ou no SDK. Enviar não vai à Meta, e a Luna entrega ao seu webhook os estados sent, delivered e read, com test: true. O botão de teste da credencial do n8n lê GET /v1/numbers e uma chave de teste não passa nele, mas as operações de enviar funcionam. O guia Modo de teste explica tudo.