Plan and numbers
Luna’s plan defines one thing only: how many numbers your account can keep active at the same time. This guide shows how to read that limit, what to do when it is reached, and how to open a slot.
The free trial#
Every new account starts with a 14-day free trial, counted from the confirmation of the sign-up email, with capacity for 1 number. No manual release is needed: after confirming the email, the account connects the number by itself. Helsen can block an account, and the block stops writes and sending the same way the end of the trial does.
Automatic billing does not exist yet. To subscribe to a plan, increase the capacity or lift the suspension, write to contato@lunahia.com.br. Use of Meta’s platform is paid by the business that owns the number, directly to Meta, and has no part in any of this. See Meta costs.
Read the plan and the usage#
GET /v1/subscription returns the account’s plan and how many numbers are in use, with nothing for your system to calculate. The scope is 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"]
}| Field | What it says |
|---|---|
capacity | How many numbers the account can keep active at the same time. |
activeNumbers | How many numbers are active right now. It is the count the capacity uses. |
status | trial (trial in progress), active (subscribed account), suspended (writes and sending paused) or none (email not yet confirmed). |
suspendedReason | When status is suspended: trial_expired (the trial ended) or account_blocked (Helsen blocked the account). |
trialEndsAt | When the trial ends. It stays filled in after the account is subscribed, as a record. |
trialDaysLeft | The days left until the trial ends, already calculated by the API. |
planName | The plan name: Teste grátis during the trial, and the name of the band that holds the capacity afterwards. |
periodo | The current period, calculated by the API. Show it as it came. |
canConnectNumber | Whether the account can open the connection of a new number now: email confirmed, account not suspended and a free slot in the capacity. It is the same decision the connection opening applies, so show or hide the button by this field. |
capacityLeft | How many numbers still fit in the capacity, never negative. Null before the account starts its plan. |
capacityNotice | When canConnectNumber is false, the refusal text, the same the API returns when you try to connect. Null when it can connect. |
writesAllowed | false only when the account is suspended. Reading, disconnecting a number and revoking a key remain valid. |
suspendedNotice | The suspension text, the same as the write refusals. Null when the account is not suspended. |
pricePerMonth e currency | The monthly value of the contracted capacity band, in reais. Helsen charges for number capacity and nothing else. Null during the free trial and above the last band (Sob consulta, on request). It is never zero. |
contactEmail | Helsen’s sales email, to subscribe, increase the capacity or lift the suspension. |
When your system shows a usage bar, use activeNumbers and capacity as they came. A number waiting for the customer’s payment at Meta still counts, because the capacity is of configured numbers, not of numbers able to send right now.
When the capacity is reached#
When activeNumbers reaches capacity, opening a connection session (POST /v1/onboarding/sessions) or creating a connect link (POST /v1/onboarding/links) answers 409 with error: "number_capacity_reached". The refusal comes before the end customer opens Meta’s screen, because the code Meta hands over at the end of the connection is valid for 30 seconds, and Luna does not let your customer get that far just to refuse afterwards.
409 responseJSON{
"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
}- Reconnecting a number that already counts against the capacity is not refused: it adds none.
- A capacity lower than the usage never disconnects anyone. Only the next connection is refused.
- The two ways forward are to disconnect a number, or to increase the capacity with sales.
A connect link does not reserve a slot. The check runs when the link is created and when the session is opened, and again when the number is registered, which is the moment it starts to count. If you create 20 links on an account with capacity 5, the first five customers to finish keep their numbers; the others stay connecting: the link becomes used, but the number neither counts nor sends, and Luna retries from time to time. If the capacity increases, they connect by themselves; if the retries run out first, the session ends as FAILED. Create links as slots are free in GET /v1/subscription, or increase the capacity before sending the links. So your end customer is never left waiting, count the slots before handing over each link: capacityLeft from GET /v1/subscription minus the new-number links still open in GET /v1/onboarding/links?status=open. Only hand the link over if a slot is left; if none is, increase the capacity first. A reconnection link for a number that already exists takes no new slot.
Disconnect a number#
DELETE /v1/numbers/{id} takes the number off Luna and opens a slot at once. The scope is 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)- The number moves to
DISCONNECTED, no longer sends, and stops counting against the capacity from that instant. - The
number.disconnectedevent, withreason: "requested_by_tenant", is delivered to your endpoints. See Account health. - If it was the last Luna number in that business account, Luna also removes its subscription to the account, and Meta stops sending its events.
- Luna does not deregister the number at Meta. Your customer’s number keeps working with the other provider or in their phone app.
- The history stays. Messages and conversations remain at
GET /v1/messages, and the number stays atGET /v1/numbers, with itsexternalIdandlabel. - Repeating the call is safe: an already disconnected number answers
204again, with no new event. If Meta is unavailable, the call fails without marking anything and can be repeated. - The route keeps working when the trial has ended, precisely to free a slot.
Connect again#
To use a disconnected number again, connect it the same way as any number: a connect link or a session. See Connect a number. It counts against the capacity again, and opening the session is refused with 409 number_capacity_reached if the account is full.
Name a number#
PATCH /v1/numbers/{id} changes the externalId (your identifier for the customer who owns the number) and the label (a free, short name, 1 to 128 characters, so you recognize the number). Send only what you want to change: an absent field stays as it is, and null clears the field. With autoRead: true, Luna marks as read, at Meta, every message the number receives from then on, with no typing indicator, a few seconds after it arrives; the default is false, and the field appears in GET /v1/numbers. The scope is numbers:write, and the response is the whole number.
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())When the trial ends#
Three days before the end, Luna emails the person responsible for the account. With the trial ended and the account not subscribed, status becomes suspended with suspendedReason: "trial_expired".
Keeps working
- Reading your data (
GET), including messages, numbers and this plan. - Receiving what arrives and delivering it to your webhook.
- The number stays connected at Meta.
- Disconnecting a number, to free a slot.
Pauses, with `403`
- Sending messages and the other writes.
- Opening a connection session or creating a link.
- Messages already in the outbound queue: they are refused, with the same reason.
403 response with the trial endedJSON{
"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."
}To continue, write to contato@lunahia.com.br. When the account is subscribed, the suspension is lifted and sending resumes, with nothing for your system to redo. The same error body, with account_blocked, applies to an account blocked by Helsen. The full list of errors is in Errors.
Route details for this guide#
The API reference says how to call each route, in a few lines. What explains the reason for each decision, the edge cases and the warnings is here, in the order of the reference.
GET /v1/numbers#
Two fields that look alike and are not: throughputLevel is SPEED, how many messages per second Meta processes; limiteDiarioDeConversas is Meta's MESSAGING LIMIT, set for the business portfolio and not for each number: it counts unique people the business writes to outside the customer service window, in the tiers TIER_250, TIER_2K, TIER_10K, TIER_100K and TIER_UNLIMITED. Neither replaces the other, and neither one counts what has already been used.
throughputLevel describes a progression Meta raises on its own as the number builds quality. Not every number follows that progression: a number connected through coexistence has a FIXED ceiling that never goes up. The field that tells you which case you are in is tetoDeVazaoPorSegundo, and it comes out when you read one number and its health, not on this list.
podeRetentar tells you whether the state allows another connection attempt. The decision belongs to the platform and not to you, because each registration attempt spends a quota Meta counts per number over a 72 hour window. Exhausting that quota on Meta's side locks the number until the window rolls.
orientacao carries, in Portuguese, what is happening with the connection and what to do about it. It is written for you to pass on to your own customer without rewriting it.
externalId is the label you gave your customer on the connect link. Use ?externalId= to list only that customer's numbers: the comparison is exact and case sensitive, and a label with no number returns an empty list.
connection is the summary state, computed by the API: status (connected, connecting, action_required or disconnected), canSend (whether sending will work now) and reasons, the list of causes with code, message and solution, ready for you to pass on to your own customer. It is what you show on their dashboard instead of combining several fields. ready is the readiness verdict: the number is registered and the app subscription was confirmed.
To filter, use ?state= (the number's state), ?ready= and ?canSend= (true or false). To page through results, use ?limit= (1 to 100, 50 if omitted) and send back the nextCursor of the previous response in ?cursor=; null means the end. The cursor is opaque: it carries position, not a count.
GET /v1/numbers/{id}#
tetoDeVazaoPorSegundo is the field that tells a ceiling that goes up apart from a ceiling that does not. throughputLevel describes the progression Meta grants as the number builds quality, and it rises over time. A number connected through coexistence, which keeps working in the business phone app, has a fixed ceiling and never enters that progression. With a value, this field gives you that fixed ceiling in messages per second; null, the progression applies and throughputLevel is what describes it. The value comes from what the platform observed in this number traffic, and not from the label Meta returned.
sincronizacaoDoHistorico tracks the import of the phone previous conversations on a number connected through coexistence, and there are FOUR situations, not three. Null means there is no import for this number. em_curso means it is running, and sincronizacaoPrazo tells you until when: past that instant without finishing, Meta disconnects the end business. concluida means it finished, and the older conversations already show up in GET /v1/messages. recusada means the business owner declined to share on the phone, so it will not finish and asking again changes nothing.
Do not read the percentage on its own. sincronizacaoProgresso is a label Meta assigns, and one hundred per cent does NOT mean success: a refusal arrives carrying whatever progress had already been recorded. What tells you the outcome is sincronizacaoDoHistorico, and nothing else. And absence is not zero progress: null means there is no import, zero means one started and has not moved yet.
When Meta refuses sending because the end business has no payment method, the number stays registered and sends nothing. That is not a platform error and there is nothing to do on Helsen's side: the orientacao field says what is missing and where it gets resolved, in text ready for you to pass on to your customer. The awaitingPaymentSince field carries the instant the refusal was seen, and is null when there is no wait. Meta does not announce when payment is fixed and offers no lookup: it only goes back to null when a later send is accepted. The number.payment_required and number.payment_resolved events announce both transitions.
waba carries the state of the number's business account: restricted and disabled, read from Meta's last notice; credentialExpiresAt and credentialNeverExpires, until when the authorization the customer gave Luna is valid; and paymentMethodOnMeta and currency, the account's payment method at Meta (without it, Meta stops delivering service messages after the allowance of 1,000 per number per month). They belong to the account and hold for all its numbers; the details are in GET /v1/business-accounts.
connection is the summary state of the connection: status, canSend and reasons (code, message and solution of each cause). It is the same calculation that decides the number.action_required and number.action_resolved events.
subscriptionConfirmedAt is the field that matters most here. It records when the app's subscription to the account was confirmed by reading it back. Without that subscription no event ever arrives, and the failure is silent: the number looks perfect and receives nothing.
credentialStatus tells you whether the customer's authorization is still valid. When it dies, the number has to be reconnected.
coexistence and ready are ready-made booleans. coexistence is true once Luna has observed coexistence traffic on this number (the same rule as the number.connected event, and it can turn from false to true after the connection). ready is true when the number is registered and the subscription is confirmed, that is, when sending is enabled: use this field instead of combining state and subscriptionConfirmedAt.
PATCH /v1/numbers/{id}#
externalId is your identifier for the customer that owns the number, 1 to 128 characters. It is the thread that ties the number to your customer: ?externalId= on GET /v1/numbers, the number.connected event and the ones after it carry the same value. label is a free, short name, 1 to 128 characters, so you can recognize the number. Luna interprets neither.
Send only what you want to change. An absent field stays as it is, and null clears it. The body needs at least one of the two. Repeating the same request leaves the same state.
The response is the whole number, as in GET /v1/numbers/{id}. A number that is not yours answers 404, the same as a number that does not exist.
DELETE /v1/numbers/{id}#
What happens: the number moves to the DISCONNECTED state, stops sending, and the number.disconnected event, with reason requested_by_tenant, is delivered to your endpoints. If it was the last Luna number on that business account, Luna also removes its subscription on the account, and Meta stops sending its events.
What does NOT happen: Luna does not deregister the number at Meta. Your customer's number keeps working on the other provider or on their phone app, and stays registered at Meta. History stays: messages and conversations are still in GET /v1/messages, and the number is still in GET /v1/numbers with its externalId and label.
To use the number again, connect it again with a connect link (POST /v1/onboarding/links) or with POST /v1/onboarding/sessions. That counts toward the capacity again, and is refused with 409 number_capacity_reached if the account is full.
Repeating the call is safe: a number already disconnected answers 204 again, with no new event. If Meta is unavailable, the call fails without marking anything and can be repeated.
The route keeps working with the free trial over, precisely to free a slot. A number that is not yours answers 404, the same as a number that does not exist.