SaaS com N clientes
Você tem um produto, os seus clientes têm negócios, e cada negócio precisa do próprio WhatsApp dentro do seu produto. Na Luna, cada negócio conecta o número dele (a “instância” é o número), e o fio que amarra tudo é o `externalId`: o rótulo que você dá ao cliente. Ele volta no link, no número, na chave, no webhook e em todo evento de número e de link. Este guia segue o caminho de um SaaS que contrata 20 números.
O contrato de cada rota, campo a campo, está na referência da API. Este guia segue a ordem em que um produto com muitos clientes usa as rotas.
O fio: um externalId por cliente#
O externalId é texto livre de 1 a 128 caracteres que a Luna nunca interpreta. Use o identificador do cliente no seu sistema. Ele nasce no link de conexão, vai para o número quando o cliente conecta, e a partir daí amarra o resto:
| Onde | O que o externalId faz |
|---|---|
POST /v1/onboarding/links | Marca o link e o número que resultar dele. |
| Todo evento de número e de link | Vem em number.external_id (e em link.external_id nos eventos do link). Separa os clientes num endpoint só. Os eventos de template e o de teste não têm cliente: veja a tabela da seção 3. |
| As listas de números, mensagens, conversas e links | O filtro ?externalId= devolve só o que é do cliente, sem você guardar o mapa de números. |
POST /v1/api-keys | A chave de UM cliente: só enxerga e usa os números dele. |
POST /v1/webhooks/endpoints | O endpoint de UM cliente (externalIds), se você prefere uma URL por cliente. |
1. A capacidade do plano#
O plano define uma coisa só: quantos números a conta mantém ativos ao mesmo tempo. Com 20 números contratados, você conecta 20 clientes. GET /v1/subscription diz a capacidade e quantos estão em uso, e o 21º link responde 409 com error: "number_capacity_reached". Para contratar ou ampliar, escreva para contato@lunahia.com.br. Detalhes em Plano e números.
curl -X GET "https://api.lunahia.com.br/v1/subscription" \
-H "Authorization: Bearer $LUNA_API_KEY"const res = await fetch('https://api.lunahia.com.br/v1/subscription', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
},
});
console.log(res.status, await res.json());import os
import requests
res = requests.get(
"https://api.lunahia.com.br/v1/subscription",
headers={
"Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
},
timeout=10,
)
print(res.status_code, res.json())2. Um link por cliente#
Crie um link com o externalId do cliente e mande a url a ele. A url sai uma vez: guarde ou envie na hora. O cliente abre a página da Luna, aceita os termos da Meta e conecta o número dele. Com redirectUrl (https), a página o devolve ao seu produto quando a conexão termina.
curl -X POST "https://api.lunahia.com.br/v1/onboarding/links" \
-H "Authorization: Bearer $LUNA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"externalId": "cliente-42",
"redirectUrl": "https://app.example.com/whatsapp/conectado"
}'const res = await fetch('https://api.lunahia.com.br/v1/onboarding/links', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"externalId": "cliente-42",
"redirectUrl": "https://app.example.com/whatsapp/conectado"
}),
});
console.log(res.status, await res.json());import os
import requests
res = requests.post(
"https://api.lunahia.com.br/v1/onboarding/links",
headers={
"Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
},
json={
"externalId": "cliente-42",
"redirectUrl": "https://app.example.com/whatsapp/conectado",
},
timeout=10,
)
print(res.status_code, res.json())Para os 20 clientes de uma vez, um laço sobre a sua lista. O script abaixo lê customers.json, cria um link por cliente e imprime as URLs; um 409 de capacidade aparece no terminal e o laço segue.
// create-links.mjs: one connect link per customer of yours.
import { readFile } from 'node:fs/promises';
const API = 'https://api.lunahia.com.br';
const customers = JSON.parse(await readFile('./customers.json', 'utf8'));
// customers.json: [{ "externalId": "cliente-1" }, { "externalId": "cliente-2" }]
for (const customer of customers) {
const res = await fetch(`${API}/v1/onboarding/links`, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
externalId: customer.externalId,
// where the link page sends your customer back to when the connection ends
redirectUrl: `https://app.example.com/whatsapp/done?customer=${customer.externalId}`,
}),
});
if (!res.ok) {
// 409 number_capacity_reached: the plan is full. Disconnect a number or ask for more capacity.
console.error(customer.externalId, res.status, await res.json());
continue;
}
const link = await res.json();
// The url is returned ONCE. Send it to the customer now.
console.log(customer.externalId, link.url);
}
Quando a conexão termina, a página leva o cliente à sua redirectUrl e acrescenta na query status (o estado final da conexão), externalId (o rótulo do link), numberId (o número, quando a Luna já o registrou; logo depois de concluir ele costuma vir vazio e some da query) e signature:
https://app.example.com/whatsapp/conectado?status=APP_SUBSCRIBED&externalId=cliente-8841&signature=t%3D1793800000%2Cv1%3D9f2c...Confira que o retorno veio da Luna
Qualquer pessoa pode abrir a sua redirectUrl com um status inventado. A signature prova que a Luna montou aqueles valores: é a mesma assinatura dos webhooks (t=<t>,v1=<hmac>), feita com o segredo do endpoint de webhook mais antigo da sua conta (o mesmo whsec_ que você já usa para validar eventos), sobre o texto status=<status>&numberId=<numberId>&externalId=<externalId>, com os valores como estão na query (vazios quando ausentes). O instante vale 5 minutos: confira ao receber o cliente, e não depois. Sem endpoint de webhook cadastrado, a signature não vai, e nesse caso trate o retorno como não confiável e leia o estado em GET /v1/numbers.
import { verifyLunaSignature } from './verify.mjs';
// a mesma conferência de um webhook, sobre o texto que a página do link assinou (os valores como estão na query)
export function verifyConnectionReturn(returnUrl, secret, nowMs = Date.now()) {
const q = new URL(returnUrl).searchParams;
const text = `status=${q.get('status') ?? ''}&numberId=${q.get('numberId') ?? ''}&externalId=${q.get('externalId') ?? ''}`;
return verifyLunaSignature(Buffer.from(text), q.get('signature'), secret, nowMs);
}from urllib.parse import parse_qs, urlparse
from verify import verify_luna_signature
def verify_connection_return(return_url, secret, now=None):
# a mesma conferência de um webhook, sobre o texto que a página do link assinou (os valores como estão na query)
q = {k: v[0] for k, v in parse_qs(urlparse(return_url).query).items()}
text = f"status={q.get('status', '')}&numberId={q.get('numberId', '')}&externalId={q.get('externalId', '')}"
return verify_luna_signature(text.encode(), q.get("signature"), secret, now)O cliente também pode ser reconhecido na página: mande displayName (de 1 a 120 caracteres) em POST /v1/onboarding/links e ela mostra "Conexão do WhatsApp de ..." acima do título. O nome que a janela da Meta mostra não dá para mudar: a janela é da Meta e mostra o nome da Luna e do negócio, e não o do seu cliente.
Para achar o link de um cliente, filtre pelo rótulo:
curl -X GET "https://api.lunahia.com.br/v1/onboarding/links?externalId=cliente-42" \
-H "Authorization: Bearer $LUNA_API_KEY"const res = await fetch('https://api.lunahia.com.br/v1/onboarding/links?externalId=cliente-42', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
},
});
console.log(res.status, await res.json());import os
import requests
res = requests.get(
"https://api.lunahia.com.br/v1/onboarding/links?externalId=cliente-42",
headers={
"Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
},
timeout=10,
)
print(res.status_code, res.json())O link vale 72 horas, abre uma vez e se revoga com DELETE /v1/onboarding/links/{id}. Mais sobre o fluxo do cliente e a coexistência em Conectar um número.
3. Todos os eventos num endpoint só#
O caminho recomendado é um endpoint para todos os clientes. Cadastre-o como em Receber eventos, verifique a assinatura, e separe os clientes por number.external_id. Quatro eventos contam a conexão de um cliente, e todos trazem o externalId:
| Evento | O que diz |
|---|---|
onboarding.link.completed | O cliente concluiu a conexão por um link. |
onboarding.link.failed | Uma tentativa não deu certo, com reason (abandonou, erro da Meta, número fora do +55, registro bloqueado) e step, a tela em que ele parou. |
onboarding.link.expired | O link venceu sem uso. Gere outro. |
number.connected | O número ficou pronto: já pode enviar e receber. |
{
"version": "2026-11-10",
"event_id": "458470a340db14358f03ac02fde7e3839cb6887f3071c06c57a3d9d456621996",
"event_type": "number.connected",
"occurred_at": "2026-10-07T13:45:00.000Z",
"phone_number_id": "123456789012345",
"number": {
"id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
"phone_number_id": "123456789012345",
"display_number": "+55 11 90000-0000",
"external_id": "cliente-8841",
"waba_id": "102290129340398",
"coexistence": false
}
}O roteador abaixo é a parte do seu servidor que decide a quem o evento pertence. Chame-o depois de verificar a assinatura; ele descarta repetições pelo event_id e ignora o rótulo que você não conhece (responda 2xx em qualquer caso).
// router.mjs: one webhook endpoint for all your customers.
// Call route(event) AFTER verifying the signature (see the Receive events guide).
/** externalId -> { onEvent(event) } for each customer of yours. */
export function createRouter(handlers) {
const seen = new Set();
return function route(event) {
// The same delivery can arrive more than once: drop repeats by event_id.
if (seen.has(event.event_id)) return 'duplicate';
seen.add(event.event_id);
// number.external_id is on every event that goes through a number;
// link events carry it in link.external_id.
const customer = event.number?.external_id ?? event.link?.external_id ?? null;
if (customer === null) return 'no-customer';
const handler = handlers.get(customer);
// A label you do not know, or an event type you do not handle: answer 2xx anyway.
if (handler === undefined) return 'unknown-customer';
handler.onEvent(event);
return 'handled';
};
}
Onde está o externalId em cada evento
| Evento | Onde vem o externalId |
|---|---|
Mensagens e contatos: message.received, message.status, message.echo, contact.*, backlog.dropped, history_sync.deadline_approaching | number.external_id |
number.* (conectou, desconectou, qualidade, pagamento, ação, credencial, nome) e account.* | number.external_id |
onboarding.link.completed | link.external_id, e number.external_id do número que acabou de conectar |
Os outros do link: onboarding.link.opened, onboarding.link.failed, onboarding.link.expired | link.external_id (ainda não há número) |
Templates e o teste: template.status, template.category, template.quality, webhook.test | Em lugar nenhum: são da conta de negócio ou do teste, e não de um cliente. O roteador devolve no-customer, e só um endpoint sem filtro os recebe. |
O number.external_id é null num número que nunca recebeu rótulo. Esse caso, e os eventos da última linha, são o no-customer do roteador: trate-os à parte, ou ignore.
Um servidor completo em TypeScript
O arquivo abaixo junta tudo: verifica a assinatura, responde 200, descarta a repetição e entrega cada evento ao código do cliente certo, por um Map. Os tipos mostram que external_id pode ser null. Rode com node server.ts (Node 24 ou mais novo, que apaga os tipos sozinho) e LUNA_WEBHOOK_SECRET definida.
// server.ts: run with Node 24 or newer: node server.ts
import crypto from 'node:crypto';
import http from 'node:http';
// Os campos do evento que este arquivo lê (há mais: veja Receber eventos).
interface LunaEvent {
event_id: string;
event_type: string;
number?: { id: string; phone_number_id: string; external_id: string | null } | null; // external_id: null num número que nunca recebeu rótulo
link?: { id: string; external_id: string | null } | null;
}
// 1. Verifique a assinatura (a explicação está no guia Receber eventos).
const SECRET = process.env.LUNA_WEBHOOK_SECRET ?? '';
const TOLERANCE_SECONDS = 300;
function verify(raw: Buffer, header: string | undefined): boolean { // raw: os bytes exatos que chegaram, nunca o JSON reserializado
const m = /^t=(\d{1,15}),/.exec(header ?? '');
if (!m || !SECRET) return false;
const t = Number(m[1]);
if (Math.abs(Math.floor(Date.now() / 1000) - t) > TOLERANCE_SECONDS) return false;
const expected = crypto.createHmac('sha256', SECRET).update(`${t}.`).update(raw).digest();
let ok = 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 as string, 'hex'), expected)) ok = true;
}
return ok;
}
// 2. Os clientes: externalId -> o código que trata aquele cliente.
type CustomerHandler = (event: LunaEvent) => void | Promise<void>;
const customers = new Map<string, CustomerHandler>([
['cliente-1', (event) => console.log('cliente-1', event.event_type)],
['cliente-2', (event) => console.log('cliente-2', event.event_type)],
]);
const seen = new Set<string>(); // em produção: um banco ou Redis, com prazo de validade
function route(event: LunaEvent): 'duplicate' | 'no-customer' | 'unknown-customer' | 'handled' {
if (seen.has(event.event_id)) return 'duplicate';
seen.add(event.event_id);
// number.external_id nos eventos de um número; link.external_id nos eventos de um link
const customer = event.number?.external_id ?? event.link?.external_id ?? null;
if (customer === null) return 'no-customer';
const handler = customers.get(customer);
if (handler === undefined) return 'unknown-customer'; // um rótulo que você não conhece: responda 2xx do mesmo jeito
void Promise.resolve(handler(event)).catch((err) => console.error(customer, 'handler failed', err));
return 'handled';
}
// 3. O servidor: verifique, responda e só então roteie.
http
.createServer((req, res) => {
const chunks: Buffer[] = [];
req.on('data', (chunk: Buffer) => chunks.push(chunk));
req.on('end', () => {
const raw = Buffer.concat(chunks);
const header = req.headers['x-luna-signature'];
if (!verify(raw, typeof header === 'string' ? header : undefined)) {
res.writeHead(401).end();
return;
}
res.writeHead(200).end(); // responda primeiro, trabalhe depois
console.log(route(JSON.parse(raw.toString('utf8')) as LunaEvent));
});
})
.listen(Number(process.env.PORT ?? 3000));
4. Enviar por número#
Ache os números do cliente pelo rótulo e envie por um deles. from aceita o UUID da Luna ou o id da Meta. ?canSend=true devolve só os números por onde enviar funciona agora.
curl -X GET "https://api.lunahia.com.br/v1/numbers?externalId=cliente-42&canSend=true" \
-H "Authorization: Bearer $LUNA_API_KEY"const res = await fetch('https://api.lunahia.com.br/v1/numbers?externalId=cliente-42&canSend=true', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
},
});
console.log(res.status, await res.json());import os
import requests
res = requests.get(
"https://api.lunahia.com.br/v1/numbers?externalId=cliente-42&canSend=true",
headers={
"Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
},
timeout=10,
)
print(res.status_code, res.json())curl -X POST "https://api.lunahia.com.br/v1/messages" \
-H "Authorization: Bearer $LUNA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"from": "YOUR_NUMBER_ID",
"to": "5511900000000",
"type": "text",
"text": {
"body": "Seu pedido saiu para entrega."
}
}'const res = await fetch('https://api.lunahia.com.br/v1/messages', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"from": "YOUR_NUMBER_ID",
"to": "5511900000000",
"type": "text",
"text": {
"body": "Seu pedido saiu para entrega."
}
}),
});
console.log(res.status, await res.json());import os
import uuid
import requests
res = requests.post(
"https://api.lunahia.com.br/v1/messages",
headers={
"Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"from": "YOUR_NUMBER_ID",
"to": "5511900000000",
"type": "text",
"text": {
"body": "Seu pedido saiu para entrega.",
},
},
timeout=10,
)
print(res.status_code, res.json())O histórico e as conversas também filtram pelo cliente, e o envio fora da janela de 24 horas é só por template. Veja Enviar mensagens e Templates. Com uma conta de negócio por cliente, GET /v1/templates?wabaId= ou ?phoneNumberId= mostra os templates de cada um.
curl -X GET "https://api.lunahia.com.br/v1/messages?externalId=cliente-42&limit=20" \
-H "Authorization: Bearer $LUNA_API_KEY"const res = await fetch('https://api.lunahia.com.br/v1/messages?externalId=cliente-42&limit=20', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
},
});
console.log(res.status, await res.json());import os
import requests
res = requests.get(
"https://api.lunahia.com.br/v1/messages?externalId=cliente-42&limit=20",
headers={
"Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
},
timeout=10,
)
print(res.status_code, res.json())5. O estado de cada número#
Para mostrar ao cliente se o número dele está bem, leia connection (a mesma conta que decide os eventos): status (connected, connecting, action_required ou disconnected), canSend e reasons, cada motivo com code, message e solution em português, prontos para repassar.
curl -X GET "https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID" \
-H "Authorization: Bearer $LUNA_API_KEY"const res = await fetch('https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
},
});
console.log(res.status, await res.json());import os
import requests
res = requests.get(
"https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID",
headers={
"Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
},
timeout=10,
)
print(res.status_code, res.json()){
"id": "ed404df1-b420-4ed6-8743-ba1609892e0a",
"metaPhoneNumberId": "123456789012345",
"externalId": "cliente-42",
"state": "REGISTERED",
"ready": true,
"connection": {
"status": "connected",
"canSend": true,
"reasons": []
}
}Você não precisa consultar os 20 números: number.action_required avisa quando um passa a precisar de ação (autorização vencendo, método de pagamento ausente na Meta, conta restrita), e number.action_resolved avisa quando deixa de precisar. A lista de números aceita ?state=, ?ready=, ?canSend=, ?limit= e ?cursor= para montar o painel de todos de uma vez.
{
"version": "2026-11-10",
"event_id": "8832cdd12544436fce3b39d709158baa046091d010b5ed144a289c81b807c710",
"event_type": "number.action_required",
"occurred_at": "2026-10-28T15:02:00.000Z",
"phone_number_id": "123456789012345",
"number": {
"id": "5b9e2c40-71d3-4f0a-9a8b-2c1d0e3f4a5b",
"phone_number_id": "123456789012345",
"display_number": "+55 11 90000-0000",
"external_id": "cliente-8841",
"status": "action_required",
"can_send": false,
"reasons": [
{
"code": "payment_required",
"message": "A Meta recusou um envio deste número por falta de método de pagamento na conta de WhatsApp Business do negócio.",
"solution": "O dono da conta cadastra o método de pagamento no WhatsApp Manager da Meta. A Luna não intermedeia esse pagamento. Quando um envio voltar a ser aceito, o aviso sai do ar."
}
]
}
}Autorização perto de vencer é o caso que se repete: abra um link de reconexão com POST /v1/onboarding/links informando numberId, e o cliente renova sem contar um número novo. Os casos estão em Saúde da conta e Pagamento na Meta.
6. Uma chave por cliente#
Se o cliente do seu cliente acessa a API diretamente, ou se você quer reduzir o estrago de uma chave vazada, crie uma chave com externalId. Ela só lê e envia pelos números com aquele rótulo (inclusive os conectados depois), só cria link com ele, só vê os templates e as contas de negócio desses números, e não lista nem cria endpoints de webhook nem chaves, nem lê o plano. O número de outro cliente responde 404, igual a um que não existe, mesmo que o id dele seja passado de propósito; uma rota fora do conjunto responde 403. O externalId de uma chave não muda: para mudar, crie outra.
Quem cria a chave precisa do escopo keys:write. A chave que você usa para chamar POST /v1/api-keys tem de tê-lo (no console, a sessão ganha esse poder por duas horas depois de você confirmar a senha). Sem o escopo, a resposta é 403, e o corpo diz qual falta: requiredScope: "keys:write". Os escopos da chave nova são escolhidos por você, dentro do que a chave de um cliente pode usar (mensagens, números, templates e o link de conexão).
curl -X POST "https://api.lunahia.com.br/v1/api-keys" \
-H "Authorization: Bearer $LUNA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"label": "Clínica Exemplo",
"scopes": [
"messages:read",
"messages:write",
"numbers:read"
],
"externalId": "cliente-42"
}'const res = await fetch('https://api.lunahia.com.br/v1/api-keys', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"label": "Clínica Exemplo",
"scopes": [
"messages:read",
"messages:write",
"numbers:read"
],
"externalId": "cliente-42"
}),
});
console.log(res.status, await res.json());import os
import requests
res = requests.post(
"https://api.lunahia.com.br/v1/api-keys",
headers={
"Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
},
json={
"label": "Clínica Exemplo",
"scopes": [
"messages:read",
"messages:write",
"numbers:read",
],
"externalId": "cliente-42",
},
timeout=10,
)
print(res.status_code, res.json())A resposta 201 traz o secret da chave (hlsn_...) uma única vez: guarde-o agora, no seu banco, na linha daquele cliente, junto do externalId. Não há rota que o devolva depois; se você o perder, revogue a chave (POST /v1/api-keys/{id}/revoke) e crie outra.
7. Um webhook por cliente (opcional)#
Se o seu produto prefere uma URL por cliente, o endpoint aceita externalIds (e phoneNumberIds): ele só recebe os eventos de números com aquele rótulo, inclusive os conectados depois, e os eventos de link dele. Ausentes, ele recebe de todos. O external_id continua em todo evento, nos dois jeitos. A assinatura, a ordem, o reenvio e a fila de rejeitados são os de qualquer endpoint.
curl -X POST "https://api.lunahia.com.br/v1/webhooks/endpoints" \
-H "Authorization: Bearer $LUNA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://saas.example.com/luna/cliente-42",
"externalIds": [
"cliente-42"
]
}'const res = await fetch('https://api.lunahia.com.br/v1/webhooks/endpoints', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"url": "https://saas.example.com/luna/cliente-42",
"externalIds": [
"cliente-42"
]
}),
});
console.log(res.status, await res.json());import os
import requests
res = requests.post(
"https://api.lunahia.com.br/v1/webhooks/endpoints",
headers={
"Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
},
json={
"url": "https://saas.example.com/luna/cliente-42",
"externalIds": [
"cliente-42",
],
},
timeout=10,
)
print(res.status_code, res.json())curl -X PATCH "https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID" \
-H "Authorization: Bearer $LUNA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"externalIds": [
"cliente-42",
"cliente-43"
]
}'const res = await fetch('https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID', {
method: 'PATCH',
headers: {
Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"externalIds": [
"cliente-42",
"cliente-43"
]
}),
});
console.log(res.status, await res.json());import os
import requests
res = requests.patch(
"https://api.lunahia.com.br/v1/webhooks/endpoints/YOUR_ENDPOINT_ID",
headers={
"Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
},
json={
"externalIds": [
"cliente-42",
"cliente-43",
],
},
timeout=10,
)
print(res.status_code, res.json())8. Desconectar e trocar o cliente#
O cliente 21 entra no lugar do 3? Desconecte o número do 3 com DELETE /v1/numbers/{id}: ele sai da Luna, para de contar na capacidade e o evento number.disconnected avisa (reason: "requested_by_tenant"). A Luna não chama deregister na Meta, para não derrubar o número do cliente em outro provedor ou no aplicativo. O histórico fica. Para reaproveitar um número para outro cliente seu, troque o rótulo com PATCH /v1/numbers/{id}.
curl -X DELETE "https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID" \
-H "Authorization: Bearer $LUNA_API_KEY"const res = await fetch('https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID', {
method: 'DELETE',
headers: {
Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
},
});
console.log(res.status);import os
import requests
res = requests.delete(
"https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID",
headers={
"Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
},
timeout=10,
)
print(res.status_code)curl -X PATCH "https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID" \
-H "Authorization: Bearer $LUNA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"externalId": "cliente-43"
}'const res = await fetch('https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID', {
method: 'PATCH',
headers: {
Authorization: `Bearer ${process.env.LUNA_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"externalId": "cliente-43"
}),
});
console.log(res.status, await res.json());import os
import requests
res = requests.patch(
"https://api.lunahia.com.br/v1/numbers/YOUR_NUMBER_ID",
headers={
"Authorization": f"Bearer {os.environ['LUNA_API_KEY']}",
},
json={
"externalId": "cliente-43",
},
timeout=10,
)
print(res.status_code, res.json())Em uma tabela#
| O que o seu produto faz | Como na Luna |
|---|---|
| Entrar um cliente | POST /v1/onboarding/links com externalId e redirectUrl |
| Saber que ele conectou | onboarding.link.completed e number.connected |
| Saber que ele desistiu | onboarding.link.failed e onboarding.link.expired |
| Enviar | POST /v1/messages com from (UUID da Luna ou id da Meta) |
| Receber de todos | Um endpoint e o number.external_id de cada evento |
| Mostrar o estado | connection e number.action_required / number.action_resolved |
| Dar acesso direto ao cliente | POST /v1/api-keys com externalId |
| Uma URL por cliente | externalIds no endpoint de webhook |
| Sair um cliente | DELETE /v1/numbers/{id} |
| Ver a capacidade | GET /v1/subscription |
Detalhes das rotas deste guia#
A referência da API diz como chamar cada rota, em poucas linhas. O que explica o motivo de cada decisão, os casos de borda e os avisos está aqui, na ordem da referência.
GET /v1/onboarding/links#
Cada um traz o status (open, used, expired ou revoked), o externalId que você deu e, depois que o cliente conecta, o numberId do número que resultou. Traz também createdAt, purpose (new para um número novo, reconnect para renovar a autorização de um número que já existe), revokedAt, lastFailure (a última tentativa que não deu certo, com step, reason e at, os mesmos do evento onboarding.link.failed, ou nulo) e allowedActions (revoke, só num link aberto). Nenhum traz o token nem a url: ela só saiu na criação.
Use ?externalId= para achar os links de um cliente seu: a comparação é exata, e um rótulo sem link devolve lista vazia. Use ?status= (open, used, expired ou revoked) para filtrar pelo estado. Os links revogados continuam na lista.
Para paginar, mande de volta o nextCursor da resposta anterior em cursor. Nulo significa fim.
POST /v1/onboarding/links#
A janela de conexão da Meta só abre em domínio cadastrado no aplicativo da Luna. Por isso o link aponta para uma página do console da Luna, que mostra o nome da sua conta, explica o que será pedido e abre a janela da Meta para o seu cliente. Quem entra com o Facebook e aceita os termos da Meta é o negócio dele, e não você em nome dele.
externalId é o seu identificador para este cliente, em texto livre de 1 a 128 caracteres. Ele fica no link e no número que resultar da conexão, e volta em GET /v1/numbers.
redirectUrl, opcional, é para onde a página do link leva o seu cliente quando a conexão termina (https). A página acrescenta na query status (o estado final da conexão), externalId (o rótulo do link), numberId (o número, quando a Luna já o registrou; logo depois de concluir ele costuma vir vazio e então não vai, e o evento number.connected avisa quando fica pronto) e signature, a assinatura de webhook sobre status, numberId e externalId com o segredo do seu endpoint de webhook mais antigo, para você conferir que o retorno veio da Luna (código em SaaS com N clientes). Sem redirectUrl, o cliente fica na página da Luna.
displayName, opcional, é o nome do seu cliente (de 1 a 120 caracteres) que a página do link mostra para ele reconhecer o pedido. A janela da Meta que abre em seguida mostra o nome da Luna e do negócio, e esse nome não dá para mudar.
O ciclo do link também chega por webhook: onboarding.link.completed quando o cliente conclui, onboarding.link.failed quando uma tentativa não dá certo (com o motivo e a tela em que ele parou) e onboarding.link.expired quando o link vence sem uso, todos com o externalId.
O link vale 72 horas para ser aberto. A resposta traz a url uma única vez: guarde-a ou envie-a agora, porque nenhuma rota devolve o token de novo. Quem tem a url pode conectar um número à sua conta, então trate-a como um segredo e mande-a só ao cliente certo.
numberId é opcional e transforma o link em link de RECONEXÃO: a página do seu cliente abre direto a renovação da autorização daquele número, sem contar um número novo. Use quando credentialStatus for reauth_required, ou quando o evento number.credential_expiring avisar que a autorização vence em até 14 dias. As regras são as de POST /v1/onboarding/reconnect: número seu e com autorização que admite reconexão (podeReconectar true); caso contrário responde 409, e número que não é seu responde 404. Sem externalId, o link herda o do número.
Para acompanhar, use GET /v1/onboarding/links/{id}, ou liste os números com ?externalId=. Para cancelar, use DELETE /v1/onboarding/links/{id}.
As mesmas condições de POST /v1/onboarding/sessions valem aqui: a conta precisa ter o e-mail confirmado.
GET /v1/onboarding/links/{id}#
Quem avisa que o seu cliente terminou é o evento number.connected, entregue no seu endpoint de webhook com o externalId do cliente. Esta leitura é a reserva, para o caso de o seu endpoint ter estado fora do ar, e não um laço de espera: não é preciso consultar de tempos em tempos. Quando o status vira used, usedAt traz o instante e numberId traz o número que resultou. O numberId aparece alguns instantes depois do used, porque a Luna registra o número em seguida; nulo no used significa que a conta foi conectada sem número.
Um link que você revogou continua aqui, com status revoked e revokedAt. Quem abre a url dele recebe 404, como se nunca tivesse existido.
DELETE /v1/onboarding/links/{id}#
Funciona também em link já usado ou vencido, e aí só o marca como revogado: o número conectado e o externalId dele continuam. O link fica na sua lista com status revoked. Revogar de novo um link já revogado responde 404.
GET /v1/public/onboarding-links/{token}#
O token é a credencial, e não há chave de API. Token desconhecido, malformado ou revogado responde 404, sempre igual. Um link vencido ou já usado responde 200 com o status, para a página poder dizer ao cliente que peça um novo.
A rota tem teto por endereço de origem.
POST /v1/public/onboarding-links/{token}/sessions#
Num link de reconexão (criado com numberId), a sessão já nasce amarrada à conta do número, como em POST /v1/onboarding/reconnect.
Pode ser chamada mais de uma vez enquanto o link está aberto: o cliente que fecha a janela da Meta tenta de novo. Link vencido ou já usado responde 410 com o motivo. Qualquer outro token inválido responde 404. A rota tem teto por endereço de origem.
POST /v1/public/onboarding-links/{token}/sessions/{sessionId}/complete#
Só conclui uma sessão aberta por este mesmo link. Quando a conexão conclui, o link passa a used, e o externalId dele vai para o número. Se o número escolhido não é +55, o estado é COUNTRY_NOT_SUPPORTED, nada é conectado e o link continua aberto para um número brasileiro.
Responde 200 mesmo quando um passo falha: o corpo traz o estado e a orientação. A rota tem teto por endereço de origem.
POST /v1/public/onboarding-links/{token}/sessions/{sessionId}/abandon#
Não muda o estado da sessão. A rota tem teto por endereço de origem.