LunaDocs

Loading search...

PortuguêsSign in to the console
On this page

Phone numbers

Use with AI

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.

Authentication
API key
Required scope
numbers:read

Path parameters

  • idstringrequired
    O 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 | nullrequired
    O recado curto do perfil. Nulo quando não há.
  • addressstring | nullrequired
    O endereço do negócio.
  • descriptionstring | nullrequired
    A descrição do negócio.
  • emailstring | nullrequired
    O e-mail de contato.
  • websitesarray<string>required
    Os sites do negócio. Lista vazia quando não há.
  • verticalstring | nullrequired
    O ramo de atividade, como a Meta o devolve. Texto da Meta, sem lista fechada aqui.
  • profilePictureUrlstring | nullrequired
    O 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.
Field refused, with the reasonJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
  • WWW-Authenticate Always Bearer.
Key refusedJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
Insufficient scopeJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Test key on a route outside test modeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
Does not exist, or is not yoursJSON
{
  "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.
Unavailable in coexistenceJSON
{
  "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."
}
Number disconnected from LunaJSON
{
  "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.
Meta refused the operationJSON
{
  "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-After Seconds to wait before repeating.
Request limitJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
Account management busyJSON
{
  "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.
UnavailableJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

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.

Authentication
API key
Required scope
numbers:write

Path parameters

  • idstringrequired
    O 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

application/json · required

  • aboutstringoptional
    O recado curto. Até 139 caracteres.1 to 139 characters
  • addressstringoptional
    O endereço. Até 256 caracteres.1 to 256 characters
  • descriptionstringoptional
    A descrição. Até 512 caracteres.1 to 512 characters
  • emailstringoptional
    O e-mail de contato. Até 128 caracteres.1 to 128 characters
  • websitesarray<string (uri)>optional
    Até dois sites. A lista inteira substitui a que existe.up to 2 items
  • verticalstringoptional
    O ramo de atividade, no vocabulário da Meta.1 to 64 characters
  • displayNamestringoptional
    Pede à 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 characters
  • profilePictureHandlestringoptional
    O 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>required
    Os campos que a Meta aceitou trocar, pelos nomes que você mandou.
202Accepted: the request was recorded and will be processed.
  • updatedFieldsarray<string>required
    Os campos que a Meta aceitou trocar, pelos nomes que você mandou.
  • displayNameStatusstringrequired
    O nome foi pedido e está em revisão na Meta. O resultado chega no evento number.display_name_reviewed.Values: pending_review
  • pendingDisplayNamestringrequired
    O 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.
Field refused, with the reasonJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
  • WWW-Authenticate Always Bearer.
Key refusedJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
Insufficient scopeJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Free trial endedJSON
{
  "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."
}
Account blocked by HelsenJSON
{
  "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."
}
Test key on a route outside test modeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
Does not exist, or is not yoursJSON
{
  "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.
Unavailable in coexistenceJSON
{
  "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."
}
Number disconnected from LunaJSON
{
  "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.
Content type not readJSON
{
  "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.
Meta refused the operationJSON
{
  "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-After Seconds to wait before repeating.
Request limitJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
Account management busyJSON
{
  "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.
UnavailableJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

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.

Authentication
API key
Required scope
messages:read

Path parameters

  • idstringrequired
    O 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

  • limitintegeroptional
    Quantos por página, de 1 a 100.minimum 1 · maximum 100
  • cursorstringoptional
    O nextCursor da página anterior.1 to 512 characters

Responses

200Success.
  • dataarray<object>required
    Os usuários bloqueados nesta página.
  • data[].waIdstring | nullrequired
    O telefone do usuário bloqueado.
  • data[].userIdstring | nullrequired
    O BSUID do usuário bloqueado.
  • nextCursorstring | nullrequired
    O 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.
Field refused, with the reasonJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
  • WWW-Authenticate Always Bearer.
Key refusedJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
Insufficient scopeJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Test key on a route outside test modeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
Does not exist, or is not yoursJSON
{
  "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.
Number disconnected from LunaJSON
{
  "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.
Meta refused the operationJSON
{
  "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-After Seconds to wait before repeating.
Request limitJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
Account management busyJSON
{
  "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.
UnavailableJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

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.

Authentication
API key
Required scope
messages:write

Path parameters

  • idstringrequired
    O 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

application/json · required

  • usersarray<string>required
    Os usuários a bloquear, de um a cinquenta.1 to 50 items

Responses

200Success.
  • donearray<object>required
    Os usuários que a Meta aceitou bloquear ou desbloquear.
  • done[].inputstring | nullrequired
    O que você pediu, como a Meta o devolveu.
  • done[].waIdstring | nullrequired
    O telefone do usuário na Meta, quando ela o devolve.
  • done[].userIdstring | nullrequired
    O BSUID do usuário, quando a Meta o devolve.
  • done[].reasonsarray<string>required
    Só em failed: o motivo que a Meta deu. Texto dela.
  • failedarray<object>required
    Os que a Meta recusou, cada um com o motivo dela.
  • failed[].inputstring | nullrequired
    O que você pediu, como a Meta o devolveu.
  • failed[].waIdstring | nullrequired
    O telefone do usuário na Meta, quando ela o devolve.
  • failed[].userIdstring | nullrequired
    O BSUID do usuário, quando a Meta o devolve.
  • failed[].reasonsarray<string>required
    Só 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.
Field refused, with the reasonJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
  • WWW-Authenticate Always Bearer.
Key refusedJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
Insufficient scopeJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Free trial endedJSON
{
  "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."
}
Account blocked by HelsenJSON
{
  "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."
}
Test key on a route outside test modeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
Does not exist, or is not yoursJSON
{
  "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.
Number disconnected from LunaJSON
{
  "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.
Content type not readJSON
{
  "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.
Meta refused the operationJSON
{
  "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-After Seconds to wait before repeating.
Request limitJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
Account management busyJSON
{
  "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.
UnavailableJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

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.

Authentication
API key
Required scope
messages:write

Path parameters

  • idstringrequired
    O 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_-]+$/
  • userstringrequired
    O telefone (só dígitos) ou o BSUID do usuário.1 to 160 characters · /^[A-Za-z0-9.]+$/

Responses

200Success.
  • donearray<object>required
    Os usuários que a Meta aceitou bloquear ou desbloquear.
  • done[].inputstring | nullrequired
    O que você pediu, como a Meta o devolveu.
  • done[].waIdstring | nullrequired
    O telefone do usuário na Meta, quando ela o devolve.
  • done[].userIdstring | nullrequired
    O BSUID do usuário, quando a Meta o devolve.
  • done[].reasonsarray<string>required
    Só em failed: o motivo que a Meta deu. Texto dela.
  • failedarray<object>required
    Os que a Meta recusou, cada um com o motivo dela.
  • failed[].inputstring | nullrequired
    O que você pediu, como a Meta o devolveu.
  • failed[].waIdstring | nullrequired
    O telefone do usuário na Meta, quando ela o devolve.
  • failed[].userIdstring | nullrequired
    O BSUID do usuário, quando a Meta o devolve.
  • failed[].reasonsarray<string>required
    Só 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.
Field refused, with the reasonJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
  • WWW-Authenticate Always Bearer.
Key refusedJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
Insufficient scopeJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Test key on a route outside test modeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
Does not exist, or is not yoursJSON
{
  "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.
Number disconnected from LunaJSON
{
  "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.
Meta refused the operationJSON
{
  "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-After Seconds to wait before repeating.
Request limitJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
Account management busyJSON
{
  "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.
UnavailableJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

List the QR codes

GET/v1/numbers/{id}/qr-codes

The codes that exist on this number, with each one's short link.

Authentication
API key
Required scope
numbers:read

Path parameters

  • idstringrequired
    O 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>required
    Os códigos do número.
  • data[].codestringrequired
    O código do QR, que vai no caminho de DELETE.
  • data[].prefilledMessagestring | nullrequired
    A mensagem que já vem escrita quando o contato abre a conversa.
  • data[].linkstring | nullrequired
    O link curto (wa.me) que abre a mesma conversa.
  • data[].imageUrlstring | nullrequired
    O 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.
Field refused, with the reasonJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
  • WWW-Authenticate Always Bearer.
Key refusedJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
Insufficient scopeJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Test key on a route outside test modeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
Does not exist, or is not yoursJSON
{
  "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.
Number disconnected from LunaJSON
{
  "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.
Meta refused the operationJSON
{
  "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-After Seconds to wait before repeating.
Request limitJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
Account management busyJSON
{
  "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.
UnavailableJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

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.

Authentication
API key
Required scope
numbers:write

Path parameters

  • idstringrequired
    O 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

application/json · required

  • prefilledMessagestringrequired
    A mensagem que já vem escrita. Até 140 caracteres, o limite da Meta, que está a confirmar na doc dela.1 to 140 characters
  • imageFormatstringoptional
    Peça a imagem do QR em PNG ou SVG. Sem isto, só o código e o link voltam.Values: PNG SVG

Responses

201Created.
  • codestringrequired
    O código do QR, que vai no caminho de DELETE.
  • prefilledMessagestring | nullrequired
    A mensagem que já vem escrita quando o contato abre a conversa.
  • linkstring | nullrequired
    O link curto (wa.me) que abre a mesma conversa.
  • imageUrlstring | nullrequired
    O 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.
Field refused, with the reasonJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
  • WWW-Authenticate Always Bearer.
Key refusedJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
Insufficient scopeJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Free trial endedJSON
{
  "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."
}
Account blocked by HelsenJSON
{
  "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."
}
Test key on a route outside test modeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
Does not exist, or is not yoursJSON
{
  "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.
Number disconnected from LunaJSON
{
  "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.
Content type not readJSON
{
  "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.
Meta refused the operationJSON
{
  "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-After Seconds to wait before repeating.
Request limitJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
Account management busyJSON
{
  "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.
UnavailableJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

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.

Authentication
API key
Required scope
numbers:write

Path parameters

  • idstringrequired
    O 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_-]+$/
  • codestringrequired
    O 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.
Field refused, with the reasonJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
  • WWW-Authenticate Always Bearer.
Key refusedJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
Insufficient scopeJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Test key on a route outside test modeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
Does not exist, or is not yoursJSON
{
  "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.
Number disconnected from LunaJSON
{
  "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.
Meta refused the operationJSON
{
  "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-After Seconds to wait before repeating.
Request limitJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
Account management busyJSON
{
  "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.
UnavailableJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

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.

Authentication
API key
Required scope
onboarding:write

Responses

201Created.
  • sessionIdstring (uuid)required
  • statestringrequired
  • configIdstringrequired
  • sdkVersionstringrequired
    A 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.
  • csrfStatestringrequired
  • expiresAtstringrequired
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
  • WWW-Authenticate Always Bearer.
Key refusedJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
Insufficient scopeJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Account not yet released to connectJSON
{
  "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"
  ]
}
Free trial endedJSON
{
  "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."
}
Account blocked by HelsenJSON
{
  "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."
}
Test key on a route outside test modeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
409The request is well formed, but the resource state does not allow it. The error field says which case it is.
The account is already at its number capacityJSON
{
  "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-After Seconds to wait before repeating.
Request limitJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
UnavailableJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Read a connection session

GET/v1/onboarding/sessions/{id}

The session's current state and the matching guidance text, ready to display.

Authentication
API key
Required scope
onboarding:write

Path parameters

  • idstring (uuid)required

Responses

200Success.
  • sessionIdstring (uuid)required
  • statestringrequired
  • orientacaostringrequired
  • terminalbooleanrequired
  • proximoPassostring | nullrequired
  • attemptCountintegerrequired
  • nextAttemptAtstring | nullrequired
  • retryNotBeforestring | nullrequired
  • expiresAtstringrequired
  • createdAtstringrequired
  • updatedAtstringrequired
400The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.
Field refused, with the reasonJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
  • WWW-Authenticate Always Bearer.
Key refusedJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
Insufficient scopeJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Test key on a route outside test modeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
Does not exist, or is not yoursJSON
{
  "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-After Seconds to wait before repeating.
Request limitJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
UnavailableJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

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.

Authentication
API key
Required scope
onboarding:write

Path parameters

  • idstring (uuid)required

Request body

application/json · required

  • csrfStatestringrequired
  • currentStepstring | nulloptional
    1 to 120 characters
  • errorCodeinteger | nulloptional
  • errorMessagestring | nulloptional

Responses

200Success.
  • sessionIdstring (uuid)required
  • statestringrequired
  • orientacaostringrequired
  • abandonedAtStepstring | nullrequired
400The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.
Field refused, with the reasonJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
  • WWW-Authenticate Always Bearer.
Key refusedJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
Insufficient scopeJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Test key on a route outside test modeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
Does not exist, or is not yoursJSON
{
  "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.
Content type not readJSON
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
429Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.
  • Retry-After Seconds to wait before repeating.
Request limitJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
UnavailableJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

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.

Authentication
API key
Required scope
onboarding:write

Path parameters

  • idstring (uuid)required

Request body

application/json · required

  • codestringrequired
  • csrfStatestringrequired
  • wabaIdstring | nulloptional
  • phoneNumberIdstring | nulloptional
  • businessIdstring | nulloptional

Responses

200Success.
  • sessionIdstring (uuid)required
  • statestringrequired
  • orientacaostringrequired
  • terminalbooleanrequired
  • proximoPassostring | nullrequired
  • motivostring | nullrequired
  • podeRetentarbooleanrequired
  • wabaIdstring | nullrequired
  • phoneNumberIdstring | nullrequired
400The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.
Field refused, with the reasonJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
  • WWW-Authenticate Always Bearer.
Key refusedJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
Insufficient scopeJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Free trial endedJSON
{
  "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."
}
Account blocked by HelsenJSON
{
  "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."
}
Test key on a route outside test modeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
Does not exist, or is not yoursJSON
{
  "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.
Content type not readJSON
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
429Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.
  • Retry-After Seconds to wait before repeating.
Request limitJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
UnavailableJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

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.

Authentication
API key
Required scope
numbers:read

Query parameters

  • externalIdstringoptional
    O rótulo que você deu ao seu cliente. Igualdade exata; rótulo sem número devolve lista vazia.1 to 128 characters
  • statestringoptional
    O estado do número (state): PENDING, REGISTER_SENT, REGISTERED, PIN_REQUIRED, BLOCKED ou DISCONNECTED.Values: PENDING REGISTER_SENT REGISTERED PIN_REQUIRED BLOCKED DISCONNECTED
  • qstringoptional
    Busca 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 characters
  • wabaIdstringoptional
    O 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 characters
  • qualityRatingstringoptional
    A 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: GREEN YELLOW RED NA UNKNOWN
  • connectionStatusstringoptional
    Só os números com este connection.status: connected, connecting, action_required ou disconnected.Values: connected connecting action_required disconnected
  • readystringoptional
    true: só os números prontos para enviar e receber. false: só os que ainda não estão.Values: true false
  • canSendstringoptional
    true: só os números por onde enviar funciona agora (connection.canSend). false: só os que não.Values: true false
  • limitintegeroptional
    Quantos números por página: de 1 a 100, 50 se omitido.minimum 1 · maximum 100
  • cursorstringoptional
    O nextCursor da resposta anterior. Opaco: carrega posição, não contagem.up to 256 characters

Responses

200Success.
  • dataarray<object>required
  • data[].idstring (uuid)required
  • data[].metaPhoneNumberIdstringrequired
  • data[].displayNumberstring | nullrequired
  • data[].statestringrequired
  • data[].retryNotBeforestring | nullrequired
  • data[].podeRetentarbooleanrequired
  • data[].qualityRatingstring | nullrequired
  • data[].throughputLevelstring | nullrequired
    A 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 | nullrequired
    O 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 | nullrequired
  • data[].displayNamestring | nullrequired
    O 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 | nullrequired
    O 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 | nullrequired
    O 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[].autoReadbooleanrequired
    Quando 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 | nullrequired
    O 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 | nullrequired
    Um 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 | nullrequired
    O 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 | nullrequired
    Quando 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[].wabaobjectrequired
    O 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 | nullrequired
    O identificador da conta de negócio do número na Meta (WABA).
  • data[].waba.restrictedbooleanrequired
    true quando a Meta avisou uma restrição da conta e ela ainda vale. Os detalhes estão em GET /v1/business-accounts.
  • data[].waba.disabledbooleanrequired
    true quando a Meta avisou que desativou a conta.
  • data[].waba.credentialExpiresAtstring | nullrequired
    Quando 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 | nullrequired
    true: 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 | nullrequired
    true: 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 | nullrequired
    A moeda da conta na Meta, como ela informa (por exemplo BRL). Nulo quando ainda não lida.
  • data[].readybooleanrequired
    true 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[].connectionobjectrequired
    O 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.statusstringrequired
    O 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: connected connecting action_required disconnected
  • data[].connection.canSendbooleanrequired
    Se 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>required
    Por 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[].codestringrequired
    O código do motivo, para o seu código comparar. Novos códigos podem aparecer.
  • data[].connection.reasons[].messagestringrequired
    O que está acontecendo, em português, pronto para repassar ao seu cliente.
  • data[].connection.reasons[].solutionstringrequired
    O que fazer a respeito, em português.
  • data[].connection.reasons[].actionstring | nullrequired
    A 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_pin reconnect reconnect_link meta_manager wait contact_helsen
  • data[].connection.reasons[].actionUrlstring | nullrequired
    O endereço da conta no WhatsApp Manager da Meta. Só vem quando action é meta_manager.
  • data[].connection.reasons[].docsUrlstring | nullrequired
    O guia do site que explica o motivo.
  • data[].connection.reasons[].sincestring | nullrequired
    Desde 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>required
    O 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>required
    As 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[].actionstringrequired
    Values: disconnect reconnect reconnect_link send_pin edit_label
  • data[].blockedActions[].messagestringrequired
    Por que a ação não está disponível agora, em português, pronto para mostrar.
  • data[].createdAtstringrequired
  • data[].updatedAtstringrequired
  • nextCursorstring | nullrequired
    Mande 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.
Field refused, with the reasonJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
  • WWW-Authenticate Always Bearer.
Key refusedJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
Insufficient scopeJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Test key on a route outside test modeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
429Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.
  • Retry-After Seconds to wait before repeating.
Request limitJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
UnavailableJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Read one phone number

GET/v1/numbers/{id}

One number, with everything the listing carries plus the health of its connection to Meta.

Authentication
API key
Required scope
numbers:read

Path parameters

  • idstringrequired
    O 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)required
  • metaPhoneNumberIdstringrequired
  • displayNumberstring | nullrequired
  • statestringrequired
  • retryNotBeforestring | nullrequired
  • podeRetentarbooleanrequired
  • qualityRatingstring | nullrequired
  • throughputLevelstring | nullrequired
    A 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 | nullrequired
    O 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 | nullrequired
  • displayNamestring | nullrequired
    O 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 | nullrequired
    O 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 | nullrequired
    O 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.
  • autoReadbooleanrequired
    Quando 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 | nullrequired
    O 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 | nullrequired
    Um 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 | nullrequired
    O 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 | nullrequired
    Quando 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.
  • wabaobjectrequired
    O 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 | nullrequired
    O identificador da conta de negócio do número na Meta (WABA).
  • waba.restrictedbooleanrequired
    true quando a Meta avisou uma restrição da conta e ela ainda vale. Os detalhes estão em GET /v1/business-accounts.
  • waba.disabledbooleanrequired
    true quando a Meta avisou que desativou a conta.
  • waba.credentialExpiresAtstring | nullrequired
    Quando 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 | nullrequired
    true: a Meta informou que a autorização não vence. false: vence, e credentialExpiresAt traz a data. Nulo: ainda não lida.
  • waba.paymentMethodOnMetaboolean | nullrequired
    true: 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 | nullrequired
    A moeda da conta na Meta, como ela informa (por exemplo BRL). Nulo quando ainda não lida.
  • readybooleanrequired
    true 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.
  • connectionobjectrequired
  • connection.statusstringrequired
    O 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: connected connecting action_required disconnected
  • connection.canSendbooleanrequired
    Se 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>required
    Por 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[].codestringrequired
    O código do motivo, para o seu código comparar. Novos códigos podem aparecer.
  • connection.reasons[].messagestringrequired
    O que está acontecendo, em português, pronto para repassar ao seu cliente.
  • connection.reasons[].solutionstringrequired
    O que fazer a respeito, em português.
  • connection.reasons[].actionstring | nullrequired
    A 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_pin reconnect reconnect_link meta_manager wait contact_helsen
  • connection.reasons[].actionUrlstring | nullrequired
    O endereço da conta no WhatsApp Manager da Meta. Só vem quando action é meta_manager.
  • connection.reasons[].docsUrlstring | nullrequired
    O guia do site que explica o motivo.
  • connection.reasons[].sincestring | nullrequired
    Desde 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>required
    Os 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[].keystringrequired
    Values: authorized receiving registered ready
  • connection.steps[].labelstringrequired
    O nome do passo, em português. Em coexistência o terceiro passo se chama Número vinculado.
  • connection.steps[].statusstringrequired
    Values: done current pending
  • allowedActionsarray<string>required
    O 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>required
    As 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[].actionstringrequired
    Values: disconnect reconnect reconnect_link send_pin edit_label
  • blockedActions[].messagestringrequired
    Por que a ação não está disponível agora, em português, pronto para mostrar.
  • createdAtstringrequired
  • updatedAtstringrequired
  • tetoDeVazaoPorSegundonumber | nullrequired
    O 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 | nullrequired
    Em 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 | nullrequired
    Até 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 | nullrequired
    O 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 | nullrequired
    Quando 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 | nullrequired
    O 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).
  • podeReconectarbooleanrequired
    Se a autorização deste número admite reconexão. Quando for true, POST /v1/onboarding/reconnect abre a sessão que a substitui.
  • coexistencebooleanrequired
    true 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.
Field refused, with the reasonJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
  • WWW-Authenticate Always Bearer.
Key refusedJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
Insufficient scopeJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Test key on a route outside test modeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
Does not exist, or is not yoursJSON
{
  "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-After Seconds to wait before repeating.
Request limitJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
UnavailableJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

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.

Authentication
API key
Required scope
numbers:write

Path parameters

  • idstringrequired
    O 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

application/json · required

  • externalIdstring | nulloptional
    O seu identificador para o cliente dono do número (1 a 128 caracteres). null limpa.1 to 128 characters
  • labelstring | nulloptional
    Um nome livre e curto para reconhecer o número (1 a 128 caracteres). null limpa.1 to 128 characters
  • autoReadbooleanoptional
    true: 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)required
  • metaPhoneNumberIdstringrequired
  • displayNumberstring | nullrequired
  • statestringrequired
  • retryNotBeforestring | nullrequired
  • podeRetentarbooleanrequired
  • qualityRatingstring | nullrequired
  • throughputLevelstring | nullrequired
    A 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 | nullrequired
    O 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 | nullrequired
  • displayNamestring | nullrequired
    O 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 | nullrequired
    O 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 | nullrequired
    O 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.
  • autoReadbooleanrequired
    Quando 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 | nullrequired
    O 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 | nullrequired
    Um 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 | nullrequired
    O 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 | nullrequired
    Quando 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.
  • wabaobjectrequired
    O 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 | nullrequired
    O identificador da conta de negócio do número na Meta (WABA).
  • waba.restrictedbooleanrequired
    true quando a Meta avisou uma restrição da conta e ela ainda vale. Os detalhes estão em GET /v1/business-accounts.
  • waba.disabledbooleanrequired
    true quando a Meta avisou que desativou a conta.
  • waba.credentialExpiresAtstring | nullrequired
    Quando 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 | nullrequired
    true: a Meta informou que a autorização não vence. false: vence, e credentialExpiresAt traz a data. Nulo: ainda não lida.
  • waba.paymentMethodOnMetaboolean | nullrequired
    true: 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 | nullrequired
    A moeda da conta na Meta, como ela informa (por exemplo BRL). Nulo quando ainda não lida.
  • readybooleanrequired
    true 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.
  • connectionobjectrequired
  • connection.statusstringrequired
    O 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: connected connecting action_required disconnected
  • connection.canSendbooleanrequired
    Se 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>required
    Por 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[].codestringrequired
    O código do motivo, para o seu código comparar. Novos códigos podem aparecer.
  • connection.reasons[].messagestringrequired
    O que está acontecendo, em português, pronto para repassar ao seu cliente.
  • connection.reasons[].solutionstringrequired
    O que fazer a respeito, em português.
  • connection.reasons[].actionstring | nullrequired
    A 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_pin reconnect reconnect_link meta_manager wait contact_helsen
  • connection.reasons[].actionUrlstring | nullrequired
    O endereço da conta no WhatsApp Manager da Meta. Só vem quando action é meta_manager.
  • connection.reasons[].docsUrlstring | nullrequired
    O guia do site que explica o motivo.
  • connection.reasons[].sincestring | nullrequired
    Desde 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>required
    Os 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[].keystringrequired
    Values: authorized receiving registered ready
  • connection.steps[].labelstringrequired
    O nome do passo, em português. Em coexistência o terceiro passo se chama Número vinculado.
  • connection.steps[].statusstringrequired
    Values: done current pending
  • allowedActionsarray<string>required
    O 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>required
    As 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[].actionstringrequired
    Values: disconnect reconnect reconnect_link send_pin edit_label
  • blockedActions[].messagestringrequired
    Por que a ação não está disponível agora, em português, pronto para mostrar.
  • createdAtstringrequired
  • updatedAtstringrequired
  • tetoDeVazaoPorSegundonumber | nullrequired
    O 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 | nullrequired
    Em 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 | nullrequired
    Até 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 | nullrequired
    O 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 | nullrequired
    Quando 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 | nullrequired
    O 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).
  • podeReconectarbooleanrequired
    Se a autorização deste número admite reconexão. Quando for true, POST /v1/onboarding/reconnect abre a sessão que a substitui.
  • coexistencebooleanrequired
    true 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.
Field refused, with the reasonJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
  • WWW-Authenticate Always Bearer.
Key refusedJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
Insufficient scopeJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Free trial endedJSON
{
  "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."
}
Account blocked by HelsenJSON
{
  "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."
}
Test key on a route outside test modeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
Does not exist, or is not yoursJSON
{
  "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.
Content type not readJSON
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
429Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.
  • Retry-After Seconds to wait before repeating.
Request limitJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
UnavailableJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

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.

Authentication
API key
Required scope
numbers:write

Path parameters

  • idstringrequired
    O 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.
Field refused, with the reasonJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
  • WWW-Authenticate Always Bearer.
Key refusedJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
Insufficient scopeJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Test key on a route outside test modeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
Does not exist, or is not yoursJSON
{
  "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-After Seconds to wait before repeating.
Request limitJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
UnavailableJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

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.

Authentication
API key
Required scope
onboarding:write

Path parameters

  • idstringrequired
    O 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

application/json · required

  • pinstringrequired
    O 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)required
    O identificador deste número na Luna.
  • statestringrequired
    O 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.
Field refused, with the reasonJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
  • WWW-Authenticate Always Bearer.
Key refusedJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
Insufficient scopeJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Free trial endedJSON
{
  "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."
}
Account blocked by HelsenJSON
{
  "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."
}
Test key on a route outside test modeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
Does not exist, or is not yoursJSON
{
  "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.
The number does not ask for a PINJSON
{
  "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á."
}
Registration attempts reservedJSON
{
  "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"
}
The account is already at its number capacityJSON
{
  "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.
Content type not readJSON
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
429Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.
  • Retry-After Seconds to wait before repeating.
Request limitJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
UnavailableJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

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.

Authentication
API key
Required scope
onboarding:write

Request body

application/json · required

  • numberIdstringrequired
    O 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)required
  • statestringrequired
  • configIdstringrequired
  • sdkVersionstringrequired
    A 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.
  • csrfStatestringrequired
  • expiresAtstringrequired
400The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.
Field refused, with the reasonJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
  • WWW-Authenticate Always Bearer.
Key refusedJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
Insufficient scopeJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Account not yet released to connectJSON
{
  "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"
  ]
}
Free trial endedJSON
{
  "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."
}
Account blocked by HelsenJSON
{
  "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."
}
Test key on a route outside test modeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
Does not exist, or is not yoursJSON
{
  "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.
The authorization does not allow reconnectionJSON
{
  "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"
}
The account is already at its number capacityJSON
{
  "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.
Content type not readJSON
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
429Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.
  • Retry-After Seconds to wait before repeating.
Request limitJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
UnavailableJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

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.

Authentication
API key
Required scope
numbers:read

Responses

200Success.
  • dataarray<object>required
  • data[].idstring (uuid)required
  • data[].wabaIdstringrequired
  • data[].numbersarray<string>required
  • data[].namestring | nullrequired
    O nome da conta de WhatsApp Business como a Meta o informa. Nulo enquanto a Luna ainda não o leu.
  • data[].managerUrlstringrequired
    O endereço desta conta no WhatsApp Manager da Meta, onde o dono da conta resolve pagamento, verificação e restrições.
  • data[].phoneNumbersarray<object>required
    Os 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)required
    O id do número na Luna, o mesmo de GET /v1/numbers.
  • data[].phoneNumbers[].displayNumberstring | nullrequired
    O número como se lê no telefone, ou nulo enquanto a Luna não o leu.
  • data[].phoneNumbers[].externalIdstring | nullrequired
    O seu rótulo para o cliente dono do número.
  • data[].phoneNumbers[].labelstring | nullrequired
    O nome que você deu ao número.
  • data[].statusobjectrequired
    O último estado de saúde conhecido da conta.
  • data[].status.restrictedbooleanrequired
    true 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>required
    As 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 | nullrequired
  • data[].status.restrictions[].expirationstring | nullrequired
  • data[].status.restrictions[].remediationstring | nullrequired
  • data[].status.disabledbooleanrequired
    true 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 | nullrequired
    O 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 | nullrequired
    Quando chegou o aviso de saúde mais recente, ou nulo se nunca chegou.
  • data[].credentialExpiresAtstring | nullrequired
    Quando 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 | nullrequired
    true: 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 | nullrequired
    true 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 | nullrequired
    A 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-Authenticate Always Bearer.
Key refusedJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
Insufficient scopeJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Test key on a route outside test modeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
429Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.
  • Retry-After Seconds to wait before repeating.
Request limitJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
UnavailableJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

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.

Authentication
API key
Required scope
numbers:read

Path parameters

  • idstring (uuid)required
    O id da conta de negócio na Luna, o mesmo que GET /v1/business-accounts devolve em id.

Responses

200Success.
  • idstring (uuid)required
  • wabaIdstringrequired
  • paymentMethodOnMetaboolean | nullrequired
    true: a conta tem forma de pagamento na Meta. false: não tem. Nulo: a Luna ainda não conseguiu ler.
  • currencystring | nullrequired
    A moeda da conta na Meta, como ela informa. Nulo quando ainda não lida.
  • checkedAtstring | nullrequired
    Quando a Luna leu a forma de pagamento da Meta pela última vez, em ISO-8601 UTC. Nulo se nunca leu.
  • refreshedbooleanrequired
    true quando esta chamada leu na Meta agora. false quando devolveu a leitura que já existia.
  • reasonstringrequired
    checked: 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: checked recent busy failed
400The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.
Field refused, with the reasonJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
  • WWW-Authenticate Always Bearer.
Key refusedJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
Insufficient scopeJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Free trial endedJSON
{
  "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."
}
Account blocked by HelsenJSON
{
  "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."
}
Test key on a route outside test modeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
Does not exist, or is not yoursJSON
{
  "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-After Seconds to wait before repeating.
Request limitJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
UnavailableJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Read the 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.

Authentication
API key
Required scope
numbers:read

Path parameters

  • idstringrequired
    O 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)required
  • qualityRatingstring | nullrequired
  • throughputLevelstring | nullrequired
  • tetoDeVazaoPorSegundonumber | nullrequired
    O 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 | nullrequired
    Em 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 | nullrequired
    Até 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 | nullrequired
    O 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 | nullrequired
  • codeVerificationStatusstring | nullrequired
  • checkedAtstring | nullrequired
  • transitionsarray<object>required
  • transitions[].qualityRatingstring | nullrequired
  • transitions[].throughputLevelstring | nullrequired
  • transitions[].limiteDiarioDeConversasstring | nullrequired
  • transitions[].codeVerificationStatusstring | nullrequired
  • transitions[].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.
Field refused, with the reasonJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
  • WWW-Authenticate Always Bearer.
Key refusedJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
Insufficient scopeJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Test key on a route outside test modeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
Does not exist, or is not yoursJSON
{
  "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-After Seconds to wait before repeating.
Request limitJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
UnavailableJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Read the 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.

Authentication
API key
Required scope
numbers:read

Query parameters

  • numberIdstringoptional
    O 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_-]+$/
  • externalIdstringoptional
    O 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 characters
  • startstring (date-time) | string (date)optional
    O 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)optional
    O fim do período, em ISO 8601. Ausente, agora (arredondado para baixo a cada cinco minutos).
  • granularitystringoptional
    O 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_HOUR DAILY MONTHLY
  • formatstringoptional
    json (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: json csv

Responses

200Success.
  • numberIdstring (uuid) | nullrequired
    O id do número na Luna, quando você consultou por numberId. Nulo quando consultou por externalId.
  • phoneNumberIdstring | nullrequired
    O id do número na Meta, quando você consultou por numberId. Nulo quando consultou por externalId.
  • externalIdstring | nullrequired
    O rótulo do cliente, quando você consultou por externalId. Nulo quando consultou por numberId.
  • startstringrequired
    O começo do período consultado, em ISO 8601.
  • endstringrequired
    O fim do período consultado, em ISO 8601.
  • granularitystringrequired
    Values: HALF_HOUR DAILY MONTHLY
  • readAtstringrequired
    Quando 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.
  • noticestringrequired
    O 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>required
    Os números cobertos pela consulta, inclusive os que ficaram de fora e os que não tiveram nenhum ponto.
  • numbers[].numberIdstring (uuid)required
    O id do número na Luna.
  • numbers[].phoneNumberIdstringrequired
    O id do número na Meta.
  • numbers[].currencystring | nullrequired
    A moeda da conta do negócio na Meta. Nulo quando a Luna ainda não a leu.
  • numbers[].readbooleanrequired
    true quando a Luna leu o consumo deste número. false quando ele ficou de fora, e reason diz por quê.
  • numbers[].reasonstring | nullrequired
    Por 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>required
    Os 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)required
    O número da Luna a que este ponto pertence.
  • data[].phoneNumberIdstringrequired
    O id do mesmo número na Meta.
  • data[].currencystring | nullrequired
    A 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 | nullrequired
    O começo do ponto, em ISO 8601. Nulo quando a Meta não informou.
  • data[].endstring | nullrequired
    O fim do ponto, em ISO 8601. Nulo quando a Meta não informou.
  • data[].pricingCategorystring | nullrequired
    A categoria de cobrança, como a Meta a nomeia (por exemplo MARKETING, UTILITY, SERVICE). Novos valores podem aparecer.
  • data[].pricingTypestring | nullrequired
    O tipo de cobrança, como a Meta o nomeia (por exemplo REGULAR, FREE_CUSTOMER_SERVICE). Novos valores podem aparecer.
  • data[].tierstring | nullrequired
    A faixa de volume da Meta, no formato que ela manda (por exemplo "0:750000"). Nulo quando não veio.
  • data[].countrystring | nullrequired
    O país do destinatário, como a Meta informou. Nulo quando não veio.
  • data[].volumenumber | nullrequired
    O volume que a Meta mediu neste ponto. É dela, aproximado, e nunca é somado pela Luna.
  • data[].costnumber | nullrequired
    O 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.
Field refused, with the reasonJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
  • WWW-Authenticate Always Bearer.
Key refusedJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
Insufficient scopeJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Test key on a route outside test modeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
409The request is well formed, but the resource state does not allow it. The error field says which case it is.
Number disconnected from LunaJSON
{
  "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.
Meta refused the operationJSON
{
  "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-After Seconds to wait before repeating.
Request limitJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
Account management busyJSON
{
  "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.
UnavailableJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}