LunaDocs

Loading search...

PortuguêsSign in to the console
On this page

Account and plan

Use with AI

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.

Authentication
API key
Required scope
numbers:read

Query parameters

  • iniciostring (date-time)optional
  • fimstring (date-time)optional

Responses

200Success.
  • planNamestring | nullrequired
    O 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.
  • statusstringrequired
    none: 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: none trial active suspended
  • suspendedReasonstring | nullrequired
    Quando status é suspended: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). Nulo nos outros casos.Values: trial_expired account_blocked
  • capacityinteger | nullrequired
    Quantos números a conta pode manter ativos ao mesmo tempo. Nulo enquanto a conta não começou plano.
  • activeNumbersintegerrequired
    Quantos 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 | nullrequired
    Quando o teste grátis termina. Fica preenchido depois que a conta é contratada, como registro. Nulo se a conta nunca teve teste.
  • trialDaysLeftinteger | nullrequired
    Quantos dias faltam para o teste terminar, calculados pela API (arredondados para cima, mínimo 0). Nulo fora do teste.
  • periodoobjectrequired
  • periodo.iniciostringrequired
  • periodo.fimstringrequired
  • canConnectNumberbooleanrequired
    Se 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 | nullrequired
    Quantos números ainda cabem na capacidade (nunca negativo). Nulo enquanto a conta não começou plano.
  • capacityNoticestring | nullrequired
    Quando 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.
  • writesAllowedbooleanrequired
    Se 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 | nullrequired
    O texto da suspensão, o mesmo das recusas 403 de escrita. Nulo quando a conta não está suspensa.
  • pricePerMonthnumber | nullrequired
    O 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 | nullrequired
    A moeda de pricePerMonth. Nulo quando pricePerMonth é nulo.Values: BRL
  • contactEmailstringrequired
    O e-mail do comercial da Helsen, para contratar, ampliar a capacidade ou sair da suspensão.
  • numerosAtivosintegerrequired
    Quantos 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>required
    Os 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.
