Phone numbers
The connected numbers: connect, read state, quality and throughput, edit and disconnect.
Migrating a number that is already on another provider's API is a supported path, and it needs no new number and loses no existing one. A number already registered on another provider's Cloud API almost always has two step verification configured there, and Meta requires the existing PIN to register it again: there is no endpoint to read or to turn that PIN off, so it has to come from the end business. Give the PIN at POST /v1/numbers/{id}/pin, or ask the end business to turn two step verification off in its WhatsApp Manager. The other prerequisites are on its side too: it has to own the WhatsApp Business account and have the number released by the previous provider.
A number that today exists only in the WhatsApp Business App, the phone application, is the other case, and Meta calls it coexistence. It has never been through any API. The connection starts from the same Meta window, and the option only shows up once the end business account is enabled for it on Meta's side and the app on the device is version 2.24.17 or later.
Connected this way, the number keeps working in the phone application, and the earlier conversations on the device are imported into the platform: they show up in GET /v1/messages next to the new ones. The import has a deadline to finish, and what tells you where it stands is GET /v1/numbers/{id}, in the fields sincronizacaoDoHistorico and sincronizacaoPrazo. The same resource carries tetoDeVazaoPorSegundo, which is the fixed sending speed ceiling of a number in coexistence and does not go up over time. And what the business owner answers from the phone application arrives too, in the recipient's conversation.
Read the business profile
GET/v1/numbers/{id}/profile
The profile the contact sees on WhatsApp: about text, address, description, email, websites, vertical and the picture. It does not work on a number in coexistence.
Path parameters
idstringrequiredO identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem.1 to 64 characters · /^[A-Za-z0-9_-]+$/
Responses
200Success.
aboutstring | nullrequiredO recado curto do perfil. Nulo quando não há.addressstring | nullrequiredO endereço do negócio.descriptionstring | nullrequiredA descrição do negócio.emailstring | nullrequiredO e-mail de contato.websitesarray<string>requiredOs sites do negócio. Lista vazia quando não há.verticalstring | nullrequiredO ramo de atividade, como a Meta o devolve. Texto da Meta, sem lista fechada aqui.profilePictureUrlstring | nullrequiredO endereço da foto do perfil. É da Meta e pode expirar: baixe o arquivo se precisar guardá-lo.
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."
}404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
{
"error": "not_found",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Recurso não encontrado."
}409The request is well formed, but the resource state does not allow it. The error field says which case it is.
{
"error": "not_available_in_coexistence",
"docsUrl": "https://lunahia.com.br/docs/numero-na-meta",
"message": "Este número está conectado em coexistência, e a Meta não aceita esta operação por API nesse caso. Faça a mudança no aplicativo WhatsApp Business do celular do negócio."
}{
"error": "number_disconnected",
"docsUrl": "https://lunahia.com.br/docs/conectar-numero",
"message": "Este número foi desconectado da Luna e não envia mais. O histórico foi preservado. Para voltar a usá-lo, conecte-o de novo com um link de conexão (POST /v1/onboarding/links)."
}422The request is well formed and Luna passed it on, and Meta refused it. The meta field carries what happened, what to do and its original error. Repeating the same request repeats the refusal.
{
"error": "meta_rejected",
"docsUrl": "https://lunahia.com.br/docs/numero-na-meta",
"message": "A Meta recusou esta operação. O campo meta traz o que aconteceu, o que fazer e o erro original dela.",
"meta": {
"codigo": 131030,
"categoria": "nao_entregavel",
"mensagem": "A Meta recusou o pedido.",
"acaoRecomendada": "Confira os campos enviados e tente de novo.",
"original": {
"error": {
"message": "Invalid parameter",
"type": "OAuthException",
"code": 131030,
"fbtrace_id": "AbCdEfGhIjK"
}
}
}
}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."
}{
"error": "management_busy",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "As operações de gestão desta conexão atingiram o limite momentâneo. 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."
}Change the business profile
PATCH/v1/numbers/{id}/profile
Changes the fields you send and leaves the others as they are. With displayName, it requests the display name change and answers 202: the name stays under review at Meta. It does not work on a number in coexistence.
Path parameters
idstringrequiredO identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem.1 to 64 characters · /^[A-Za-z0-9_-]+$/
Request body
aboutstringoptionalO recado curto. Até 139 caracteres.1 to 139 charactersaddressstringoptionalO endereço. Até 256 caracteres.1 to 256 charactersdescriptionstringoptionalA descrição. Até 512 caracteres.1 to 512 charactersemailstringoptionalO e-mail de contato. Até 128 caracteres.1 to 128 characterswebsitesarray<string (uri)>optionalAté dois sites. A lista inteira substitui a que existe.up to 2 itemsverticalstringoptionalO ramo de atividade, no vocabulário da Meta.1 to 64 charactersdisplayNamestringoptionalPede à Meta a mudança do nome de exibição (o nome que o contato vê no topo da conversa). A resposta é 202: o pedido está em revisão e displayNameStatus passa a pending_review. A Meta aceita até 10 mudanças a cada 30 dias, e é ela quem julga o nome. O evento number.display_name_reviewed avisa o resultado. Um nome aprovado só passa a valer depois que o número é registrado de novo.1 to 512 charactersprofilePictureHandlestringoptionalO handle de uma foto que você subiu pelo envio resumível da Meta. O mesmo handle que POST /v1/template-assets devolve serve de foto do perfil, o que está a confirmar na doc da Meta.1 to 1024 characters
Responses
200Success.
updatedFieldsarray<string>requiredOs campos que a Meta aceitou trocar, pelos nomes que você mandou.
202Accepted: the request was recorded and will be processed.
updatedFieldsarray<string>requiredOs campos que a Meta aceitou trocar, pelos nomes que você mandou.displayNameStatusstringrequiredO nome foi pedido e está em revisão na Meta. O resultado chega no evento number.display_name_reviewed.Values:pending_reviewpendingDisplayNamestringrequiredO nome que você pediu.
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": "trial_expired",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"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."
}{
"error": "account_blocked",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. 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 saber o motivo e resolver, escreva para contato@lunahia.com.br."
}{
"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."
}404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
{
"error": "not_found",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Recurso não encontrado."
}409The request is well formed, but the resource state does not allow it. The error field says which case it is.
{
"error": "not_available_in_coexistence",
"docsUrl": "https://lunahia.com.br/docs/numero-na-meta",
"message": "Este número está conectado em coexistência, e a Meta não aceita esta operação por API nesse caso. Faça a mudança no aplicativo WhatsApp Business do celular do negócio."
}{
"error": "number_disconnected",
"docsUrl": "https://lunahia.com.br/docs/conectar-numero",
"message": "Este número foi desconectado da Luna e não envia mais. O histórico foi preservado. Para voltar a usá-lo, conecte-o de novo com um link de conexão (POST /v1/onboarding/links)."
}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."
}422The request is well formed and Luna passed it on, and Meta refused it. The meta field carries what happened, what to do and its original error. Repeating the same request repeats the refusal.
{
"error": "meta_rejected",
"docsUrl": "https://lunahia.com.br/docs/numero-na-meta",
"message": "A Meta recusou esta operação. O campo meta traz o que aconteceu, o que fazer e o erro original dela.",
"meta": {
"codigo": 131030,
"categoria": "nao_entregavel",
"mensagem": "A Meta recusou o pedido.",
"acaoRecomendada": "Confira os campos enviados e tente de novo.",
"original": {
"error": {
"message": "Invalid parameter",
"type": "OAuthException",
"code": 131030,
"fbtrace_id": "AbCdEfGhIjK"
}
}
}
}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."
}{
"error": "management_busy",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "As operações de gestão desta conexão atingiram o limite momentâneo. 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."
}List blocked users
GET/v1/numbers/{id}/blocked-users
Who this number has blocked, in pages. The cursor is Meta's, and its shape does not change.
Path parameters
idstringrequiredO identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem.1 to 64 characters · /^[A-Za-z0-9_-]+$/
Query parameters
limitintegeroptionalQuantos por página, de 1 a 100.minimum 1 · maximum 100cursorstringoptionalO nextCursor da página anterior.1 to 512 characters
Responses
200Success.
dataarray<object>requiredOs usuários bloqueados nesta página.data[].waIdstring | nullrequiredO telefone do usuário bloqueado.data[].userIdstring | nullrequiredO BSUID do usuário bloqueado.nextCursorstring | nullrequiredO cursor da próxima página, como a Meta o deu. Nulo quando acabou.
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."
}404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
{
"error": "not_found",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Recurso não encontrado."
}409The request is well formed, but the resource state does not allow it. The error field says which case it is.
{
"error": "number_disconnected",
"docsUrl": "https://lunahia.com.br/docs/conectar-numero",
"message": "Este número foi desconectado da Luna e não envia mais. O histórico foi preservado. Para voltar a usá-lo, conecte-o de novo com um link de conexão (POST /v1/onboarding/links)."
}422The request is well formed and Luna passed it on, and Meta refused it. The meta field carries what happened, what to do and its original error. Repeating the same request repeats the refusal.
{
"error": "meta_rejected",
"docsUrl": "https://lunahia.com.br/docs/numero-na-meta",
"message": "A Meta recusou esta operação. O campo meta traz o que aconteceu, o que fazer e o erro original dela.",
"meta": {
"codigo": 131030,
"categoria": "nao_entregavel",
"mensagem": "A Meta recusou o pedido.",
"acaoRecomendada": "Confira os campos enviados e tente de novo.",
"original": {
"error": {
"message": "Invalid parameter",
"type": "OAuthException",
"code": 131030,
"fbtrace_id": "AbCdEfGhIjK"
}
}
}
}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."
}{
"error": "management_busy",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "As operações de gestão desta conexão atingiram o limite momentâneo. 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."
}Block users
POST/v1/numbers/{id}/blocked-users
Blocks people who wrote to the number in the last 24 hours. Each user is a phone number or a BSUID, and the response separates the ones Meta accepted from the ones it refused, with the reason.
Path parameters
idstringrequiredO identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem.1 to 64 characters · /^[A-Za-z0-9_-]+$/
Request body
usersarray<string>requiredOs usuários a bloquear, de um a cinquenta.1 to 50 items
Responses
200Success.
donearray<object>requiredOs usuários que a Meta aceitou bloquear ou desbloquear.done[].inputstring | nullrequiredO que você pediu, como a Meta o devolveu.done[].waIdstring | nullrequiredO telefone do usuário na Meta, quando ela o devolve.done[].userIdstring | nullrequiredO BSUID do usuário, quando a Meta o devolve.done[].reasonsarray<string>requiredSó em failed: o motivo que a Meta deu. Texto dela.failedarray<object>requiredOs que a Meta recusou, cada um com o motivo dela.failed[].inputstring | nullrequiredO que você pediu, como a Meta o devolveu.failed[].waIdstring | nullrequiredO telefone do usuário na Meta, quando ela o devolve.failed[].userIdstring | nullrequiredO BSUID do usuário, quando a Meta o devolve.failed[].reasonsarray<string>requiredSó em failed: o motivo que a Meta deu. Texto dela.
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": "trial_expired",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"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."
}{
"error": "account_blocked",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. 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 saber o motivo e resolver, escreva para contato@lunahia.com.br."
}{
"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."
}404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
{
"error": "not_found",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Recurso não encontrado."
}409The request is well formed, but the resource state does not allow it. The error field says which case it is.
{
"error": "number_disconnected",
"docsUrl": "https://lunahia.com.br/docs/conectar-numero",
"message": "Este número foi desconectado da Luna e não envia mais. O histórico foi preservado. Para voltar a usá-lo, conecte-o de novo com um link de conexão (POST /v1/onboarding/links)."
}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."
}422The request is well formed and Luna passed it on, and Meta refused it. The meta field carries what happened, what to do and its original error. Repeating the same request repeats the refusal.
{
"error": "meta_rejected",
"docsUrl": "https://lunahia.com.br/docs/numero-na-meta",
"message": "A Meta recusou esta operação. O campo meta traz o que aconteceu, o que fazer e o erro original dela.",
"meta": {
"codigo": 131030,
"categoria": "nao_entregavel",
"mensagem": "A Meta recusou o pedido.",
"acaoRecomendada": "Confira os campos enviados e tente de novo.",
"original": {
"error": {
"message": "Invalid parameter",
"type": "OAuthException",
"code": 131030,
"fbtrace_id": "AbCdEfGhIjK"
}
}
}
}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."
}{
"error": "management_busy",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "As operações de gestão desta conexão atingiram o limite momentâneo. 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."
}Unblock a user
DELETE/v1/numbers/{id}/blocked-users/{user}
Unblocks a user, by the phone number or the BSUID in the path. It stays open on a suspended account: unblocking is never the problem.
Path parameters
idstringrequiredO identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem.1 to 64 characters · /^[A-Za-z0-9_-]+$/userstringrequiredO telefone (só dígitos) ou o BSUID do usuário.1 to 160 characters · /^[A-Za-z0-9.]+$/
Responses
200Success.
donearray<object>requiredOs usuários que a Meta aceitou bloquear ou desbloquear.done[].inputstring | nullrequiredO que você pediu, como a Meta o devolveu.done[].waIdstring | nullrequiredO telefone do usuário na Meta, quando ela o devolve.done[].userIdstring | nullrequiredO BSUID do usuário, quando a Meta o devolve.done[].reasonsarray<string>requiredSó em failed: o motivo que a Meta deu. Texto dela.failedarray<object>requiredOs que a Meta recusou, cada um com o motivo dela.failed[].inputstring | nullrequiredO que você pediu, como a Meta o devolveu.failed[].waIdstring | nullrequiredO telefone do usuário na Meta, quando ela o devolve.failed[].userIdstring | nullrequiredO BSUID do usuário, quando a Meta o devolve.failed[].reasonsarray<string>requiredSó em failed: o motivo que a Meta deu. Texto dela.
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."
}404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
{
"error": "not_found",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Recurso não encontrado."
}409The request is well formed, but the resource state does not allow it. The error field says which case it is.
{
"error": "number_disconnected",
"docsUrl": "https://lunahia.com.br/docs/conectar-numero",
"message": "Este número foi desconectado da Luna e não envia mais. O histórico foi preservado. Para voltar a usá-lo, conecte-o de novo com um link de conexão (POST /v1/onboarding/links)."
}422The request is well formed and Luna passed it on, and Meta refused it. The meta field carries what happened, what to do and its original error. Repeating the same request repeats the refusal.
{
"error": "meta_rejected",
"docsUrl": "https://lunahia.com.br/docs/numero-na-meta",
"message": "A Meta recusou esta operação. O campo meta traz o que aconteceu, o que fazer e o erro original dela.",
"meta": {
"codigo": 131030,
"categoria": "nao_entregavel",
"mensagem": "A Meta recusou o pedido.",
"acaoRecomendada": "Confira os campos enviados e tente de novo.",
"original": {
"error": {
"message": "Invalid parameter",
"type": "OAuthException",
"code": 131030,
"fbtrace_id": "AbCdEfGhIjK"
}
}
}
}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."
}{
"error": "management_busy",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "As operações de gestão desta conexão atingiram o limite momentâneo. 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."
}List the QR codes
GET/v1/numbers/{id}/qr-codes
The codes that exist on this number, with each one's short link.
Path parameters
idstringrequiredO identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem.1 to 64 characters · /^[A-Za-z0-9_-]+$/
Responses
200Success.
dataarray<object>requiredOs códigos do número.data[].codestringrequiredO código do QR, que vai no caminho de DELETE.data[].prefilledMessagestring | nullrequiredA mensagem que já vem escrita quando o contato abre a conversa.data[].linkstring | nullrequiredO link curto (wa.me) que abre a mesma conversa.data[].imageUrlstring | nullrequiredO endereço da imagem do QR, quando você pediu imageFormat. É da Meta e pode expirar: baixe o arquivo.
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."
}404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
{
"error": "not_found",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Recurso não encontrado."
}409The request is well formed, but the resource state does not allow it. The error field says which case it is.
{
"error": "number_disconnected",
"docsUrl": "https://lunahia.com.br/docs/conectar-numero",
"message": "Este número foi desconectado da Luna e não envia mais. O histórico foi preservado. Para voltar a usá-lo, conecte-o de novo com um link de conexão (POST /v1/onboarding/links)."
}422The request is well formed and Luna passed it on, and Meta refused it. The meta field carries what happened, what to do and its original error. Repeating the same request repeats the refusal.
{
"error": "meta_rejected",
"docsUrl": "https://lunahia.com.br/docs/numero-na-meta",
"message": "A Meta recusou esta operação. O campo meta traz o que aconteceu, o que fazer e o erro original dela.",
"meta": {
"codigo": 131030,
"categoria": "nao_entregavel",
"mensagem": "A Meta recusou o pedido.",
"acaoRecomendada": "Confira os campos enviados e tente de novo.",
"original": {
"error": {
"message": "Invalid parameter",
"type": "OAuthException",
"code": 131030,
"fbtrace_id": "AbCdEfGhIjK"
}
}
}
}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."
}{
"error": "management_busy",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "As operações de gestão desta conexão atingiram o limite momentâneo. 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."
}Create a QR code and a short link
POST/v1/numbers/{id}/qr-codes
Creates a code that opens a conversation with the number, with the message already written. It returns the code, the short link and, if you asked for it, the address of the image.
Path parameters
idstringrequiredO identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem.1 to 64 characters · /^[A-Za-z0-9_-]+$/
Request body
prefilledMessagestringrequiredA mensagem que já vem escrita. Até 140 caracteres, o limite da Meta, que está a confirmar na doc dela.1 to 140 charactersimageFormatstringoptionalPeça a imagem do QR em PNG ou SVG. Sem isto, só o código e o link voltam.Values:PNGSVG
Responses
201Created.
codestringrequiredO código do QR, que vai no caminho de DELETE.prefilledMessagestring | nullrequiredA mensagem que já vem escrita quando o contato abre a conversa.linkstring | nullrequiredO link curto (wa.me) que abre a mesma conversa.imageUrlstring | nullrequiredO endereço da imagem do QR, quando você pediu imageFormat. É da Meta e pode expirar: baixe o arquivo.
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": "trial_expired",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"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."
}{
"error": "account_blocked",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. 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 saber o motivo e resolver, escreva para contato@lunahia.com.br."
}{
"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."
}404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
{
"error": "not_found",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Recurso não encontrado."
}409The request is well formed, but the resource state does not allow it. The error field says which case it is.
{
"error": "number_disconnected",
"docsUrl": "https://lunahia.com.br/docs/conectar-numero",
"message": "Este número foi desconectado da Luna e não envia mais. O histórico foi preservado. Para voltar a usá-lo, conecte-o de novo com um link de conexão (POST /v1/onboarding/links)."
}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."
}422The request is well formed and Luna passed it on, and Meta refused it. The meta field carries what happened, what to do and its original error. Repeating the same request repeats the refusal.
{
"error": "meta_rejected",
"docsUrl": "https://lunahia.com.br/docs/numero-na-meta",
"message": "A Meta recusou esta operação. O campo meta traz o que aconteceu, o que fazer e o erro original dela.",
"meta": {
"codigo": 131030,
"categoria": "nao_entregavel",
"mensagem": "A Meta recusou o pedido.",
"acaoRecomendada": "Confira os campos enviados e tente de novo.",
"original": {
"error": {
"message": "Invalid parameter",
"type": "OAuthException",
"code": 131030,
"fbtrace_id": "AbCdEfGhIjK"
}
}
}
}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."
}{
"error": "management_busy",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "As operações de gestão desta conexão atingiram o limite momentâneo. 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."
}Delete a QR code
DELETE/v1/numbers/{id}/qr-codes/{code}
Deletes the code and the short link: whoever still has the QR printed stops opening the conversation. It stays open on a suspended account.
Path parameters
idstringrequiredO identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem.1 to 64 characters · /^[A-Za-z0-9_-]+$/codestringrequiredO código do QR, como a criação o devolveu.1 to 64 characters · /^[A-Za-z0-9_-]+$/
Responses
204No content: the operation was done and the response has no body.
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."
}404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
{
"error": "not_found",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Recurso não encontrado."
}409The request is well formed, but the resource state does not allow it. The error field says which case it is.
{
"error": "number_disconnected",
"docsUrl": "https://lunahia.com.br/docs/conectar-numero",
"message": "Este número foi desconectado da Luna e não envia mais. O histórico foi preservado. Para voltar a usá-lo, conecte-o de novo com um link de conexão (POST /v1/onboarding/links)."
}422The request is well formed and Luna passed it on, and Meta refused it. The meta field carries what happened, what to do and its original error. Repeating the same request repeats the refusal.
{
"error": "meta_rejected",
"docsUrl": "https://lunahia.com.br/docs/numero-na-meta",
"message": "A Meta recusou esta operação. O campo meta traz o que aconteceu, o que fazer e o erro original dela.",
"meta": {
"codigo": 131030,
"categoria": "nao_entregavel",
"mensagem": "A Meta recusou o pedido.",
"acaoRecomendada": "Confira os campos enviados e tente de novo.",
"original": {
"error": {
"message": "Invalid parameter",
"type": "OAuthException",
"code": 131030,
"fbtrace_id": "AbCdEfGhIjK"
}
}
}
}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."
}{
"error": "management_busy",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "As operações de gestão desta conexão atingiram o limite momentâneo. 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."
}Open a connection session
POST/v1/onboarding/sessions
Creates the session that Meta's connection flow fills in, and returns the sessionId and the csrfState.
Responses
201Created.
sessionIdstring (uuid)requiredstatestringrequiredconfigIdstringrequiredsdkVersionstringrequiredA versão da Graph API com que o seu código deve iniciar o SDK do Facebook (FB.init) e abrir a janela de conexão da Meta. A Luna a escolhe e a atualiza, então não a copie para o seu código.csrfStatestringrequiredexpiresAtstringrequired
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": "connection_not_released",
"docsUrl": "https://lunahia.com.br/docs/conectar-numero",
"message": "Esta conta ainda não pode conectar um número: falta confirmar o e-mail do cadastro. Abra o link que enviamos para esse e-mail e tente de novo. A lista faltando mostra o que ainda não foi cumprido.",
"faltando": [
"email_confirmado"
]
}{
"error": "trial_expired",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"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."
}{
"error": "account_blocked",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. 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 saber o motivo e resolver, escreva para contato@lunahia.com.br."
}{
"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."
}409The request is well formed, but the resource state does not allow it. The error field says which case it is.
{
"error": "number_capacity_reached",
"message": "Esta conta já tem 20 números ativos, o máximo contratado (20). Para conectar outro, desconecte um número (DELETE /v1/numbers/{id}) ou escreva para contato@lunahia.com.br.",
"capacity": 20,
"activeNumbers": 20
}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 a connection session
GET/v1/onboarding/sessions/{id}
The session's current state and the matching guidance text, ready to display.
Path parameters
idstring (uuid)required
Responses
200Success.
sessionIdstring (uuid)requiredstatestringrequiredorientacaostringrequiredterminalbooleanrequiredproximoPassostring | nullrequiredattemptCountintegerrequirednextAttemptAtstring | nullrequiredretryNotBeforestring | nullrequiredexpiresAtstringrequiredcreatedAtstringrequiredupdatedAtstringrequired
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."
}404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
{
"error": "not_found",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Recurso não encontrado."
}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."
}Report an abandoned or failed flow
POST/v1/onboarding/sessions/{id}/abandon
Telemetry about what happened in Meta's window when the flow did not complete: which screen the customer stopped on, or which error Meta reported.
Path parameters
idstring (uuid)required
Request body
csrfStatestringrequiredcurrentStepstring | nulloptional1 to 120 characterserrorCodeinteger | nulloptionalerrorMessagestring | nulloptional
Responses
200Success.
sessionIdstring (uuid)requiredstatestringrequiredorientacaostringrequiredabandonedAtStepstring | 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."
}404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
{
"error": "not_found",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Recurso não encontrado."
}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."
}Complete the connection
POST/v1/onboarding/sessions/{id}/complete
Exchanges the embedded flow's code for permanent access to the customer's account, and drives the session to the end: sealed token, app subscribed to the account, phone number registered.
Path parameters
idstring (uuid)required
Request body
codestringrequiredcsrfStatestringrequiredwabaIdstring | nulloptionalphoneNumberIdstring | nulloptionalbusinessIdstring | nulloptional
Responses
200Success.
sessionIdstring (uuid)requiredstatestringrequiredorientacaostringrequiredterminalbooleanrequiredproximoPassostring | nullrequiredmotivostring | nullrequiredpodeRetentarbooleanrequiredwabaIdstring | nullrequiredphoneNumberIdstring | 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": "trial_expired",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"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."
}{
"error": "account_blocked",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. 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 saber o motivo e resolver, escreva para contato@lunahia.com.br."
}{
"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."
}404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
{
"error": "not_found",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Recurso não encontrado."
}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."
}List connected phone numbers
GET/v1/numbers
Every WhatsApp number connected to this customer, with state, quality, sending speed and daily conversation limit. Filters: externalId (exact match), q (prefix search over externalId, label and displayNumber), state, wabaId, qualityRating, connectionStatus, ready and canSend. A parameter the route does not know answers 400.
Query parameters
externalIdstringoptionalO rótulo que você deu ao seu cliente. Igualdade exata; rótulo sem número devolve lista vazia.1 to 128 charactersstatestringoptionalO estado do número (state): PENDING, REGISTER_SENT, REGISTERED, PIN_REQUIRED, BLOCKED ou DISCONNECTED.Values:PENDINGREGISTER_SENTREGISTEREDPIN_REQUIREDBLOCKEDDISCONNECTEDqstringoptionalBusca por prefixo, sem diferenciar maiúscula, em externalId, label e displayNumber. Quem digita só o número de telefone acha o número mesmo sem os espaços e o hífen.1 to 128 characterswabaIdstringoptionalO id da conta de negócio na Meta (waba.id): só os números dela. Igualdade exata; uma conta sem número seu devolve lista vazia.1 to 64 charactersqualityRatingstringoptionalA qualidade que a Meta informou para o número (qualityRating): GREEN, YELLOW, RED, NA ou UNKNOWN. Número cuja qualidade a Luna ainda não leu (qualityRating nulo) não entra em nenhum valor.Values:GREENYELLOWREDNAUNKNOWNconnectionStatusstringoptionalSó os números com este connection.status: connected, connecting, action_required ou disconnected.Values:connectedconnectingaction_requireddisconnectedreadystringoptionaltrue: só os números prontos para enviar e receber. false: só os que ainda não estão.Values:truefalsecanSendstringoptionaltrue: só os números por onde enviar funciona agora (connection.canSend). false: só os que não.Values:truefalselimitintegeroptionalQuantos números por página: de 1 a 100, 50 se omitido.minimum 1 · maximum 100cursorstringoptionalO nextCursor da resposta anterior. Opaco: carrega posição, não contagem.up to 256 characters
Responses
200Success.
dataarray<object>requireddata[].idstring (uuid)requireddata[].metaPhoneNumberIdstringrequireddata[].displayNumberstring | nullrequireddata[].statestringrequireddata[].retryNotBeforestring | nullrequireddata[].podeRetentarbooleanrequireddata[].qualityRatingstring | nullrequireddata[].throughputLevelstring | nullrequiredA VELOCIDADE de envio que a Meta concede a este número: quantas mensagens por segundo ela aceita processar. Não é o volume que pode ser iniciado por dia, que é limiteDiarioDeConversas.data[].limiteDiarioDeConversasstring | nullrequiredO limite de mensagens da Meta, no nome de faixa dela: TIER_250, TIER_2K, TIER_10K, TIER_100K ou TIER_UNLIMITED (250, 2.000, 10.000 e 100.000 pessoas por período de 24 horas, ou sem teto). Ele é do portfólio empresarial (business portfolio) e não do número: vale para todos os números do portfólio juntos, e o valor aqui é o que a Meta devolveu na leitura deste número. Conta pessoas únicas a quem a empresa escreve fora da janela de atendimento, e não mensagens: conversas que o cliente final inicia, e respostas dentro da janela de 24 horas, não consomem este limite. Não é a velocidade de envio, que é throughputLevel. Nulo enquanto a plataforma ainda não verificou este número.data[].codeVerificationStatusstring | nullrequireddata[].displayNamestring | nullrequiredO nome de exibição do número: o nome verificado que o contato vê no topo da conversa. Nulo enquanto a plataforma ainda não leu o número, o que acontece em até cerca de uma hora.data[].displayNameStatusstring | nullrequiredO estado da revisão do nome de exibição pela Meta: approved, pending_review, declined, expired ou none. Vale para o pedido mais recente, quando há um, e senão para o nome em uso. Novos valores podem aparecer: não trate a lista como fechada. Nulo enquanto a plataforma ainda não leu o número. Quando muda, o evento number.display_name_reviewed avisa. Para pedir um nome novo, use PATCH /v1/numbers/{id}/profile com displayName.data[].pendingDisplayNamestring | nullrequiredO nome pedido que ainda não é o nome em uso: em revisão, recusado, ou aprovado à espera de um novo registro do número. Nulo quando não há pedido. A Meta não informa o motivo de uma recusa, e a Luna não devolve um.data[].autoReadbooleanrequiredQuando true, a Luna marca como lida, na Meta, cada mensagem que este número recebe, sem indicador de digitando. Vale false quando nunca foi ligado. Liga e desliga com PATCH /v1/numbers/{id}. Só vale para mensagem que chega depois de ligar, e a marcação sai alguns segundos depois da chegada: a Luna não a faz no caminho do webhook.data[].externalIdstring | nullrequiredO rótulo que você deu ao seu cliente ao criar o link de conexão (POST /v1/onboarding/links), devolvido sem alteração. Nulo quando o número foi conectado sem link, ou com um link sem rótulo. Use ?externalId= na listagem para achar os números de um cliente seu.data[].labelstring | nullrequiredUm rótulo livre e curto (1 a 128 caracteres) que você dá ao número, por exemplo o nome do ponto de atendimento. Edite com PATCH /v1/numbers/{id}. Nulo quando não há. É diferente de externalId, que identifica o cliente seu a quem o número pertence.data[].orientacaostring | nullrequiredO que está acontecendo com a conexão deste número e o que fazer a respeito, em português pronto para você repassar ao seu cliente sem reescrever. Existe para todos os estados, inclusive os que não são falha: um número operando traz a confirmação de que está tudo certo. Um número que a Meta recusou por falta de método de pagamento traz aqui a razão e onde ela se resolve. Nulo quando não há sessão de conexão registrada para este número.data[].awaitingPaymentSincestring | nullrequiredQuando a Meta recusou um envio deste número por falta de método de pagamento do negócio final (erro 131042), em ISO-8601 UTC. Nulo quando não há espera. Num número desconectado (connection.status disconnected) é o último valor lido antes da desconexão: a Luna deixou de acompanhá-lo. A Meta não oferece consulta de pagamento nem avisa quando ele é regularizado: este campo só volta a nulo quando um envio seguinte é aceito, e é então que o evento number.payment_resolved sai. A Luna não cobra, não adianta e não intermedeia esse pagamento; quem resolve é o negócio dono da conta, no WhatsApp Manager da Meta.data[].wabaobjectrequiredO estado de saúde da conta de negócio a que este número pertence, lido do último aviso da Meta (os eventos account.restricted, account.disabled e account.reinstated). A restrição e a desativação são da conta, e valem para todos os números dela.data[].waba.idstring | nullrequiredO identificador da conta de negócio do número na Meta (WABA).data[].waba.restrictedbooleanrequiredtrue quando a Meta avisou uma restrição da conta e ela ainda vale. Os detalhes estão em GET /v1/business-accounts.data[].waba.disabledbooleanrequiredtrue quando a Meta avisou que desativou a conta.data[].waba.credentialExpiresAtstring | nullrequiredQuando a autorização que o cliente deu à Luna vence, em ISO-8601 UTC. Nulo quando ela não vence (veja credentialNeverExpires) ou quando a Luna ainda não leu a validade. O evento number.credential_expiring avisa 14 dias antes.data[].waba.credentialNeverExpiresboolean | nullrequiredtrue: a Meta informou que a autorização não vence. false: vence, e credentialExpiresAt traz a data. Nulo: ainda não lida.data[].waba.paymentMethodOnMetaboolean | nullrequiredtrue: a conta tem forma de pagamento na Meta. false: não tem, e a Meta para de entregar mensagens de serviço depois da franquia de 1.000 por número por mês. Nulo: a Luna ainda não leu. O pagamento é do negócio com a Meta, e a Luna não o intermedeia.data[].waba.currencystring | nullrequiredA moeda da conta na Meta, como ela informa (por exemplo BRL). Nulo quando ainda não lida.data[].readybooleanrequiredtrue quando o número já pode enviar e receber: state é REGISTERED e a inscrição do aplicativo na conta foi confirmada. Use este campo em vez de combinar os dois você mesmo. É diferente de connection.canSend, que diz se enviar vai funcionar agora.data[].connectionobjectrequiredO estado resumido da conexão, calculado pela API a partir do estado do número, da autorização do cliente, da espera por pagamento, da forma de pagamento na Meta, da restrição da conta e da suspensão do plano. Os eventos number.action_required e number.action_resolved avisam quando a lista de motivos passa de vazia para não vazia, e de volta.data[].connection.statusstringrequiredO estado resumido: connected (nada a fazer), connecting (a conexão está em curso e é automática), action_required (alguém precisa agir, e reasons diz o quê) ou disconnected (você desconectou o número).Values:connectedconnectingaction_requireddisconnecteddata[].connection.canSendbooleanrequiredSe o envio por este número vai funcionar agora. Pode ser true com status action_required: autorização vencendo e conta sem método de pagamento são avisos, e o número ainda envia.data[].connection.reasonsarray<object>requiredPor que o número precisa de ação. Vazio quando status é connected, connecting ou disconnected. Os motivos possíveis: pin_required, registration_blocked, credential_invalid, credential_expired, credential_expiring, payment_required, payment_method_missing, account_restricted, account_disabled, trial_expired e account_blocked.data[].connection.reasons[].codestringrequiredO código do motivo, para o seu código comparar. Novos códigos podem aparecer.data[].connection.reasons[].messagestringrequiredO que está acontecendo, em português, pronto para repassar ao seu cliente.data[].connection.reasons[].solutionstringrequiredO que fazer a respeito, em português.data[].connection.reasons[].actionstring | nullrequiredA ação que resolve o motivo: send_pin (informe o PIN em POST /v1/numbers/{id}/pin), reconnect (reconecte pela janela da Meta), reconnect_link (gere um link de reconexão para o seu cliente), meta_manager (o dono da conta resolve no WhatsApp Manager, em actionUrl), wait (só esperar) ou contact_helsen (fale com o comercial da Helsen). Nulo quando não há ação a oferecer.Values:send_pinreconnectreconnect_linkmeta_managerwaitcontact_helsendata[].connection.reasons[].actionUrlstring | nullrequiredO endereço da conta no WhatsApp Manager da Meta. Só vem quando action é meta_manager.data[].connection.reasons[].docsUrlstring | nullrequiredO guia do site que explica o motivo.data[].connection.reasons[].sincestring | nullrequiredDesde quando o motivo vale, em ISO-8601 UTC. É o instante exato quando a Luna o conhece (espera por pagamento, vencimento da autorização, aviso da Meta sobre a conta, fim do teste, bloqueio) e, nos demais, o instante em que o número passou a precisar de ação. Nulo quando a Luna não tem instante nenhum.data[].allowedActionsarray<string>requiredO que a sua conta pode fazer com este número agora, decidido pela API: disconnect (DELETE /v1/numbers/{id}), reconnect (POST /v1/onboarding/reconnect), reconnect_link (POST /v1/onboarding/links com numberId), send_pin (POST /v1/numbers/{id}/pin) e edit_label (PATCH /v1/numbers/{id}). Mostre o botão quando o verbo está na lista, e não por state ou connection.status. A lista leva em conta o estado do número, a autorização do cliente, o e-mail confirmado, a suspensão e a capacidade do plano, e não leva em conta os escopos da chave que perguntou.data[].blockedActionsarray<object>requiredAs ações que fariam sentido neste número e a conta impede agora, cada uma com a razão. Um verbo que não se aplica ao estado do número não aparece aqui nem em allowedActions.data[].blockedActions[].actionstringrequiredValues:disconnectreconnectreconnect_linksend_pinedit_labeldata[].blockedActions[].messagestringrequiredPor que a ação não está disponível agora, em português, pronto para mostrar.data[].createdAtstringrequireddata[].updatedAtstringrequirednextCursorstring | nullrequiredMande este valor de volta em cursor para pegar a próxima página. Nulo significa fim.
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 one phone number
GET/v1/numbers/{id}
One number, with everything the listing carries plus the health of its connection to Meta.
Path parameters
idstringrequiredO identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem.1 to 64 characters · /^[A-Za-z0-9_-]+$/
Responses
200Success.
idstring (uuid)requiredmetaPhoneNumberIdstringrequireddisplayNumberstring | nullrequiredstatestringrequiredretryNotBeforestring | nullrequiredpodeRetentarbooleanrequiredqualityRatingstring | nullrequiredthroughputLevelstring | nullrequiredA VELOCIDADE de envio que a Meta concede a este número: quantas mensagens por segundo ela aceita processar. Não é o volume que pode ser iniciado por dia, que é limiteDiarioDeConversas.limiteDiarioDeConversasstring | nullrequiredO limite de mensagens da Meta, no nome de faixa dela: TIER_250, TIER_2K, TIER_10K, TIER_100K ou TIER_UNLIMITED (250, 2.000, 10.000 e 100.000 pessoas por período de 24 horas, ou sem teto). Ele é do portfólio empresarial (business portfolio) e não do número: vale para todos os números do portfólio juntos, e o valor aqui é o que a Meta devolveu na leitura deste número. Conta pessoas únicas a quem a empresa escreve fora da janela de atendimento, e não mensagens: conversas que o cliente final inicia, e respostas dentro da janela de 24 horas, não consomem este limite. Não é a velocidade de envio, que é throughputLevel. Nulo enquanto a plataforma ainda não verificou este número.codeVerificationStatusstring | nullrequireddisplayNamestring | nullrequiredO nome de exibição do número: o nome verificado que o contato vê no topo da conversa. Nulo enquanto a plataforma ainda não leu o número, o que acontece em até cerca de uma hora.displayNameStatusstring | nullrequiredO estado da revisão do nome de exibição pela Meta: approved, pending_review, declined, expired ou none. Vale para o pedido mais recente, quando há um, e senão para o nome em uso. Novos valores podem aparecer: não trate a lista como fechada. Nulo enquanto a plataforma ainda não leu o número. Quando muda, o evento number.display_name_reviewed avisa. Para pedir um nome novo, use PATCH /v1/numbers/{id}/profile com displayName.pendingDisplayNamestring | nullrequiredO nome pedido que ainda não é o nome em uso: em revisão, recusado, ou aprovado à espera de um novo registro do número. Nulo quando não há pedido. A Meta não informa o motivo de uma recusa, e a Luna não devolve um.autoReadbooleanrequiredQuando true, a Luna marca como lida, na Meta, cada mensagem que este número recebe, sem indicador de digitando. Vale false quando nunca foi ligado. Liga e desliga com PATCH /v1/numbers/{id}. Só vale para mensagem que chega depois de ligar, e a marcação sai alguns segundos depois da chegada: a Luna não a faz no caminho do webhook.externalIdstring | nullrequiredO rótulo que você deu ao seu cliente ao criar o link de conexão (POST /v1/onboarding/links), devolvido sem alteração. Nulo quando o número foi conectado sem link, ou com um link sem rótulo. Use ?externalId= na listagem para achar os números de um cliente seu.labelstring | nullrequiredUm rótulo livre e curto (1 a 128 caracteres) que você dá ao número, por exemplo o nome do ponto de atendimento. Edite com PATCH /v1/numbers/{id}. Nulo quando não há. É diferente de externalId, que identifica o cliente seu a quem o número pertence.orientacaostring | nullrequiredO que está acontecendo com a conexão deste número e o que fazer a respeito, em português pronto para você repassar ao seu cliente sem reescrever. Existe para todos os estados, inclusive os que não são falha: um número operando traz a confirmação de que está tudo certo. Um número que a Meta recusou por falta de método de pagamento traz aqui a razão e onde ela se resolve. Nulo quando não há sessão de conexão registrada para este número.awaitingPaymentSincestring | nullrequiredQuando a Meta recusou um envio deste número por falta de método de pagamento do negócio final (erro 131042), em ISO-8601 UTC. Nulo quando não há espera. Num número desconectado (connection.status disconnected) é o último valor lido antes da desconexão: a Luna deixou de acompanhá-lo. A Meta não oferece consulta de pagamento nem avisa quando ele é regularizado: este campo só volta a nulo quando um envio seguinte é aceito, e é então que o evento number.payment_resolved sai. A Luna não cobra, não adianta e não intermedeia esse pagamento; quem resolve é o negócio dono da conta, no WhatsApp Manager da Meta.wabaobjectrequiredO estado de saúde da conta de negócio a que este número pertence, lido do último aviso da Meta (os eventos account.restricted, account.disabled e account.reinstated). A restrição e a desativação são da conta, e valem para todos os números dela.waba.idstring | nullrequiredO identificador da conta de negócio do número na Meta (WABA).waba.restrictedbooleanrequiredtrue quando a Meta avisou uma restrição da conta e ela ainda vale. Os detalhes estão em GET /v1/business-accounts.waba.disabledbooleanrequiredtrue quando a Meta avisou que desativou a conta.waba.credentialExpiresAtstring | nullrequiredQuando a autorização que o cliente deu à Luna vence, em ISO-8601 UTC. Nulo quando ela não vence (veja credentialNeverExpires) ou quando a Luna ainda não leu a validade. O evento number.credential_expiring avisa 14 dias antes.waba.credentialNeverExpiresboolean | nullrequiredtrue: a Meta informou que a autorização não vence. false: vence, e credentialExpiresAt traz a data. Nulo: ainda não lida.waba.paymentMethodOnMetaboolean | nullrequiredtrue: a conta tem forma de pagamento na Meta. false: não tem, e a Meta para de entregar mensagens de serviço depois da franquia de 1.000 por número por mês. Nulo: a Luna ainda não leu. O pagamento é do negócio com a Meta, e a Luna não o intermedeia.waba.currencystring | nullrequiredA moeda da conta na Meta, como ela informa (por exemplo BRL). Nulo quando ainda não lida.readybooleanrequiredtrue quando o número já pode enviar e receber: state é REGISTERED e a inscrição do aplicativo na conta foi confirmada. Use este campo em vez de combinar os dois você mesmo. É diferente de connection.canSend, que diz se enviar vai funcionar agora.connectionobjectrequiredconnection.statusstringrequiredO estado resumido: connected (nada a fazer), connecting (a conexão está em curso e é automática), action_required (alguém precisa agir, e reasons diz o quê) ou disconnected (você desconectou o número).Values:connectedconnectingaction_requireddisconnectedconnection.canSendbooleanrequiredSe o envio por este número vai funcionar agora. Pode ser true com status action_required: autorização vencendo e conta sem método de pagamento são avisos, e o número ainda envia.connection.reasonsarray<object>requiredPor que o número precisa de ação. Vazio quando status é connected, connecting ou disconnected. Os motivos possíveis: pin_required, registration_blocked, credential_invalid, credential_expired, credential_expiring, payment_required, payment_method_missing, account_restricted, account_disabled, trial_expired e account_blocked.connection.reasons[].codestringrequiredO código do motivo, para o seu código comparar. Novos códigos podem aparecer.connection.reasons[].messagestringrequiredO que está acontecendo, em português, pronto para repassar ao seu cliente.connection.reasons[].solutionstringrequiredO que fazer a respeito, em português.connection.reasons[].actionstring | nullrequiredA ação que resolve o motivo: send_pin (informe o PIN em POST /v1/numbers/{id}/pin), reconnect (reconecte pela janela da Meta), reconnect_link (gere um link de reconexão para o seu cliente), meta_manager (o dono da conta resolve no WhatsApp Manager, em actionUrl), wait (só esperar) ou contact_helsen (fale com o comercial da Helsen). Nulo quando não há ação a oferecer.Values:send_pinreconnectreconnect_linkmeta_managerwaitcontact_helsenconnection.reasons[].actionUrlstring | nullrequiredO endereço da conta no WhatsApp Manager da Meta. Só vem quando action é meta_manager.connection.reasons[].docsUrlstring | nullrequiredO guia do site que explica o motivo.connection.reasons[].sincestring | nullrequiredDesde quando o motivo vale, em ISO-8601 UTC. É o instante exato quando a Luna o conhece (espera por pagamento, vencimento da autorização, aviso da Meta sobre a conta, fim do teste, bloqueio) e, nos demais, o instante em que o número passou a precisar de ação. Nulo quando a Luna não tem instante nenhum.connection.stepsarray<object>requiredOs quatro passos da conexão, sempre nesta ordem: authorized (a autorização do cliente), receiving (a inscrição do aplicativo na conta, que traz os eventos), registered (o número registrado, ou vinculado em coexistência) e ready (pronto para enviar e receber). current é o primeiro que ainda não terminou, e com todos done nenhum é current. A tela só precisa desenhar a lista.connection.steps[].keystringrequiredValues:authorizedreceivingregisteredreadyconnection.steps[].labelstringrequiredO nome do passo, em português. Em coexistência o terceiro passo se chama Número vinculado.connection.steps[].statusstringrequiredValues:donecurrentpendingallowedActionsarray<string>requiredO que a sua conta pode fazer com este número agora, decidido pela API: disconnect (DELETE /v1/numbers/{id}), reconnect (POST /v1/onboarding/reconnect), reconnect_link (POST /v1/onboarding/links com numberId), send_pin (POST /v1/numbers/{id}/pin) e edit_label (PATCH /v1/numbers/{id}). Mostre o botão quando o verbo está na lista, e não por state ou connection.status. A lista leva em conta o estado do número, a autorização do cliente, o e-mail confirmado, a suspensão e a capacidade do plano, e não leva em conta os escopos da chave que perguntou.blockedActionsarray<object>requiredAs ações que fariam sentido neste número e a conta impede agora, cada uma com a razão. Um verbo que não se aplica ao estado do número não aparece aqui nem em allowedActions.blockedActions[].actionstringrequiredValues:disconnectreconnectreconnect_linksend_pinedit_labelblockedActions[].messagestringrequiredPor que a ação não está disponível agora, em português, pronto para mostrar.createdAtstringrequiredupdatedAtstringrequiredtetoDeVazaoPorSegundonumber | nullrequiredO teto de envio deste número em mensagens por segundo, quando ele é FIXO e não sobe. Números conectados em coexistência, que continuam funcionando no aplicativo de celular do negócio, têm esse teto fixo pela plataforma da Meta, e ele não acompanha a progressão de throughputLevel. Nulo significa o contrário: este número segue a progressão da Meta, e quem a descreve é throughputLevel. Não é contagem de nada e não muda com o que o número enviou: é a capacidade que a plataforma da Meta concede.sincronizacaoDoHistoricostring | nullrequiredEm que pé está a importação das conversas anteriores do aparelho do negócio, num número conectado em coexistência. São quatro situações e cada uma pede uma reação diferente. Nulo significa que não há importação para este número, e não que ela parou. em_curso significa que ela está acontecendo, e sincronizacaoPrazo diz até quando. 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: não vai concluir, e pedir de novo não muda isso. Atenção ao ler sincronizacaoProgresso junto: cem por cento não significa sucesso, porque a recusa chega com o progresso que já havia sido registrado.sincronizacaoPrazostring | nullrequiredAté quando a importação precisa terminar. Passado esse instante sem concluir, a plataforma da Meta desconecta o negócio final e ele precisa refazer a conexão no aparelho. Sai sempre como instante em UTC, e nunca como texto do tipo faltam tantas horas: um texto desses fica errado na tela de quem a deixou aberta, e quem integra pela API precisa de um valor comparável com o próprio relógio. Nulo quando não há importação em curso conhecida.sincronizacaoProgressonumber | nullrequiredO rótulo de progresso que a plataforma da Meta atribui à importação, de 0 a 100. É um rótulo e não uma contagem: ele chega a 100 igualmente para um aparelho com poucas conversas antigas e para um com muitas, e nada nele cresce com o tamanho do que foi importado. Não use este campo para deduzir quantidade, porque ele não carrega nenhuma. Nulo quando a plataforma da Meta ainda não informou progresso para este número.subscriptionConfirmedAtstring | nullrequiredQuando a inscrição do aplicativo na conta foi confirmada por leitura de volta. Nulo significa que os eventos deste número ainda não chegam. Num número desconectado é o último valor lido antes da desconexão.credentialStatusstring | nullrequiredO estado da autorização concedida pelo cliente. Nunca a credencial em si. Num número desconectado é o último valor lido antes da desconexão, e serve a quem decide reconectar (podeReconectar).podeReconectarbooleanrequiredSe a autorização deste número admite reconexão. Quando for true, POST /v1/onboarding/reconnect abre a sessão que a substitui.coexistencebooleanrequiredtrue quando a Luna já observou tráfego de coexistência neste número, ou seja, ele continua funcionando no aplicativo de celular do negócio. É a mesma regra do campo coexistence do evento number.connected, e pode passar de false para true depois da conexão. É true exatamente quando tetoDeVazaoPorSegundo tem valor.
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."
}404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
{
"error": "not_found",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Recurso não encontrado."
}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."
}Edit a number
PATCH/v1/numbers/{id}
Changes a number's externalId and label, and turns autoRead (mark every received message as read on its own) on or off. It is how you reuse a number for another customer of yours, or name a number that was connected through the console, without a link.
Path parameters
idstringrequiredO identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem.1 to 64 characters · /^[A-Za-z0-9_-]+$/
Request body
externalIdstring | nulloptionalO seu identificador para o cliente dono do número (1 a 128 caracteres). null limpa.1 to 128 characterslabelstring | nulloptionalUm nome livre e curto para reconhecer o número (1 a 128 caracteres). null limpa.1 to 128 charactersautoReadbooleanoptionaltrue: a Luna marca como lida, na Meta, cada mensagem que o número receber daqui em diante, sem indicador de digitando. false desliga. Ausente não muda. O padrão de um número é false.
Responses
200Success.
idstring (uuid)requiredmetaPhoneNumberIdstringrequireddisplayNumberstring | nullrequiredstatestringrequiredretryNotBeforestring | nullrequiredpodeRetentarbooleanrequiredqualityRatingstring | nullrequiredthroughputLevelstring | nullrequiredA VELOCIDADE de envio que a Meta concede a este número: quantas mensagens por segundo ela aceita processar. Não é o volume que pode ser iniciado por dia, que é limiteDiarioDeConversas.limiteDiarioDeConversasstring | nullrequiredO limite de mensagens da Meta, no nome de faixa dela: TIER_250, TIER_2K, TIER_10K, TIER_100K ou TIER_UNLIMITED (250, 2.000, 10.000 e 100.000 pessoas por período de 24 horas, ou sem teto). Ele é do portfólio empresarial (business portfolio) e não do número: vale para todos os números do portfólio juntos, e o valor aqui é o que a Meta devolveu na leitura deste número. Conta pessoas únicas a quem a empresa escreve fora da janela de atendimento, e não mensagens: conversas que o cliente final inicia, e respostas dentro da janela de 24 horas, não consomem este limite. Não é a velocidade de envio, que é throughputLevel. Nulo enquanto a plataforma ainda não verificou este número.codeVerificationStatusstring | nullrequireddisplayNamestring | nullrequiredO nome de exibição do número: o nome verificado que o contato vê no topo da conversa. Nulo enquanto a plataforma ainda não leu o número, o que acontece em até cerca de uma hora.displayNameStatusstring | nullrequiredO estado da revisão do nome de exibição pela Meta: approved, pending_review, declined, expired ou none. Vale para o pedido mais recente, quando há um, e senão para o nome em uso. Novos valores podem aparecer: não trate a lista como fechada. Nulo enquanto a plataforma ainda não leu o número. Quando muda, o evento number.display_name_reviewed avisa. Para pedir um nome novo, use PATCH /v1/numbers/{id}/profile com displayName.pendingDisplayNamestring | nullrequiredO nome pedido que ainda não é o nome em uso: em revisão, recusado, ou aprovado à espera de um novo registro do número. Nulo quando não há pedido. A Meta não informa o motivo de uma recusa, e a Luna não devolve um.autoReadbooleanrequiredQuando true, a Luna marca como lida, na Meta, cada mensagem que este número recebe, sem indicador de digitando. Vale false quando nunca foi ligado. Liga e desliga com PATCH /v1/numbers/{id}. Só vale para mensagem que chega depois de ligar, e a marcação sai alguns segundos depois da chegada: a Luna não a faz no caminho do webhook.externalIdstring | nullrequiredO rótulo que você deu ao seu cliente ao criar o link de conexão (POST /v1/onboarding/links), devolvido sem alteração. Nulo quando o número foi conectado sem link, ou com um link sem rótulo. Use ?externalId= na listagem para achar os números de um cliente seu.labelstring | nullrequiredUm rótulo livre e curto (1 a 128 caracteres) que você dá ao número, por exemplo o nome do ponto de atendimento. Edite com PATCH /v1/numbers/{id}. Nulo quando não há. É diferente de externalId, que identifica o cliente seu a quem o número pertence.orientacaostring | nullrequiredO que está acontecendo com a conexão deste número e o que fazer a respeito, em português pronto para você repassar ao seu cliente sem reescrever. Existe para todos os estados, inclusive os que não são falha: um número operando traz a confirmação de que está tudo certo. Um número que a Meta recusou por falta de método de pagamento traz aqui a razão e onde ela se resolve. Nulo quando não há sessão de conexão registrada para este número.awaitingPaymentSincestring | nullrequiredQuando a Meta recusou um envio deste número por falta de método de pagamento do negócio final (erro 131042), em ISO-8601 UTC. Nulo quando não há espera. Num número desconectado (connection.status disconnected) é o último valor lido antes da desconexão: a Luna deixou de acompanhá-lo. A Meta não oferece consulta de pagamento nem avisa quando ele é regularizado: este campo só volta a nulo quando um envio seguinte é aceito, e é então que o evento number.payment_resolved sai. A Luna não cobra, não adianta e não intermedeia esse pagamento; quem resolve é o negócio dono da conta, no WhatsApp Manager da Meta.wabaobjectrequiredO estado de saúde da conta de negócio a que este número pertence, lido do último aviso da Meta (os eventos account.restricted, account.disabled e account.reinstated). A restrição e a desativação são da conta, e valem para todos os números dela.waba.idstring | nullrequiredO identificador da conta de negócio do número na Meta (WABA).waba.restrictedbooleanrequiredtrue quando a Meta avisou uma restrição da conta e ela ainda vale. Os detalhes estão em GET /v1/business-accounts.waba.disabledbooleanrequiredtrue quando a Meta avisou que desativou a conta.waba.credentialExpiresAtstring | nullrequiredQuando a autorização que o cliente deu à Luna vence, em ISO-8601 UTC. Nulo quando ela não vence (veja credentialNeverExpires) ou quando a Luna ainda não leu a validade. O evento number.credential_expiring avisa 14 dias antes.waba.credentialNeverExpiresboolean | nullrequiredtrue: a Meta informou que a autorização não vence. false: vence, e credentialExpiresAt traz a data. Nulo: ainda não lida.waba.paymentMethodOnMetaboolean | nullrequiredtrue: a conta tem forma de pagamento na Meta. false: não tem, e a Meta para de entregar mensagens de serviço depois da franquia de 1.000 por número por mês. Nulo: a Luna ainda não leu. O pagamento é do negócio com a Meta, e a Luna não o intermedeia.waba.currencystring | nullrequiredA moeda da conta na Meta, como ela informa (por exemplo BRL). Nulo quando ainda não lida.readybooleanrequiredtrue quando o número já pode enviar e receber: state é REGISTERED e a inscrição do aplicativo na conta foi confirmada. Use este campo em vez de combinar os dois você mesmo. É diferente de connection.canSend, que diz se enviar vai funcionar agora.connectionobjectrequiredconnection.statusstringrequiredO estado resumido: connected (nada a fazer), connecting (a conexão está em curso e é automática), action_required (alguém precisa agir, e reasons diz o quê) ou disconnected (você desconectou o número).Values:connectedconnectingaction_requireddisconnectedconnection.canSendbooleanrequiredSe o envio por este número vai funcionar agora. Pode ser true com status action_required: autorização vencendo e conta sem método de pagamento são avisos, e o número ainda envia.connection.reasonsarray<object>requiredPor que o número precisa de ação. Vazio quando status é connected, connecting ou disconnected. Os motivos possíveis: pin_required, registration_blocked, credential_invalid, credential_expired, credential_expiring, payment_required, payment_method_missing, account_restricted, account_disabled, trial_expired e account_blocked.connection.reasons[].codestringrequiredO código do motivo, para o seu código comparar. Novos códigos podem aparecer.connection.reasons[].messagestringrequiredO que está acontecendo, em português, pronto para repassar ao seu cliente.connection.reasons[].solutionstringrequiredO que fazer a respeito, em português.connection.reasons[].actionstring | nullrequiredA ação que resolve o motivo: send_pin (informe o PIN em POST /v1/numbers/{id}/pin), reconnect (reconecte pela janela da Meta), reconnect_link (gere um link de reconexão para o seu cliente), meta_manager (o dono da conta resolve no WhatsApp Manager, em actionUrl), wait (só esperar) ou contact_helsen (fale com o comercial da Helsen). Nulo quando não há ação a oferecer.Values:send_pinreconnectreconnect_linkmeta_managerwaitcontact_helsenconnection.reasons[].actionUrlstring | nullrequiredO endereço da conta no WhatsApp Manager da Meta. Só vem quando action é meta_manager.connection.reasons[].docsUrlstring | nullrequiredO guia do site que explica o motivo.connection.reasons[].sincestring | nullrequiredDesde quando o motivo vale, em ISO-8601 UTC. É o instante exato quando a Luna o conhece (espera por pagamento, vencimento da autorização, aviso da Meta sobre a conta, fim do teste, bloqueio) e, nos demais, o instante em que o número passou a precisar de ação. Nulo quando a Luna não tem instante nenhum.connection.stepsarray<object>requiredOs quatro passos da conexão, sempre nesta ordem: authorized (a autorização do cliente), receiving (a inscrição do aplicativo na conta, que traz os eventos), registered (o número registrado, ou vinculado em coexistência) e ready (pronto para enviar e receber). current é o primeiro que ainda não terminou, e com todos done nenhum é current. A tela só precisa desenhar a lista.connection.steps[].keystringrequiredValues:authorizedreceivingregisteredreadyconnection.steps[].labelstringrequiredO nome do passo, em português. Em coexistência o terceiro passo se chama Número vinculado.connection.steps[].statusstringrequiredValues:donecurrentpendingallowedActionsarray<string>requiredO que a sua conta pode fazer com este número agora, decidido pela API: disconnect (DELETE /v1/numbers/{id}), reconnect (POST /v1/onboarding/reconnect), reconnect_link (POST /v1/onboarding/links com numberId), send_pin (POST /v1/numbers/{id}/pin) e edit_label (PATCH /v1/numbers/{id}). Mostre o botão quando o verbo está na lista, e não por state ou connection.status. A lista leva em conta o estado do número, a autorização do cliente, o e-mail confirmado, a suspensão e a capacidade do plano, e não leva em conta os escopos da chave que perguntou.blockedActionsarray<object>requiredAs ações que fariam sentido neste número e a conta impede agora, cada uma com a razão. Um verbo que não se aplica ao estado do número não aparece aqui nem em allowedActions.blockedActions[].actionstringrequiredValues:disconnectreconnectreconnect_linksend_pinedit_labelblockedActions[].messagestringrequiredPor que a ação não está disponível agora, em português, pronto para mostrar.createdAtstringrequiredupdatedAtstringrequiredtetoDeVazaoPorSegundonumber | nullrequiredO teto de envio deste número em mensagens por segundo, quando ele é FIXO e não sobe. Números conectados em coexistência, que continuam funcionando no aplicativo de celular do negócio, têm esse teto fixo pela plataforma da Meta, e ele não acompanha a progressão de throughputLevel. Nulo significa o contrário: este número segue a progressão da Meta, e quem a descreve é throughputLevel. Não é contagem de nada e não muda com o que o número enviou: é a capacidade que a plataforma da Meta concede.sincronizacaoDoHistoricostring | nullrequiredEm que pé está a importação das conversas anteriores do aparelho do negócio, num número conectado em coexistência. São quatro situações e cada uma pede uma reação diferente. Nulo significa que não há importação para este número, e não que ela parou. em_curso significa que ela está acontecendo, e sincronizacaoPrazo diz até quando. 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: não vai concluir, e pedir de novo não muda isso. Atenção ao ler sincronizacaoProgresso junto: cem por cento não significa sucesso, porque a recusa chega com o progresso que já havia sido registrado.sincronizacaoPrazostring | nullrequiredAté quando a importação precisa terminar. Passado esse instante sem concluir, a plataforma da Meta desconecta o negócio final e ele precisa refazer a conexão no aparelho. Sai sempre como instante em UTC, e nunca como texto do tipo faltam tantas horas: um texto desses fica errado na tela de quem a deixou aberta, e quem integra pela API precisa de um valor comparável com o próprio relógio. Nulo quando não há importação em curso conhecida.sincronizacaoProgressonumber | nullrequiredO rótulo de progresso que a plataforma da Meta atribui à importação, de 0 a 100. É um rótulo e não uma contagem: ele chega a 100 igualmente para um aparelho com poucas conversas antigas e para um com muitas, e nada nele cresce com o tamanho do que foi importado. Não use este campo para deduzir quantidade, porque ele não carrega nenhuma. Nulo quando a plataforma da Meta ainda não informou progresso para este número.subscriptionConfirmedAtstring | nullrequiredQuando a inscrição do aplicativo na conta foi confirmada por leitura de volta. Nulo significa que os eventos deste número ainda não chegam. Num número desconectado é o último valor lido antes da desconexão.credentialStatusstring | nullrequiredO estado da autorização concedida pelo cliente. Nunca a credencial em si. Num número desconectado é o último valor lido antes da desconexão, e serve a quem decide reconectar (podeReconectar).podeReconectarbooleanrequiredSe a autorização deste número admite reconexão. Quando for true, POST /v1/onboarding/reconnect abre a sessão que a substitui.coexistencebooleanrequiredtrue quando a Luna já observou tráfego de coexistência neste número, ou seja, ele continua funcionando no aplicativo de celular do negócio. É a mesma regra do campo coexistence do evento number.connected, e pode passar de false para true depois da conexão. É true exatamente quando tetoDeVazaoPorSegundo tem valor.
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": "trial_expired",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"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."
}{
"error": "account_blocked",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. 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 saber o motivo e resolver, escreva para contato@lunahia.com.br."
}{
"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."
}404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
{
"error": "not_found",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Recurso não encontrado."
}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."
}Disconnect a number
DELETE/v1/numbers/{id}
Takes the number off Luna. It is how you open a slot in the plan capacity: the number stops counting from this instant, and your customer can be swapped for another.
Path parameters
idstringrequiredO identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem.1 to 64 characters · /^[A-Za-z0-9_-]+$/
Responses
204No content: the operation was done and the response has no body.
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."
}404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
{
"error": "not_found",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Recurso não encontrado."
}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."
}Give a number's two step verification PIN
POST/v1/numbers/{id}/pin
Gives the two step verification PIN of a number that is already registered on another provider's Cloud API, so Luna can register it without the end business having to turn verification off.
Path parameters
idstringrequiredO identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem.1 to 64 characters · /^[A-Za-z0-9_-]+$/
Request body
pinstringrequiredO PIN de verificação em duas etapas deste número, com exatamente seis dígitos. Quando o número já tem verificação em duas etapas configurada em outro provedor, é o PIN existente dele, e apenas o negócio final o conhece: não existe endpoint para ler nem para desligar o PIN de um número. Quando o número não tem verificação em duas etapas, este valor passa a ser o PIN dele./^\d{6}$/
Responses
200Success.
idstring (uuid)requiredO identificador deste número na Luna.statestringrequiredO estado do número depois da submissão. Ele volta ao ponto de onde o registro opera, e a próxima tentativa de conexão usa o PIN que você informou.
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": "trial_expired",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"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."
}{
"error": "account_blocked",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. 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 saber o motivo e resolver, escreva para contato@lunahia.com.br."
}{
"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."
}404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
{
"error": "not_found",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Recurso não encontrado."
}409The request is well formed, but the resource state does not allow it. The error field says which case it is.
{
"error": "pin_not_applicable",
"docsUrl": "https://lunahia.com.br/docs/conectar-numero",
"message": "Este número não está aguardando o PIN de verificação em duas etapas. O campo state diz em que ponto ele está."
}{
"error": "register_budget_reserved",
"docsUrl": "https://lunahia.com.br/docs/conectar-numero",
"message": "As tentativas de registro que a Meta concede a este número em 72 horas estão perto do fim, e a plataforma guarda as últimas para não travar o número. Confirme o PIN com o negócio final antes de submeter de novo.",
"tentativasRestantes": 1,
"janelaVira": "2026-10-09T12:00:00.000Z"
}{
"error": "number_capacity_reached",
"message": "Esta conta já tem 20 números ativos, o máximo contratado (20). Para conectar outro, desconecte um número (DELETE /v1/numbers/{id}) ou escreva para contato@lunahia.com.br.",
"capacity": 20,
"activeNumbers": 20
}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."
}Reconnect a number whose authorisation died
POST/v1/onboarding/reconnect
Opens a connection session for a number that already exists, when the authorisation granted by the customer expired or was revoked.
Request body
numberIdstringrequiredO número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem.1 to 64 characters · /^[A-Za-z0-9_-]+$/
Responses
201Created.
sessionIdstring (uuid)requiredstatestringrequiredconfigIdstringrequiredsdkVersionstringrequiredA versão da Graph API com que o seu código deve iniciar o SDK do Facebook (FB.init) e abrir a janela de conexão da Meta. A Luna a escolhe e a atualiza, então não a copie para o seu código.csrfStatestringrequiredexpiresAtstringrequired
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": "connection_not_released",
"docsUrl": "https://lunahia.com.br/docs/conectar-numero",
"message": "Esta conta ainda não pode conectar um número: falta confirmar o e-mail do cadastro. Abra o link que enviamos para esse e-mail e tente de novo. A lista faltando mostra o que ainda não foi cumprido.",
"faltando": [
"email_confirmado"
]
}{
"error": "trial_expired",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"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."
}{
"error": "account_blocked",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. 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 saber o motivo e resolver, escreva para contato@lunahia.com.br."
}{
"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."
}404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
{
"error": "not_found",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Recurso não encontrado."
}409The request is well formed, but the resource state does not allow it. The error field says which case it is.
{
"error": "reconnect_not_applicable",
"docsUrl": "https://lunahia.com.br/docs/conectar-numero",
"message": "A autorização deste número não admite reconexão.",
"credentialStatus": "active"
}{
"error": "number_capacity_reached",
"message": "Esta conta já tem 20 números ativos, o máximo contratado (20). Para conectar outro, desconecte um número (DELETE /v1/numbers/{id}) ou escreva para contato@lunahia.com.br.",
"capacity": 20,
"activeNumbers": 20
}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."
}List business accounts
GET/v1/business-accounts
The WhatsApp Business accounts this customer has connected, newest first, each with its name at Meta, its WhatsApp Manager address and its numbers.
Responses
200Success.
dataarray<object>requireddata[].idstring (uuid)requireddata[].wabaIdstringrequireddata[].numbersarray<string>requireddata[].namestring | nullrequiredO nome da conta de WhatsApp Business como a Meta o informa. Nulo enquanto a Luna ainda não o leu.data[].managerUrlstringrequiredO endereço desta conta no WhatsApp Manager da Meta, onde o dono da conta resolve pagamento, verificação e restrições.data[].phoneNumbersarray<object>requiredOs números desta conta, na ordem em que foram conectados. É o numbers de texto com o que a tela precisa para ligar cada número ao seu recurso.data[].phoneNumbers[].idstring (uuid)requiredO id do número na Luna, o mesmo de GET /v1/numbers.data[].phoneNumbers[].displayNumberstring | nullrequiredO número como se lê no telefone, ou nulo enquanto a Luna não o leu.data[].phoneNumbers[].externalIdstring | nullrequiredO seu rótulo para o cliente dono do número.data[].phoneNumbers[].labelstring | nullrequiredO nome que você deu ao número.data[].statusobjectrequiredO último estado de saúde conhecido da conta.data[].status.restrictedbooleanrequiredtrue quando o último aviso de restrição da Meta ainda vale. Uma restrição com prazo deixa de contar quando o prazo passa, porque a Meta não avisa o fim dela. Uma restrição sem prazo legível conta até um novo aviso.data[].status.restrictionsarray<object>requiredAs restrições do último aviso, com o tipo, o prazo e a orientação como a Meta mandou. Vazia quando não há aviso.data[].status.restrictions[].restrictionTypestring | nullrequireddata[].status.restrictions[].expirationstring | nullrequireddata[].status.restrictions[].remediationstring | nullrequireddata[].status.disabledbooleanrequiredtrue quando o último aviso de desativação da Meta diz que a conta foi desativada. Volta a false se a Meta avisar a reativação.data[].status.violationTypestring | nullrequiredO tipo da última violação de política que a Meta avisou, ou nulo. É um aviso, e não um estado que expira.data[].status.reportedAtstring | nullrequiredQuando chegou o aviso de saúde mais recente, ou nulo se nunca chegou.data[].credentialExpiresAtstring | nullrequiredQuando a autorização que o cliente deu à Luna vence, em ISO-8601 UTC. Nulo quando ela não vence (veja credentialNeverExpires) ou quando a Luna ainda não leu a validade. A Luna avisa 14 dias antes, no evento number.credential_expiring.data[].credentialNeverExpiresboolean | nullrequiredtrue: a Meta informou que a autorização não vence. false: ela vence, e credentialExpiresAt traz a data. Nulo: a Luna ainda não leu a validade desta conta.data[].paymentMethodOnMetaboolean | nullrequiredtrue quando a conta tem forma de pagamento cadastrada na Meta, false quando não tem, nulo quando a Luna ainda não leu. Sem forma de pagamento, a Meta para de entregar mensagens de serviço depois da franquia de 1.000 por número por mês. O pagamento é do negócio dono da conta com a Meta, e a Luna não o intermedeia.data[].currencystring | nullrequiredA moeda da conta na Meta, como ela informa (por exemplo BRL). Nulo quando a Luna ainda não leu.data[].createdAtstringrequired
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."
}Check the account payment method at Meta now
POST/v1/business-accounts/{id}/payment-method/check
Reads from Meta whether the account has a payment method on file, without waiting for the hourly read, and returns the result. The webhook notice follows the usual path: number.action_required (reason payment_method_missing) when it is missing and number.action_resolved when it shows up. A read newer than 60 seconds is returned without calling Meta, and the call respects the account call budget.
Path parameters
idstring (uuid)requiredO id da conta de negócio na Luna, o mesmo que GET /v1/business-accounts devolve em id.
Responses
200Success.
idstring (uuid)requiredwabaIdstringrequiredpaymentMethodOnMetaboolean | nullrequiredtrue: a conta tem forma de pagamento na Meta. false: não tem. Nulo: a Luna ainda não conseguiu ler.currencystring | nullrequiredA moeda da conta na Meta, como ela informa. Nulo quando ainda não lida.checkedAtstring | nullrequiredQuando a Luna leu a forma de pagamento da Meta pela última vez, em ISO-8601 UTC. Nulo se nunca leu.refreshedbooleanrequiredtrue quando esta chamada leu na Meta agora. false quando devolveu a leitura que já existia.reasonstringrequiredchecked: leu na Meta agora. recent: a leitura tem menos de 60 segundos e foi devolvida sem chamar a Meta. busy: o orçamento de chamadas da Meta para esta conta está no limite; tente de novo em alguns minutos. failed: a Meta não respondeu ou recusou; o valor devolvido é o anterior.Values:checkedrecentbusyfailed
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": "trial_expired",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"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."
}{
"error": "account_blocked",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. 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 saber o motivo e resolver, escreva para contato@lunahia.com.br."
}{
"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."
}404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
{
"error": "not_found",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Recurso não encontrado."
}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 health of a phone number
GET/v1/numbers/{id}/health
The quality rating, throughput level and daily conversation limit Meta assigns to this number right now, and the changes the platform has observed over time.
Path parameters
idstringrequiredO identificador do número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem.1 to 64 characters · /^[A-Za-z0-9_-]+$/
Responses
200Success.
idstring (uuid)requiredqualityRatingstring | nullrequiredthroughputLevelstring | nullrequiredtetoDeVazaoPorSegundonumber | nullrequiredO teto de envio deste número em mensagens por segundo, quando ele é FIXO e não sobe. Números conectados em coexistência, que continuam funcionando no aplicativo de celular do negócio, têm esse teto fixo pela plataforma da Meta, e ele não acompanha a progressão de throughputLevel. Nulo significa o contrário: este número segue a progressão da Meta, e quem a descreve é throughputLevel. Não é contagem de nada e não muda com o que o número enviou: é a capacidade que a plataforma da Meta concede.sincronizacaoDoHistoricostring | nullrequiredEm que pé está a importação das conversas anteriores do aparelho do negócio, num número conectado em coexistência. São quatro situações e cada uma pede uma reação diferente. Nulo significa que não há importação para este número, e não que ela parou. em_curso significa que ela está acontecendo, e sincronizacaoPrazo diz até quando. 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: não vai concluir, e pedir de novo não muda isso. Atenção ao ler sincronizacaoProgresso junto: cem por cento não significa sucesso, porque a recusa chega com o progresso que já havia sido registrado.sincronizacaoPrazostring | nullrequiredAté quando a importação precisa terminar. Passado esse instante sem concluir, a plataforma da Meta desconecta o negócio final e ele precisa refazer a conexão no aparelho. Sai sempre como instante em UTC, e nunca como texto do tipo faltam tantas horas: um texto desses fica errado na tela de quem a deixou aberta, e quem integra pela API precisa de um valor comparável com o próprio relógio. Nulo quando não há importação em curso conhecida.sincronizacaoProgressonumber | nullrequiredO rótulo de progresso que a plataforma da Meta atribui à importação, de 0 a 100. É um rótulo e não uma contagem: ele chega a 100 igualmente para um aparelho com poucas conversas antigas e para um com muitas, e nada nele cresce com o tamanho do que foi importado. Não use este campo para deduzir quantidade, porque ele não carrega nenhuma. Nulo quando a plataforma da Meta ainda não informou progresso para este número.limiteDiarioDeConversasstring | nullrequiredcodeVerificationStatusstring | nullrequiredcheckedAtstring | nullrequiredtransitionsarray<object>requiredtransitions[].qualityRatingstring | nullrequiredtransitions[].throughputLevelstring | nullrequiredtransitions[].limiteDiarioDeConversasstring | nullrequiredtransitions[].codeVerificationStatusstring | nullrequiredtransitions[].observedAtstringrequired
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."
}404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
{
"error": "not_found",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Recurso não encontrado."
}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 Meta usage of a number or a customer
GET/v1/usage
The usage Meta measures for a number (numberId) or for all the numbers of one of your customers (externalId), passed through as Meta reports it, with each account's currency and no sums. format=csv returns text/csv. Luna only reads and shows it: none of it goes into the Luna subscription.
Query parameters
numberIdstringoptionalO número a consultar: o UUID da Luna (o id de GET /v1/numbers) ou o id da Meta (metaPhoneNumberId). Os dois valem. Mande este ou externalId, nunca os dois.1 to 64 characters · /^[A-Za-z0-9_-]+$/externalIdstringoptionalO rótulo do seu cliente (o externalId do link de conexão): lê o consumo de todos os números dele, cada um na moeda da conta dele. Mande este ou numberId, nunca os dois.1 to 128 charactersstartstring (date-time) | string (date)optionalO começo do período, em ISO 8601 (data ou data e hora, em UTC). Ausente, o primeiro dia do mês corrente.endstring (date-time) | string (date)optionalO fim do período, em ISO 8601. Ausente, agora (arredondado para baixo a cada cinco minutos).granularitystringoptionalO tamanho de cada ponto, no vocabulário da Meta: HALF_HOUR, DAILY (o padrão) ou MONTHLY. A Meta limita o período de cada um, e recusa o que passa do limite dela.default: "DAILY"Values:HALF_HOURDAILYMONTHLYformatstringoptionaljson (o padrão) ou csv. O csv vem em text/csv, uma linha por ponto, com numberId, phoneNumberId e currency em cada linha, para planilha.default: "json"Values:jsoncsv
Responses
200Success.
numberIdstring (uuid) | nullrequiredO id do número na Luna, quando você consultou por numberId. Nulo quando consultou por externalId.phoneNumberIdstring | nullrequiredO id do número na Meta, quando você consultou por numberId. Nulo quando consultou por externalId.externalIdstring | nullrequiredO rótulo do cliente, quando você consultou por externalId. Nulo quando consultou por numberId.startstringrequiredO começo do período consultado, em ISO 8601.endstringrequiredO fim do período consultado, em ISO 8601.granularitystringrequiredValues:HALF_HOURDAILYMONTHLYreadAtstringrequiredQuando a Luna leu isto na Meta; com vários números, a leitura mais antiga. A mesma consulta repetida em até cinco minutos devolve a mesma leitura.noticestringrequiredO aviso que acompanha o consumo: é aproximação, a Meta cobra direto do negócio, e nada daqui entra na assinatura da Luna. Mostre-o junto dos valores.numbersarray<object>requiredOs números cobertos pela consulta, inclusive os que ficaram de fora e os que não tiveram nenhum ponto.numbers[].numberIdstring (uuid)requiredO id do número na Luna.numbers[].phoneNumberIdstringrequiredO id do número na Meta.numbers[].currencystring | nullrequiredA moeda da conta do negócio na Meta. Nulo quando a Luna ainda não a leu.numbers[].readbooleanrequiredtrue quando a Luna leu o consumo deste número. false quando ele ficou de fora, e reason diz por quê.numbers[].reasonstring | nullrequiredPor que o número não foi lido: number_disconnected (você o desconectou) ou phone_not_read_yet (a Luna ainda não leu o telefone dele na Meta). Nulo quando read é true.dataarray<object>requiredOs pontos que a Meta devolveu, de todos os números, cada um com o número e a moeda dele. Sem total: agrupe por numberId, e nunca some currency diferentes.data[].numberIdstring (uuid)requiredO número da Luna a que este ponto pertence.data[].phoneNumberIdstringrequiredO id do mesmo número na Meta.data[].currencystring | nullrequiredA moeda de cost, a da conta do negócio na Meta (por exemplo BRL). Nulo quando a Luna ainda não a leu. Contas de moedas diferentes nunca são somadas.data[].startstring | nullrequiredO começo do ponto, em ISO 8601. Nulo quando a Meta não informou.data[].endstring | nullrequiredO fim do ponto, em ISO 8601. Nulo quando a Meta não informou.data[].pricingCategorystring | nullrequiredA categoria de cobrança, como a Meta a nomeia (por exemplo MARKETING, UTILITY, SERVICE). Novos valores podem aparecer.data[].pricingTypestring | nullrequiredO tipo de cobrança, como a Meta o nomeia (por exemplo REGULAR, FREE_CUSTOMER_SERVICE). Novos valores podem aparecer.data[].tierstring | nullrequiredA faixa de volume da Meta, no formato que ela manda (por exemplo "0:750000"). Nulo quando não veio.data[].countrystring | nullrequiredO país do destinatário, como a Meta informou. Nulo quando não veio.data[].volumenumber | nullrequiredO volume que a Meta mediu neste ponto. É dela, aproximado, e nunca é somado pela Luna.data[].costnumber | nullrequiredO custo aproximado que a Meta aplicou neste ponto, na moeda da conta do negócio na Meta. A fatura da Meta é a referência.
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."
}409The request is well formed, but the resource state does not allow it. The error field says which case it is.
{
"error": "number_disconnected",
"docsUrl": "https://lunahia.com.br/docs/conectar-numero",
"message": "Este número foi desconectado da Luna e não envia mais. O histórico foi preservado. Para voltar a usá-lo, conecte-o de novo com um link de conexão (POST /v1/onboarding/links)."
}422The request is well formed and Luna passed it on, and Meta refused it. The meta field carries what happened, what to do and its original error. Repeating the same request repeats the refusal.
{
"error": "meta_rejected",
"docsUrl": "https://lunahia.com.br/docs/numero-na-meta",
"message": "A Meta recusou esta operação. O campo meta traz o que aconteceu, o que fazer e o erro original dela.",
"meta": {
"codigo": 131030,
"categoria": "nao_entregavel",
"mensagem": "A Meta recusou o pedido.",
"acaoRecomendada": "Confira os campos enviados e tente de novo.",
"original": {
"error": {
"message": "Invalid parameter",
"type": "OAuthException",
"code": 131030,
"fbtrace_id": "AbCdEfGhIjK"
}
}
}
}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."
}{
"error": "management_busy",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "As operações de gestão desta conexão atingiram o limite momentâneo. 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."
}