Account and plan
The credential's account, the plan, the number capacity and how many are in use in the period.
Read the plan and the subscription
GET/v1/subscription
The account's plan (free trial or contracted), the number capacity and how many are in use, and what Helsen charges for the period: the capacity of active numbers, and nothing beyond that.
Query parameters
iniciostring (date-time)optionalfimstring (date-time)optional
Responses
200Success.
planNamestring | nullrequiredO nome do plano: Teste grátis enquanto a conta está no teste, e o nome da faixa que comporta a capacidade depois que ela é contratada (Avulso, Starter, Growth, Scale, ou Sob consulta acima de 60). Nulo enquanto a conta não começou plano.statusstringrequirednone: a conta ainda não começou plano (o e-mail não foi confirmado). trial: teste grátis em curso. active: conta contratada. suspended: escrita e envio recusados; suspendedReason diz por quê.Values:nonetrialactivesuspendedsuspendedReasonstring | nullrequiredQuando status é suspended: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). Nulo nos outros casos.Values:trial_expiredaccount_blockedcapacityinteger | nullrequiredQuantos números a conta pode manter ativos ao mesmo tempo. Nulo enquanto a conta não começou plano.activeNumbersintegerrequiredQuantos números estão ativos agora. É a contagem que a capacidade usa; a da assinatura do mês é numerosAtivos, que soma os que ficaram ativos em algum momento do período.trialEndsAtstring | nullrequiredQuando o teste grátis termina. Fica preenchido depois que a conta é contratada, como registro. Nulo se a conta nunca teve teste.trialDaysLeftinteger | nullrequiredQuantos dias faltam para o teste terminar, calculados pela API (arredondados para cima, mínimo 0). Nulo fora do teste.periodoobjectrequiredperiodo.iniciostringrequiredperiodo.fimstringrequiredcanConnectNumberbooleanrequiredSe esta conta pode abrir a conexão de um número novo agora: o e-mail está confirmado, a conta não está suspensa e ainda há vaga na capacidade. É a mesma decisão que a abertura da conexão e a criação do link de conexão aplicam, então a tela pode mostrar ou esconder o botão sem comparar nada.capacityLeftinteger | nullrequiredQuantos números ainda cabem na capacidade (nunca negativo). Nulo enquanto a conta não começou plano.capacityNoticestring | nullrequiredQuando canConnectNumber é false, o texto da recusa, o mesmo que a API devolve ao tentar conectar: e-mail por confirmar, conta suspensa ou capacidade cheia. Nulo quando pode conectar.writesAllowedbooleanrequiredSe a conta pode fazer alterações agora. É false só com a conta suspensa, e então suspendedNotice diz por quê. Ler, desconectar número e revogar chave continuam valendo.suspendedNoticestring | nullrequiredO texto da suspensão, o mesmo das recusas 403 de escrita. Nulo quando a conta não está suspensa.pricePerMonthnumber | nullrequiredO valor mensal da faixa de capacidade contratada, em reais, que a Helsen cobra pela capacidade de números e por mais nada. Nulo no teste grátis, enquanto a conta não começou plano e acima da última faixa (Sob consulta).currencystring | nullrequiredA moeda de pricePerMonth. Nulo quando pricePerMonth é nulo.Values:BRLcontactEmailstringrequiredO e-mail do comercial da Helsen, para contratar, ampliar a capacidade ou sair da suspensão.numerosAtivosintegerrequiredQuantos números distintos estiveram ativos em algum momento do período consultado (periodo): a contagem que a assinatura do mês usa. Não é o mesmo que activeNumbers: este é o acumulado do período e inclui um número que já foi desconectado depois de ter sido ativo nele; activeNumbers é quantos estão ativos agora e é o que a capacidade compara.phoneNumberIdsarray<string>requiredOs ids da Meta (metaPhoneNumberId) dos números que entraram em numerosAtivos, para você conferir a contagem. É uma lista de identificadores, sem contagem de mensagens.
400The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.
{
"error": "invalid_request",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisição inválida.",
"campos": [
{
"campo": "text.body",
"motivo": "Não pode ficar vazio."
}
]
}401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
WWW-AuthenticateAlways Bearer.
{
"error": "unauthorized",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Credencial ausente ou inválida."
}403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
{
"error": "forbidden",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
"requiredScope": "numbers:read"
}{
"error": "test_key_not_allowed",
"docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
"message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}429Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.
Retry-AfterSeconds to wait before repeating.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
{
"error": "unavailable",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}Read the platform's technical limits
GET/v1/limits
The ceilings the API applies, each with its value, unit and reason. They are the same for every customer and do not depend on the plan: they exist for infrastructure capacity or because Meta imposes them. They are not a count of your usage and do not enter billing.
Responses
200Success.
dataarray<object>requiredOs limites, na ordem em que devem aparecer.data[].keystringrequiredO identificador estável do limite, para o seu código comparar. Novos limites podem aparecer.data[].labelstringrequiredO nome do limite, em português.data[].valuenumberrequiredO valor, na unidade de unit.data[].unitstringrequiredA unidade de value: requests_per_minute, endpoints, seconds, hours, bytes ou messages_per_second.data[].reasonstringrequiredPor que o limite existe, em português. É sempre capacidade ou regra da Meta, nunca preço.
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
WWW-AuthenticateAlways Bearer.
{
"error": "unauthorized",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Credencial ausente ou inválida."
}403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
{
"error": "forbidden",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
"requiredScope": "numbers:read"
}{
"error": "test_key_not_allowed",
"docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
"message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}429Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.
Retry-AfterSeconds to wait before repeating.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
{
"error": "unavailable",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}Read Meta's pricing rules
GET/v1/meta-pricing
The rules by which Meta charges for the use of WhatsApp to the business that owns the number, and the day Luna read them. It carries no monetary values: the rate table stays at Meta. Luna charges none of this.
Responses
200Success.
readAtstringrequiredO dia em que as regras foram lidas na página de preços da Meta (AAAA-MM-DD). Mostre-o junto das regras: é o que diz o quão fresca é a informação.sourceUrlstringrequiredA tabela de tarifas da Meta, que é a referência para qualquer valor.aiProvidersUrlstringrequiredA política própria da Meta para assistentes de IA de uso geral (Provedores de IA).rulesarray<object>requiredAs regras, na ordem em que devem aparecer.rules[].keystringrequiredO identificador estável da regra, para o seu código comparar.rules[].titlestringrequiredrules[].textstringrequiredA regra, em português. Não traz valor em moeda.
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
WWW-AuthenticateAlways Bearer.
{
"error": "unauthorized",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Credencial ausente ou inválida."
}403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
{
"error": "forbidden",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
"requiredScope": "numbers:read"
}{
"error": "test_key_not_allowed",
"docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
"message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}429Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.
Retry-AfterSeconds to wait before repeating.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
{
"error": "unavailable",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}Read your own account
GET/v1/account
Returns the account behind the credential presented: identifier, name, whether the email has been confirmed, and when the account was created.
Responses
200Success.
idstring (uuid)requirednamestringrequiredemailConfirmedbooleanrequiredcreatedAtstringrequiredoperatorEmailstring | nullrequired
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
WWW-AuthenticateAlways Bearer.
{
"error": "unauthorized",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Credencial ausente ou inválida."
}403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
{
"error": "forbidden",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
"requiredScope": "numbers:read"
}{
"error": "test_key_not_allowed",
"docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
"message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}429Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.
Retry-AfterSeconds to wait before repeating.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
{
"error": "unavailable",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}Rename the account
PATCH/v1/account
Changes the account name, the same one GET /v1/account returns. Returns the account with the new name. Only the console session does this.
Request body
namestringrequiredO novo nome da conta, de 1 a 120 caracteres: o mesmo limite do cadastro.1 to 120 characters
Responses
200Success.
idstring (uuid)requirednamestringrequiredemailConfirmedbooleanrequiredcreatedAtstringrequiredoperatorEmailstring | nullrequired
400The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.
{
"error": "invalid_request",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisição inválida.",
"campos": [
{
"campo": "text.body",
"motivo": "Não pode ficar vazio."
}
]
}401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
WWW-AuthenticateAlways Bearer.
{
"error": "unauthorized",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Credencial ausente ou inválida."
}403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
{
"error": "forbidden",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
"requiredScope": "numbers:read"
}{
"error": "test_key_not_allowed",
"docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
"message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}415The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.
{
"error": "unsupported_media_type",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Envie o corpo como application/json."
}429Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.
Retry-AfterSeconds to wait before repeating.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
{
"error": "unavailable",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}See the account summary
GET/v1/account/overview
What the account needs to look at now (alerts, most serious first), the four first steps, and the numbers by connection state. Everything is decided by the API, so a home screen has nothing to calculate.
Responses
200Success.
attentionarray<object>requiredO que a conta precisa olhar, na ordem em que deve aparecer: o que está parado primeiro, depois o mais antigo.attention[].codestringrequiredO tipo do aviso, para o seu código comparar.Values:number_action_requirednumber_credential_expiringnumber_payment_missingaccount_restrictedaccount_disabledsubscription_trial_endingsubscription_suspendedemail_not_confirmedwebhook_endpoint_failingwebhook_no_endpointwebhook_rejected_pendingtemplate_pausedtemplate_rejectedlink_failedattention[].severitystringrequiredblocking: algo está parado e precisa de ação. warning: algo vai parar ou funciona pela metade. info: vale olhar.Values:blockingwarninginfoattention[].titlestringrequiredO aviso em poucas palavras, em português.attention[].messagestringrequiredO que está acontecendo, em português, pronto para mostrar.attention[].solutionstringrequiredO que fazer a respeito, em português.attention[].resourceobjectrequiredA que o aviso se refere.attention[].resource.typestringrequiredValues:numberlinkwebhook_endpointtemplatesubscriptionbusiness_accountaccountattention[].resource.idstringrequiredO identificador do recurso na Luna. Para account e subscription é o da própria conta.attention[].actionstring | nullrequiredA ação que resolve o aviso, quando há: send_pin, reconnect, reconnect_link, meta_manager, wait, contact_helsen, confirm_email, add_webhook_endpoint, review_webhook_endpoint, requeue_webhook_events, edit_template ou create_link. Novos valores podem aparecer.attention[].actionUrlstring | nullrequiredO endereço da conta no WhatsApp Manager da Meta. Só vem quando action é meta_manager.attention[].sincestringrequiredDesde quando o aviso vale, em ISO-8601 UTC.checklistarray<object>requiredOs quatro primeiros passos, sempre nesta ordem: connect_number (há um número conectado), create_key (há uma chave de integração não revogada), add_webhook_endpoint (há um endereço de webhook) e send_message (já saiu uma mensagem).checklist[].keystringrequiredValues:connect_numbercreate_keyadd_webhook_endpointsend_messagechecklist[].donebooleanrequiredchecklist[].doneAtstring | nullrequiredQuando o passo foi cumprido pela primeira vez. Nulo enquanto não foi.numbersobjectrequiredOs números da conta por estado de conexão (connection.status). A soma dos quatro estados é total.numbers.totalintegerrequirednumbers.byStatusobjectrequirednumbers.byStatus.connectedintegerrequirednumbers.byStatus.connectingintegerrequirednumbers.byStatus.action_requiredintegerrequirednumbers.byStatus.disconnectedintegerrequired
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
WWW-AuthenticateAlways Bearer.
{
"error": "unauthorized",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Credencial ausente ou inválida."
}403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
{
"error": "forbidden",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
"requiredScope": "numbers:read"
}{
"error": "test_key_not_allowed",
"docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
"message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}429Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.
Retry-AfterSeconds to wait before repeating.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
{
"error": "unavailable",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}