Field refused, with the reasonJSON
{
  "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-Authenticate Always Bearer.
Key refusedJSON
{
  "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.
Insufficient scopeJSON
{
  "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"
}
Test key on a route outside test modeJSON
{
  "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-After Seconds to wait before repeating.
Request limitJSON
{
  "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.
UnavailableJSON
{
  "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.

Authentication
API key
Required scope
numbers:read

Responses

200Success.
  • dataarray<object>required
    Os limites, na ordem em que devem aparecer.
  • data[].keystringrequired
    O identificador estável do limite, para o seu código comparar. Novos limites podem aparecer.
  • data[].labelstringrequired
    O nome do limite, em português.
  • data[].valuenumberrequired
    O valor, na unidade de unit.
  • data[].unitstringrequired
    A unidade de value: requests_per_minute, endpoints, seconds, hours, bytes ou messages_per_second.
  • data[].reasonstringrequired
    Por 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-Authenticate Always Bearer.
Key refusedJSON
{
  "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.
Insufficient scopeJSON
{
  "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"
}
Test key on a route outside test modeJSON
{
  "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-After Seconds to wait before repeating.
Request limitJSON
{
  "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.
UnavailableJSON
{
  "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.

Authentication
API key
Required scope
numbers:read

Responses

200Success.
  • readAtstringrequired
    O 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.
  • sourceUrlstringrequired
    A tabela de tarifas da Meta, que é a referência para qualquer valor.
  • aiProvidersUrlstringrequired
    A política própria da Meta para assistentes de IA de uso geral (Provedores de IA).
  • rulesarray<object>required
    As regras, na ordem em que devem aparecer.
  • rules[].keystringrequired
    O identificador estável da regra, para o seu código comparar.
  • rules[].titlestringrequired
  • rules[].textstringrequired
    A 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-Authenticate Always Bearer.
Key refusedJSON
{
  "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.
Insufficient scopeJSON
{
  "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"
}
Test key on a route outside test modeJSON
{
  "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-After Seconds to wait before repeating.
Request limitJSON
{
  "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.
UnavailableJSON
{
  "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.

Authentication
API key
Required scope
numbers:read

Responses

200Success.
  • idstring (uuid)required
  • namestringrequired
  • emailConfirmedbooleanrequired
  • createdAtstringrequired
  • operatorEmailstring | nullrequired
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
  • WWW-Authenticate Always Bearer.
Key refusedJSON
{
  "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.
Insufficient scopeJSON
{
  "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"
}
Test key on a route outside test modeJSON
{
  "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-After Seconds to wait before repeating.
Request limitJSON
{
  "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.
UnavailableJSON
{
  "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.

Authentication
API key
Required scope
session:end

Request body

application/json · required

  • namestringrequired
    O novo nome da conta, de 1 a 120 caracteres: o mesmo limite do cadastro.1 to 120 characters

Responses

200Success.
  • idstring (uuid)required
  • namestringrequired
  • emailConfirmedbooleanrequired
  • createdAtstringrequired
  • operatorEmailstring | 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.
Field refused, with the reasonJSON
{
  "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-Authenticate Always Bearer.
Key refusedJSON
{
  "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.
Insufficient scopeJSON
{
  "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"
}
Test key on a route outside test modeJSON
{
  "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.
Content type not readJSON
{
  "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-After Seconds to wait before repeating.
Request limitJSON
{
  "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.
UnavailableJSON
{
  "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.

Authentication
API key
Required scope
numbers:read

Responses

200Success.
  • attentionarray<object>required
    O que a conta precisa olhar, na ordem em que deve aparecer: o que está parado primeiro, depois o mais antigo.
  • attention[].codestringrequired
    O tipo do aviso, para o seu código comparar.Values: number_action_required number_credential_expiring number_payment_missing account_restricted account_disabled subscription_trial_ending subscription_suspended email_not_confirmed webhook_endpoint_failing webhook_no_endpoint webhook_rejected_pending template_paused template_rejected link_failed
  • attention[].severitystringrequired
    blocking: algo está parado e precisa de ação. warning: algo vai parar ou funciona pela metade. info: vale olhar.Values: blocking warning info
  • attention[].titlestringrequired
    O aviso em poucas palavras, em português.
  • attention[].messagestringrequired
    O que está acontecendo, em português, pronto para mostrar.
  • attention[].solutionstringrequired
    O que fazer a respeito, em português.
  • attention[].resourceobjectrequired
    A que o aviso se refere.
  • attention[].resource.typestringrequired
    Values: number link webhook_endpoint template subscription business_account account
  • attention[].resource.idstringrequired
    O identificador do recurso na Luna. Para account e subscription é o da própria conta.
  • attention[].actionstring | nullrequired
    A 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 | nullrequired
    O endereço da conta no WhatsApp Manager da Meta. Só vem quando action é meta_manager.
  • attention[].sincestringrequired
    Desde quando o aviso vale, em ISO-8601 UTC.
  • checklistarray<object>required
    Os 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[].keystringrequired
    Values: connect_number create_key add_webhook_endpoint send_message
  • checklist[].donebooleanrequired
  • checklist[].doneAtstring | nullrequired
    Quando o passo foi cumprido pela primeira vez. Nulo enquanto não foi.
  • numbersobjectrequired
    Os números da conta por estado de conexão (connection.status). A soma dos quatro estados é total.
  • numbers.totalintegerrequired
  • numbers.byStatusobjectrequired
  • numbers.byStatus.connectedintegerrequired
  • numbers.byStatus.connectingintegerrequired
  • numbers.byStatus.action_requiredintegerrequired
  • numbers.byStatus.disconnectedintegerrequired
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
  • WWW-Authenticate Always Bearer.
Key refusedJSON
{
  "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.
Insufficient scopeJSON
{
  "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"
}
Test key on a route outside test modeJSON
{
  "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-After Seconds to wait before repeating.
Request limitJSON
{
  "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.
UnavailableJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}