LunaDocs

Carregando a busca...

EnglishEntrar no console
Nesta página

SaaS com N clientes

Usar com IA

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:

OndeO que o externalId faz
POST /v1/onboarding/linksMarca o link e o número que resultar dele.
Todo evento de número e de linkVem 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 linksO filtro ?externalId= devolve só o que é do cliente, sem você guardar o mapa de números.
POST /v1/api-keysA chave de UM cliente: só enxerga e usa os números dele.
POST /v1/webhooks/endpointsO 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())

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 (Node 18 ou mais novo)JavaScript
// 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:

Texto
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:

EventoO que diz
onboarding.link.completedO cliente concluiu a conexão por um link.
onboarding.link.failedUma 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.expiredO link venceu sem uso. Gere outro.
number.connectedO número ficou pronto: já pode enviar e receber.
number.connectedJSON
{
  "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.mjsJavaScript
// 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

EventoOnde vem o externalId
Mensagens e contatos: message.received, message.status, message.echo, contact.*, backlog.dropped, history_sync.deadline_approachingnumber.external_id
number.* (conectou, desconectou, qualidade, pagamento, ação, credencial, nome) e account.*number.external_id
onboarding.link.completedlink.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.expiredlink.external_id (ainda não há número)
Templates e o teste: template.status, template.category, template.quality, webhook.testEm 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.tsJavaScript
// 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())
Resposta (resumida)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.

number.action_requiredJSON
{
  "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 fazComo na Luna
Entrar um clientePOST /v1/onboarding/links com externalId e redirectUrl
Saber que ele conectouonboarding.link.completed e number.connected
Saber que ele desistiuonboarding.link.failed e onboarding.link.expired
EnviarPOST /v1/messages com from (UUID da Luna ou id da Meta)
Receber de todosUm endpoint e o number.external_id de cada evento
Mostrar o estadoconnection e number.action_required / number.action_resolved
Dar acesso direto ao clientePOST /v1/api-keys com externalId
Uma URL por clienteexternalIds no endpoint de webhook
Sair um clienteDELETE /v1/numbers/{id}
Ver a capacidadeGET /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.

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.

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.

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.

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.