Plano e números
O plano da Luna define uma coisa só: quantos números a sua conta pode manter ativos ao mesmo tempo. Este guia mostra como ler esse limite, o que fazer quando ele chega, e como abrir uma vaga.
O teste grátis#
Toda conta nova começa com um teste grátis de 14 dias, contados da confirmação do e-mail do cadastro, com capacidade para 1 número. Não precisa de liberação manual: depois de confirmar o e-mail, a conta conecta o número sozinha. A Helsen pode bloquear uma conta, e o bloqueio para a escrita e o envio como o fim do teste.
A cobrança automática ainda não existe. Para contratar um plano, ampliar a capacidade ou tirar a conta da suspensão, escreva para contato@lunahia.com.br. O uso da plataforma da Meta é pago pelo negócio dono do número, direto à Meta, e não entra em nada disso. Veja Custos da Meta.
Ler o plano e o uso#
GET /v1/subscription devolve o plano da conta e quantos números estão em uso, sem que o seu sistema precise calcular nada. O escopo é numbers:read.
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()){
"planName": "Teste grátis",
"status": "trial",
"suspendedReason": null,
"capacity": 1,
"activeNumbers": 1,
"canConnectNumber": false,
"capacityLeft": 0,
"capacityNotice": "Esta conta já tem 1 número ativo, o máximo contratado (1). Para conectar outro, desconecte um número (DELETE /v1/numbers/{id}) ou escreva para contato@lunahia.com.br.",
"writesAllowed": true,
"suspendedNotice": null,
"pricePerMonth": null,
"currency": null,
"contactEmail": "contato@lunahia.com.br",
"trialEndsAt": "2026-11-03T13:00:00.000Z",
"trialDaysLeft": 5,
"periodo": {
"inicio": "2026-10-01T00:00:00.000Z",
"fim": "2026-11-01T00:00:00.000Z"
},
"numerosAtivos": 1,
"phoneNumberIds": ["123456789012345"]
}| Campo | O que diz |
|---|---|
capacity | Quantos números a conta pode manter ativos ao mesmo tempo. |
activeNumbers | Quantos números estão ativos agora. É a conta que a capacidade usa. |
status | trial (teste em curso), active (conta contratada), suspended (escrita e envio pausados) ou none (e-mail ainda não confirmado). |
suspendedReason | Quando status é suspended: trial_expired (o teste terminou) ou account_blocked (a Helsen bloqueou a conta). |
trialEndsAt | Quando o teste termina. Fica preenchido depois que a conta é contratada, como registro. |
trialDaysLeft | Os dias que faltam para o teste terminar, já calculados pela API. |
planName | O nome do plano: Teste grátis durante o teste, e o nome da faixa que comporta a capacidade depois. |
periodo | O período corrente, calculado pela API. Mostre-o como veio. |
canConnectNumber | Se a conta pode abrir a conexão de um número novo agora: e-mail confirmado, conta não suspensa e vaga na capacidade. É a mesma decisão que a abertura da conexão aplica, então mostre ou esconda o botão por este campo. |
capacityLeft | Quantos números ainda cabem na capacidade, nunca negativo. Nulo antes de a conta começar o plano. |
capacityNotice | Quando canConnectNumber é false, o texto da recusa, o mesmo que a API devolve ao tentar conectar. Nulo quando pode conectar. |
writesAllowed | false só com a conta suspensa. Ler, desconectar número e revogar chave continuam valendo. |
suspendedNotice | O texto da suspensão, o mesmo das recusas de escrita. Nulo quando a conta não está suspensa. |
pricePerMonth e currency | O valor mensal da faixa de capacidade contratada, em reais. A Helsen cobra pela capacidade de números e por mais nada. Nulos no teste grátis e acima da última faixa (Sob consulta). Nunca é zero. |
contactEmail | O e-mail do comercial da Helsen, para contratar, ampliar a capacidade ou sair da suspensão. |
Quando o seu sistema mostrar uma barra de uso, use activeNumbers e capacity como vieram. Um número aguardando o pagamento do cliente na Meta continua contando, porque a capacidade é de números configurados, e não de números aptos a enviar agora.
Quando a capacidade chega#
Quando activeNumbers chega a capacity, abrir uma sessão de conexão (POST /v1/onboarding/sessions) ou criar um link de conexão (POST /v1/onboarding/links) responde 409 com error: "number_capacity_reached". A recusa vem antes de o cliente final abrir a tela da Meta, porque o código que a Meta entrega no fim da conexão vale 30 segundos, e a Luna não deixa o seu cliente chegar até ali para recusar depois.
409JSON{
"error": "number_capacity_reached",
"message": "Esta conta já tem 1 número ativo, o máximo contratado (1). Para conectar outro, desconecte um número (DELETE /v1/numbers/{id}) ou escreva para contato@lunahia.com.br.",
"capacity": 1,
"activeNumbers": 1
}- Reconectar um número que já conta na capacidade não é recusado: ele não acrescenta nenhum.
- Capacidade menor que o uso nunca desconecta ninguém. Só a próxima conexão é recusada.
- Os dois caminhos para seguir são desconectar um número, ou ampliar a capacidade com o comercial.
O link de conexão não reserva vaga. A checagem acontece quando o link é criado e quando a sessão é aberta, e de novo quando o número é registrado, que é o instante em que ele passa a contar. Se você criar 20 links numa conta com capacidade 5, os cinco primeiros clientes que terminarem ficam com os números; os outros ficam em connecting: o link vira used, mas o número não conta nem envia, e a Luna tenta de novo de tempos em tempos. Se a capacidade aumentar, eles conectam sozinhos; se as tentativas se esgotarem antes, a sessão termina em FAILED. Crie os links na medida em que há vaga em GET /v1/subscription, ou amplie a capacidade antes de mandar os links. Para o seu cliente final nunca ficar nessa espera, conte as vagas antes de entregar cada link: capacityLeft de GET /v1/subscription menos os links de número novo que continuam open em GET /v1/onboarding/links?status=open. Só entregue o link se sobrar vaga; se não sobrar, amplie a capacidade primeiro. Link de reconexão de um número que já existe não ocupa vaga nova.
Desconectar um número#
DELETE /v1/numbers/{id} tira o número da Luna e abre uma vaga na hora. O escopo é numbers:write.
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)- O número passa para
DISCONNECTED, não envia mais e deixa de contar na capacidade a partir daquele instante. - O evento
number.disconnected, comreason: "requested_by_tenant", é entregue aos seus endpoints. Veja Saúde da conta. - Se era o último número da Luna naquela conta de negócio, a Luna também remove a inscrição dela na conta, e a Meta deixa de mandar eventos dela.
- A Luna não desregistra o número na Meta. O número do seu cliente continua funcionando no outro provedor ou no aplicativo do celular dele.
- O histórico fica. As mensagens e as conversas continuam em
GET /v1/messages, e o número continua emGET /v1/numbers, com oexternalIde olabeldele. - Repetir a chamada é seguro: um número já desconectado responde
204de novo, sem novo evento. Se a Meta estiver indisponível, a chamada falha sem marcar nada e pode ser repetida. - A rota continua funcionando com o teste terminado, justamente para liberar vaga.
Voltar a conectar#
Para voltar a usar um número desconectado, conecte-o de novo pelo mesmo caminho de qualquer número: um link de conexão ou uma sessão. Veja Conectar um número. Ele volta a contar na capacidade, e a abertura da sessão é recusada com 409 number_capacity_reached se a conta estiver cheia.
Dar nome a um número#
PATCH /v1/numbers/{id} troca o externalId (o seu identificador para o cliente dono do número) e o label (um nome livre e curto, de 1 a 128 caracteres, para você reconhecer o número). Mande só o que quer mudar: um campo ausente fica como está, e null limpa o campo. Com autoRead: true, a Luna marca como lida, na Meta, cada mensagem que o número receber daqui em diante, sem indicador de digitando, alguns segundos depois de ela chegar; o padrão é false, e o campo aparece em GET /v1/numbers. O escopo é numbers:write, e a resposta é o número inteiro.
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-8841",
"label": "Atendimento Pinheiros"
}'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-8841",
"label": "Atendimento Pinheiros"
}),
});
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-8841",
"label": "Atendimento Pinheiros",
},
timeout=10,
)
print(res.status_code, res.json())Quando o teste termina#
Três dias antes do fim, a Luna manda um e-mail ao responsável pela conta. Com o teste terminado e a conta sem contratação, status vira suspended com suspendedReason: "trial_expired".
Continua funcionando
- Ler os seus dados (
GET), inclusive mensagens, números e este plano. - Receber o que chega e entregar ao seu webhook.
- O número continua conectado na Meta.
- Desconectar um número, para liberar vaga.
Pausa, com `403`
- Enviar mensagens e as demais escritas.
- Abrir uma sessão de conexão ou criar um link.
- Mensagens que já estavam na fila de saída: são recusadas, com o mesmo motivo.
403 com o teste terminadoJSON{
"error": "trial_expired",
"message": "O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."
}Para continuar, escreva para contato@lunahia.com.br. Quando a conta é contratada, a suspensão sai e o envio volta, sem o seu sistema precisar refazer nada. O mesmo corpo de erro, com account_blocked, vale para a conta bloqueada pela Helsen. A lista completa de erros está em Erros.
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/numbers#
Dois campos parecidos e diferentes: throughputLevel é VELOCIDADE, quantas mensagens por segundo a Meta processa; limiteDiarioDeConversas é o LIMITE DE MENSAGENS da Meta, do portfólio empresarial (business portfolio) e não de cada número: conta pessoas únicas a quem a empresa escreve fora da janela de atendimento, nas faixas TIER_250, TIER_2K, TIER_10K, TIER_100K e TIER_UNLIMITED. Um não substitui o outro, e nenhum dos dois conta o que já foi usado.
throughputLevel descreve uma progressão que a Meta sobe sozinha conforme a qualidade do número. Nem todo número segue essa progressão: um número conectado em coexistência tem teto FIXO, que não sobe nunca. Quem diz qual é o caso é tetoDeVazaoPorSegundo, e ele sai na leitura de um número e na saúde dele, não nesta lista.
podeRetentar diz se o estado admite nova tentativa de conexão. A decisão é da plataforma e não sua, porque cada tentativa de registro consome uma cota que a Meta conta por número numa janela de 72 horas. Esgotar essa cota do lado da Meta trava o número até a janela correr.
orientacao traz, em português, o que está acontecendo com a conexão e o que fazer a respeito. Ela é escrita para você repassar ao seu cliente sem reescrever.
externalId é o rótulo que você deu ao seu cliente no link de conexão. Use ?externalId= para listar só os números dele: a comparação é exata e sensível a maiúsculas, e um rótulo sem número devolve lista vazia.
connection é o estado resumido, calculado pela API: status (connected, connecting, action_required ou disconnected), canSend (se enviar vai funcionar agora) e reasons, a lista de motivos com code, message e solution, prontos para você repassar ao seu cliente. É o que você mostra no painel dele em vez de combinar vários campos. ready é o veredito de prontidão: o número está registrado e a inscrição do aplicativo foi confirmada.
Para filtrar, use ?state= (o estado do número), ?ready= e ?canSend= (true ou false). Para percorrer páginas, use ?limit= (de 1 a 100, 50 se omitido) e mande de volta o nextCursor da resposta anterior em ?cursor=; nulo significa o fim. O cursor é opaco: ele carrega posição, não contagem.
GET /v1/numbers/{id}#
tetoDeVazaoPorSegundo é o campo que distingue teto que sobe de teto que não sobe. throughputLevel descreve a progressão que a Meta concede conforme a qualidade do número, e ela sobe com o tempo. Um número conectado em coexistência, que continua funcionando no aplicativo de celular do negócio, tem teto fixo e não entra nessa progressão. Com valor, este campo diz qual é o teto fixo em mensagens por segundo; nulo, a progressão vale e quem a descreve é throughputLevel. O valor vem do que a plataforma observou no tráfego deste número, e não do rótulo que a Meta devolveu.
sincronizacaoDoHistorico conta a importação das conversas anteriores do aparelho, num número conectado em coexistência, e são QUATRO situações e não três. Nulo significa que não há importação para este número. em_curso significa que ela está acontecendo, e sincronizacaoPrazo diz até quando: passado esse instante sem concluir, a plataforma da Meta desconecta o negócio final. concluida significa que terminou, e as conversas antigas já aparecem em GET /v1/messages. recusada significa que o dono do negócio recusou compartilhar no aparelho dele, e aí não vai concluir e pedir de novo não muda isso.
Não leia o percentual sozinho. sincronizacaoProgresso é um rótulo que a plataforma da Meta atribui, e cem por cento NÃO significa sucesso: a recusa chega com o progresso que já havia sido registrado. Quem diz o desfecho é sincronizacaoDoHistorico, e só ele. E ausência não é progresso zero: nulo é não haver importação, e zero é uma importação que começou e ainda não andou.
Quando a Meta recusa o envio por falta de método de pagamento do negócio final, o número fica registrado e sem enviar. Esse não é um erro da plataforma e não há nada a fazer do lado da Helsen: o campo orientacao diz o que falta e onde resolver, em texto pronto para você repassar ao seu cliente. O campo awaitingPaymentSince traz o instante em que a recusa foi vista e é nulo quando não há espera. A Meta não avisa quando o pagamento é regularizado nem oferece consulta: ele só volta a nulo quando um envio seguinte é aceito. Os eventos number.payment_required e number.payment_resolved avisam as duas passagens.
waba traz o estado da conta de negócio do número: restricted e disabled, lidos do último aviso da Meta; credentialExpiresAt e credentialNeverExpires, até quando vale a autorização que o cliente deu à Luna; e paymentMethodOnMeta e currency, a forma de pagamento da conta na Meta (sem ela, a Meta para de entregar mensagens de serviço depois da franquia de 1.000 por número por mês). São da conta, e valem para todos os números dela; os detalhes estão em GET /v1/business-accounts.
connection é o estado resumido da conexão: status, canSend e reasons (code, message e solution de cada motivo). É a mesma conta que decide os eventos number.action_required e number.action_resolved.
subscriptionConfirmedAt é o campo que mais importa aqui. Ele registra quando a inscrição do aplicativo na conta foi confirmada por leitura de volta. Sem essa inscrição nenhum evento chega, e a falha é silenciosa: o número parece perfeito e não recebe nada.
credentialStatus diz se a autorização do cliente continua válida. Quando ela morre, o número precisa ser reconectado.
coexistence e ready são booleanos prontos. coexistence é true quando a Luna já observou tráfego de coexistência neste número (a mesma regra do evento number.connected, e ele pode passar de false para true depois da conexão). ready é true quando o número está registrado e a inscrição foi confirmada, ou seja, quando o envio está liberado: use este campo em vez de combinar state e subscriptionConfirmedAt.
PATCH /v1/numbers/{id}#
externalId é o seu identificador para o cliente dono do número, de 1 a 128 caracteres. É o fio que amarra o número ao seu cliente: ?externalId= em GET /v1/numbers, o evento number.connected e os que vêm depois trazem o mesmo valor. label é um nome livre e curto, de 1 a 128 caracteres, para você reconhecer o número. A Luna não interpreta nenhum dos dois.
Mande só o que quer mudar. Um campo ausente fica como está, e null limpa o campo. O corpo precisa ter pelo menos um dos dois. Repetir o mesmo pedido deixa o mesmo estado.
A resposta é o número inteiro, como em GET /v1/numbers/{id}. Número que não é seu responde 404, igual a número que não existe.
DELETE /v1/numbers/{id}#
O que acontece: o número passa para o estado DISCONNECTED, não envia mais, e o evento number.disconnected, com reason requested_by_tenant, é entregue aos seus endpoints. Se era o último número da Luna naquela conta de negócio, a Luna também remove a inscrição dela na conta, e a Meta deixa de mandar eventos dela.
O que NÃO acontece: a Luna não desregistra o número na Meta. O número do seu cliente continua funcionando no outro provedor ou no aplicativo do celular dele, e continua registrado na Meta. O histórico fica: mensagens e conversas continuam em GET /v1/messages, e o número continua em GET /v1/numbers com o externalId e o label dele.
Para voltar a usar o número, conecte-o de novo com um link de conexão (POST /v1/onboarding/links) ou com POST /v1/onboarding/sessions. Isso conta de novo na capacidade, e é recusado com 409 number_capacity_reached se a conta estiver cheia.
Repetir a chamada é seguro: um número já desconectado responde 204 de novo, sem novo evento. Se a Meta estiver indisponível, a chamada falha sem marcar nada e pode ser repetida.
A rota continua funcionando com o teste grátis terminado, justamente para liberar vaga. Número que não é seu responde 404, igual a número que não existe.