SDK e n8n
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
401a 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 osecretda 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.
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:
| Campo | Valor |
|---|---|
| Method | POST |
| URL | https://api.lunahia.com.br/v1/messages |
Cabeçalho Authorization | Bearer hlsn_... (a sua chave; no n8n, prefira uma credencial “Header Auth”) |
Cabeçalho Idempotency-Key | resp- 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.
{
"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.
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.
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#
- Crie a credencial com a sua chave de API.
- No nó Luna, escolha Mensagem e Enviar Texto, ou Enviar Template. Preencha o número de origem (o
metaPhoneNumberIdque Listar Números devolve), o telefone do destinatário (só dígitos) e o conteúdo. - A saída é o
202da API, com oidda mensagem. Se a API recusar (por exemplo409, 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#
- Ative o fluxo e copie a URL de produção do webhook do nó Luna Trigger.
- Cadastre essa URL como endpoint da Luna (
POST /v1/webhooks/endpoints). A resposta traz o segredo uma única vez. - 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.