LunaDocs

Carregando a busca...

EnglishEntrar no console
Nesta página

Números

Usar com IA

Os números conectados: conectar, ver estado, qualidade e vazão, editar e desconectar.

Migrar um número que já está na API de outro provedor é caminho suportado, e não exige número novo nem perda do número atual. Um número já registrado na Cloud API de outro provedor quase sempre tem verificação em duas etapas configurada lá, e a Meta exige o PIN existente para registrá-lo de novo: não há endpoint para ler nem para desligar esse PIN, então ele precisa vir do negócio final. Informe o PIN em POST /v1/numbers/{id}/pin, ou peça ao negócio final que desligue a verificação em duas etapas no WhatsApp Manager dele. Os outros pré-requisitos também são do lado dele: ser o dono da conta de WhatsApp Business e ter o número liberado no provedor anterior.

Um número que hoje só existe no WhatsApp Business App, o aplicativo de celular, é o outro caso, e a Meta o chama de coexistência. Ele nunca passou por API nenhuma. A conexão parte da mesma janela da Meta, e a opção só aparece quando a conta do negócio final está habilitada para isso do lado da Meta e o aplicativo no aparelho está na versão 2.24.17 ou maior.

Conectado assim, o número continua funcionando no aplicativo de celular, e as conversas anteriores do aparelho são importadas para a plataforma: elas aparecem em GET /v1/messages junto das novas. A importação tem prazo para concluir, e quem diz onde ela está é GET /v1/numbers/{id}, nos campos sincronizacaoDoHistorico e sincronizacaoPrazo. O mesmo recurso traz tetoDeVazaoPorSegundo, que é o teto fixo de vazão de um número em coexistência e não sobe com o tempo. E o que o dono do negócio responder pelo aplicativo de celular também chega, na conversa do destinatário.

Ler o perfil do negócio

GET/v1/numbers/{id}/profile

O perfil que o contato vê no WhatsApp: recado, endereço, descrição, e-mail, sites, ramo e a foto. Não vale para número em coexistência.

Autenticação
Chave de API
Escopo exigido
numbers:read

Parâmetros de caminho

  • idstringobrigatório
    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 a 64 caracteres · /^[A-Za-z0-9_-]+$/

Respostas

200Sucesso.
  • aboutstring | nullobrigatório
    O recado curto do perfil. Nulo quando não há.
  • addressstring | nullobrigatório
    O endereço do negócio.
  • descriptionstring | nullobrigatório
    A descrição do negócio.
  • emailstring | nullobrigatório
    O e-mail de contato.
  • websitesarray<string>obrigatório
    Os sites do negócio. Lista vazia quando não há.
  • verticalstring | nullobrigatório
    O ramo de atividade, como a Meta o devolve. Texto da Meta, sem lista fechada aqui.
  • profilePictureUrlstring | nullobrigatório
    O endereço da foto do perfil. É da Meta e pode expirar: baixe o arquivo se precisar guardá-lo.
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
Campo recusado, com o motivoJSON
{
  "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."
    }
  ]
}
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "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"
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "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."
}
404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
Não existe, ou não é seuJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
409O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.
Indisponível em coexistênciaJSON
{
  "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."
}
Número desconectado da 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)."
}
422O pedido está bem formado e a Luna o repassou, e a Meta recusou. O campo meta traz o que aconteceu, o que fazer e o erro original dela. Repetir o mesmo pedido repete a recusa.
A Meta recusou a operaçãoJSON
{
  "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"
      }
    }
  }
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
Gestão da conta ocupadaJSON
{
  "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."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Mudar o perfil do negócio

PATCH/v1/numbers/{id}/profile

Troca os campos que você mandar, e deixa os outros como estão. Com displayName, pede a mudança do nome de exibição e responde 202: o nome fica em revisão na Meta. Não vale para número em coexistência.

Autenticação
Chave de API
Escopo exigido
numbers:write

Parâmetros de caminho

  • idstringobrigatório
    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 a 64 caracteres · /^[A-Za-z0-9_-]+$/

Corpo da requisição

application/json · obrigatório

  • aboutstringopcional
    O recado curto. Até 139 caracteres.1 a 139 caracteres
  • addressstringopcional
    O endereço. Até 256 caracteres.1 a 256 caracteres
  • descriptionstringopcional
    A descrição. Até 512 caracteres.1 a 512 caracteres
  • emailstringopcional
    O e-mail de contato. Até 128 caracteres.1 a 128 caracteres
  • websitesarray<string (uri)>opcional
    Até dois sites. A lista inteira substitui a que existe.até 2 itens
  • verticalstringopcional
    O ramo de atividade, no vocabulário da Meta.1 a 64 caracteres
  • displayNamestringopcional
    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 a 512 caracteres
  • profilePictureHandlestringopcional
    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 a 1024 caracteres

Respostas

200Sucesso.
  • updatedFieldsarray<string>obrigatório
    Os campos que a Meta aceitou trocar, pelos nomes que você mandou.
202Aceito: o pedido foi registrado e será processado.
  • updatedFieldsarray<string>obrigatório
    Os campos que a Meta aceitou trocar, pelos nomes que você mandou.
  • displayNameStatusstringobrigatório
    O nome foi pedido e está em revisão na Meta. O resultado chega no evento number.display_name_reviewed.Valores: pending_review
  • pendingDisplayNamestringobrigatório
    O nome que você pediu.
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
Campo recusado, com o motivoJSON
{
  "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."
    }
  ]
}
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "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"
}
Teste grátis terminadoJSON
{
  "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."
}
Conta bloqueada pela 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."
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "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."
}
404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
Não existe, ou não é seuJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
409O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.
Indisponível em coexistênciaJSON
{
  "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."
}
Número desconectado da 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)."
}
415O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.
Tipo de conteúdo não lidoJSON
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
422O pedido está bem formado e a Luna o repassou, e a Meta recusou. O campo meta traz o que aconteceu, o que fazer e o erro original dela. Repetir o mesmo pedido repete a recusa.
A Meta recusou a operaçãoJSON
{
  "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"
      }
    }
  }
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
Gestão da conta ocupadaJSON
{
  "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."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Listar os usuários bloqueados

GET/v1/numbers/{id}/blocked-users

Quem este número bloqueou, em páginas. O cursor é o da Meta, e não muda de forma.

Autenticação
Chave de API
Escopo exigido
messages:read

Parâmetros de caminho

  • idstringobrigatório
    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 a 64 caracteres · /^[A-Za-z0-9_-]+$/

Parâmetros de consulta

  • limitintegeropcional
    Quantos por página, de 1 a 100.mínimo 1 · máximo 100
  • cursorstringopcional
    O nextCursor da página anterior.1 a 512 caracteres

Respostas

200Sucesso.
  • dataarray<object>obrigatório
    Os usuários bloqueados nesta página.
  • data[].waIdstring | nullobrigatório
    O telefone do usuário bloqueado.
  • data[].userIdstring | nullobrigatório
    O BSUID do usuário bloqueado.
  • nextCursorstring | nullobrigatório
    O cursor da próxima página, como a Meta o deu. Nulo quando acabou.
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
Campo recusado, com o motivoJSON
{
  "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."
    }
  ]
}
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "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"
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "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."
}
404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
Não existe, ou não é seuJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
409O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.
Número desconectado da 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)."
}
422O pedido está bem formado e a Luna o repassou, e a Meta recusou. O campo meta traz o que aconteceu, o que fazer e o erro original dela. Repetir o mesmo pedido repete a recusa.
A Meta recusou a operaçãoJSON
{
  "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"
      }
    }
  }
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
Gestão da conta ocupadaJSON
{
  "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."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Bloquear usuários

POST/v1/numbers/{id}/blocked-users

Bloqueia quem escreveu ao número nas últimas 24 horas. Cada usuário é um telefone ou um BSUID, e a resposta separa os que a Meta aceitou dos que ela recusou, com o motivo.

Autenticação
Chave de API
Escopo exigido
messages:write

Parâmetros de caminho

  • idstringobrigatório
    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 a 64 caracteres · /^[A-Za-z0-9_-]+$/

Corpo da requisição

application/json · obrigatório

  • usersarray<string>obrigatório
    Os usuários a bloquear, de um a cinquenta.1 a 50 itens

Respostas

200Sucesso.
  • donearray<object>obrigatório
    Os usuários que a Meta aceitou bloquear ou desbloquear.
  • done[].inputstring | nullobrigatório
    O que você pediu, como a Meta o devolveu.
  • done[].waIdstring | nullobrigatório
    O telefone do usuário na Meta, quando ela o devolve.
  • done[].userIdstring | nullobrigatório
    O BSUID do usuário, quando a Meta o devolve.
  • done[].reasonsarray<string>obrigatório
    Só em failed: o motivo que a Meta deu. Texto dela.
  • failedarray<object>obrigatório
    Os que a Meta recusou, cada um com o motivo dela.
  • failed[].inputstring | nullobrigatório
    O que você pediu, como a Meta o devolveu.
  • failed[].waIdstring | nullobrigatório
    O telefone do usuário na Meta, quando ela o devolve.
  • failed[].userIdstring | nullobrigatório
    O BSUID do usuário, quando a Meta o devolve.
  • failed[].reasonsarray<string>obrigatório
    Só em failed: o motivo que a Meta deu. Texto dela.
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
Campo recusado, com o motivoJSON
{
  "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."
    }
  ]
}
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "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"
}
Teste grátis terminadoJSON
{
  "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."
}
Conta bloqueada pela 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."
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "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."
}
404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
Não existe, ou não é seuJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
409O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.
Número desconectado da 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)."
}
415O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.
Tipo de conteúdo não lidoJSON
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
422O pedido está bem formado e a Luna o repassou, e a Meta recusou. O campo meta traz o que aconteceu, o que fazer e o erro original dela. Repetir o mesmo pedido repete a recusa.
A Meta recusou a operaçãoJSON
{
  "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"
      }
    }
  }
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
Gestão da conta ocupadaJSON
{
  "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."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Desbloquear um usuário

DELETE/v1/numbers/{id}/blocked-users/{user}

Desbloqueia um usuário, pelo telefone ou pelo BSUID que está no caminho. Fica aberta na conta suspensa: desbloquear nunca é o problema.

Autenticação
Chave de API
Escopo exigido
messages:write

Parâmetros de caminho

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

Respostas

200Sucesso.
  • donearray<object>obrigatório
    Os usuários que a Meta aceitou bloquear ou desbloquear.
  • done[].inputstring | nullobrigatório
    O que você pediu, como a Meta o devolveu.
  • done[].waIdstring | nullobrigatório
    O telefone do usuário na Meta, quando ela o devolve.
  • done[].userIdstring | nullobrigatório
    O BSUID do usuário, quando a Meta o devolve.
  • done[].reasonsarray<string>obrigatório
    Só em failed: o motivo que a Meta deu. Texto dela.
  • failedarray<object>obrigatório
    Os que a Meta recusou, cada um com o motivo dela.
  • failed[].inputstring | nullobrigatório
    O que você pediu, como a Meta o devolveu.
  • failed[].waIdstring | nullobrigatório
    O telefone do usuário na Meta, quando ela o devolve.
  • failed[].userIdstring | nullobrigatório
    O BSUID do usuário, quando a Meta o devolve.
  • failed[].reasonsarray<string>obrigatório
    Só em failed: o motivo que a Meta deu. Texto dela.
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
Campo recusado, com o motivoJSON
{
  "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."
    }
  ]
}
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "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"
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "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."
}
404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
Não existe, ou não é seuJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
409O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.
Número desconectado da 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)."
}
422O pedido está bem formado e a Luna o repassou, e a Meta recusou. O campo meta traz o que aconteceu, o que fazer e o erro original dela. Repetir o mesmo pedido repete a recusa.
A Meta recusou a operaçãoJSON
{
  "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"
      }
    }
  }
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
Gestão da conta ocupadaJSON
{
  "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."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Listar os QR codes

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

Os códigos que existem neste número, com o link curto de cada um.

Autenticação
Chave de API
Escopo exigido
numbers:read

Parâmetros de caminho

  • idstringobrigatório
    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 a 64 caracteres · /^[A-Za-z0-9_-]+$/

Respostas

200Sucesso.
  • dataarray<object>obrigatório
    Os códigos do número.
  • data[].codestringobrigatório
    O código do QR, que vai no caminho de DELETE.
  • data[].prefilledMessagestring | nullobrigatório
    A mensagem que já vem escrita quando o contato abre a conversa.
  • data[].linkstring | nullobrigatório
    O link curto (wa.me) que abre a mesma conversa.
  • data[].imageUrlstring | nullobrigatório
    O endereço da imagem do QR, quando você pediu imageFormat. É da Meta e pode expirar: baixe o arquivo.
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
Campo recusado, com o motivoJSON
{
  "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."
    }
  ]
}
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "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"
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "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."
}
404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
Não existe, ou não é seuJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
409O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.
Número desconectado da 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)."
}
422O pedido está bem formado e a Luna o repassou, e a Meta recusou. O campo meta traz o que aconteceu, o que fazer e o erro original dela. Repetir o mesmo pedido repete a recusa.
A Meta recusou a operaçãoJSON
{
  "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"
      }
    }
  }
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
Gestão da conta ocupadaJSON
{
  "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."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Criar um QR code e um link curto

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

Cria um código que abre uma conversa com o número, com a mensagem já escrita. Devolve o código, o link curto e, se você pediu, o endereço da imagem.

Autenticação
Chave de API
Escopo exigido
numbers:write

Parâmetros de caminho

  • idstringobrigatório
    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 a 64 caracteres · /^[A-Za-z0-9_-]+$/

Corpo da requisição

application/json · obrigatório

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

Respostas

201Criado.
  • codestringobrigatório
    O código do QR, que vai no caminho de DELETE.
  • prefilledMessagestring | nullobrigatório
    A mensagem que já vem escrita quando o contato abre a conversa.
  • linkstring | nullobrigatório
    O link curto (wa.me) que abre a mesma conversa.
  • imageUrlstring | nullobrigatório
    O endereço da imagem do QR, quando você pediu imageFormat. É da Meta e pode expirar: baixe o arquivo.
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
Campo recusado, com o motivoJSON
{
  "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."
    }
  ]
}
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "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"
}
Teste grátis terminadoJSON
{
  "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."
}
Conta bloqueada pela 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."
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "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."
}
404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
Não existe, ou não é seuJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
409O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.
Número desconectado da 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)."
}
415O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.
Tipo de conteúdo não lidoJSON
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
422O pedido está bem formado e a Luna o repassou, e a Meta recusou. O campo meta traz o que aconteceu, o que fazer e o erro original dela. Repetir o mesmo pedido repete a recusa.
A Meta recusou a operaçãoJSON
{
  "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"
      }
    }
  }
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
Gestão da conta ocupadaJSON
{
  "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."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Apagar um QR code

DELETE/v1/numbers/{id}/qr-codes/{code}

Apaga o código e o link curto: quem ainda tem o QR impresso deixa de abrir a conversa. Fica aberta na conta suspensa.

Autenticação
Chave de API
Escopo exigido
numbers:write

Parâmetros de caminho

  • idstringobrigatório
    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 a 64 caracteres · /^[A-Za-z0-9_-]+$/
  • codestringobrigatório
    O código do QR, como a criação o devolveu.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/

Respostas

204Sem conteúdo: a operação foi feita e a resposta não tem corpo.
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
Campo recusado, com o motivoJSON
{
  "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."
    }
  ]
}
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "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"
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "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."
}
404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
Não existe, ou não é seuJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
409O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.
Número desconectado da 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)."
}
422O pedido está bem formado e a Luna o repassou, e a Meta recusou. O campo meta traz o que aconteceu, o que fazer e o erro original dela. Repetir o mesmo pedido repete a recusa.
A Meta recusou a operaçãoJSON
{
  "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"
      }
    }
  }
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
Gestão da conta ocupadaJSON
{
  "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."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Abrir uma sessão de conexão

POST/v1/onboarding/sessions

Cria a sessão que o fluxo de conexão da Meta preenche, e devolve o sessionId e o csrfState.

Autenticação
Chave de API
Escopo exigido
onboarding:write

Respostas

201Criado.
  • sessionIdstring (uuid)obrigatório
  • statestringobrigatório
  • configIdstringobrigatório
  • sdkVersionstringobrigatório
    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.
  • csrfStatestringobrigatório
  • expiresAtstringobrigatório
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "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"
}
Conta ainda sem liberação para conectarJSON
{
  "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"
  ]
}
Teste grátis terminadoJSON
{
  "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."
}
Conta bloqueada pela 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."
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "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."
}
409O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.
A conta já está na capacidade de númerosJSON
{
  "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
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Consultar uma sessão de conexão

GET/v1/onboarding/sessions/{id}

O estado atual da sessão e a orientação correspondente, em português, pronta para exibir.

Autenticação
Chave de API
Escopo exigido
onboarding:write

Parâmetros de caminho

  • idstring (uuid)obrigatório

Respostas

200Sucesso.
  • sessionIdstring (uuid)obrigatório
  • statestringobrigatório
  • orientacaostringobrigatório
  • terminalbooleanobrigatório
  • proximoPassostring | nullobrigatório
  • attemptCountintegerobrigatório
  • nextAttemptAtstring | nullobrigatório
  • retryNotBeforestring | nullobrigatório
  • expiresAtstringobrigatório
  • createdAtstringobrigatório
  • updatedAtstringobrigatório
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
Campo recusado, com o motivoJSON
{
  "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."
    }
  ]
}
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "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"
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "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."
}
404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
Não existe, ou não é seuJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Registrar abandono ou erro do fluxo

POST/v1/onboarding/sessions/{id}/abandon

Telemetria do que aconteceu na janela da Meta quando o fluxo não completou: em que tela o cliente parou, ou que erro a Meta reportou.

Autenticação
Chave de API
Escopo exigido
onboarding:write

Parâmetros de caminho

  • idstring (uuid)obrigatório

Corpo da requisição

application/json · obrigatório

  • csrfStatestringobrigatório
  • currentStepstring | nullopcional
    1 a 120 caracteres
  • errorCodeinteger | nullopcional
  • errorMessagestring | nullopcional

Respostas

200Sucesso.
  • sessionIdstring (uuid)obrigatório
  • statestringobrigatório
  • orientacaostringobrigatório
  • abandonedAtStepstring | nullobrigatório
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
Campo recusado, com o motivoJSON
{
  "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."
    }
  ]
}
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "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"
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "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."
}
404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
Não existe, ou não é seuJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
415O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.
Tipo de conteúdo não lidoJSON
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Concluir a conexão

POST/v1/onboarding/sessions/{id}/complete

Troca o código do fluxo embutido por acesso permanente à conta do cliente, e leva a sessão até o fim: token selado, aplicativo inscrito na conta, número registrado.

Autenticação
Chave de API
Escopo exigido
onboarding:write

Parâmetros de caminho

  • idstring (uuid)obrigatório

Corpo da requisição

application/json · obrigatório

  • codestringobrigatório
  • csrfStatestringobrigatório
  • wabaIdstring | nullopcional
  • phoneNumberIdstring | nullopcional
  • businessIdstring | nullopcional

Respostas

200Sucesso.
  • sessionIdstring (uuid)obrigatório
  • statestringobrigatório
  • orientacaostringobrigatório
  • terminalbooleanobrigatório
  • proximoPassostring | nullobrigatório
  • motivostring | nullobrigatório
  • podeRetentarbooleanobrigatório
  • wabaIdstring | nullobrigatório
  • phoneNumberIdstring | nullobrigatório
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
Campo recusado, com o motivoJSON
{
  "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."
    }
  ]
}
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "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"
}
Teste grátis terminadoJSON
{
  "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."
}
Conta bloqueada pela 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."
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "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."
}
404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
Não existe, ou não é seuJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
415O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.
Tipo de conteúdo não lidoJSON
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Listar números conectados

GET/v1/numbers

Todos os números de WhatsApp conectados a este cliente, com estado, qualidade, velocidade de envio e limite diário de conversas. Filtros: externalId (igualdade exata), q (busca por prefixo em externalId, label e displayNumber), state, wabaId, qualityRating, connectionStatus, ready e canSend. Parâmetro que a rota não conhece volta 400.

Autenticação
Chave de API
Escopo exigido
numbers:read

Parâmetros de consulta

  • externalIdstringopcional
    O rótulo que você deu ao seu cliente. Igualdade exata; rótulo sem número devolve lista vazia.1 a 128 caracteres
  • statestringopcional
    O estado do número (state): PENDING, REGISTER_SENT, REGISTERED, PIN_REQUIRED, BLOCKED ou DISCONNECTED.Valores: PENDING REGISTER_SENT REGISTERED PIN_REQUIRED BLOCKED DISCONNECTED
  • qstringopcional
    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 a 128 caracteres
  • wabaIdstringopcional
    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 a 64 caracteres
  • qualityRatingstringopcional
    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.Valores: GREEN YELLOW RED NA UNKNOWN
  • connectionStatusstringopcional
    Só os números com este connection.status: connected, connecting, action_required ou disconnected.Valores: connected connecting action_required disconnected
  • readystringopcional
    true: só os números prontos para enviar e receber. false: só os que ainda não estão.Valores: true false
  • canSendstringopcional
    true: só os números por onde enviar funciona agora (connection.canSend). false: só os que não.Valores: true false
  • limitintegeropcional
    Quantos números por página: de 1 a 100, 50 se omitido.mínimo 1 · máximo 100
  • cursorstringopcional
    O nextCursor da resposta anterior. Opaco: carrega posição, não contagem.até 256 caracteres

Respostas

200Sucesso.
  • dataarray<object>obrigatório
  • data[].idstring (uuid)obrigatório
  • data[].metaPhoneNumberIdstringobrigatório
  • data[].displayNumberstring | nullobrigatório
  • data[].statestringobrigatório
  • data[].retryNotBeforestring | nullobrigatório
  • data[].podeRetentarbooleanobrigatório
  • data[].qualityRatingstring | nullobrigatório
  • data[].throughputLevelstring | nullobrigatório
    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 | nullobrigatório
    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 | nullobrigatório
  • data[].displayNamestring | nullobrigatório
    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 | nullobrigatório
    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 | nullobrigatório
    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[].autoReadbooleanobrigatório
    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 | nullobrigatório
    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 | nullobrigatório
    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 | nullobrigatório
    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 | nullobrigatório
    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[].wabaobjectobrigatório
    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 | nullobrigatório
    O identificador da conta de negócio do número na Meta (WABA).
  • data[].waba.restrictedbooleanobrigatório
    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.disabledbooleanobrigatório
    true quando a Meta avisou que desativou a conta.
  • data[].waba.credentialExpiresAtstring | nullobrigatório
    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 | nullobrigatório
    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 | nullobrigatório
    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 | nullobrigatório
    A moeda da conta na Meta, como ela informa (por exemplo BRL). Nulo quando ainda não lida.
  • data[].readybooleanobrigatório
    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[].connectionobjectobrigatório
    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.statusstringobrigatório
    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).Valores: connected connecting action_required disconnected
  • data[].connection.canSendbooleanobrigatório
    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>obrigatório
    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[].codestringobrigatório
    O código do motivo, para o seu código comparar. Novos códigos podem aparecer.
  • data[].connection.reasons[].messagestringobrigatório
    O que está acontecendo, em português, pronto para repassar ao seu cliente.
  • data[].connection.reasons[].solutionstringobrigatório
    O que fazer a respeito, em português.
  • data[].connection.reasons[].actionstring | nullobrigatório
    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.Valores: send_pin reconnect reconnect_link meta_manager wait contact_helsen
  • data[].connection.reasons[].actionUrlstring | nullobrigatório
    O endereço da conta no WhatsApp Manager da Meta. Só vem quando action é meta_manager.
  • data[].connection.reasons[].docsUrlstring | nullobrigatório
    O guia do site que explica o motivo.
  • data[].connection.reasons[].sincestring | nullobrigatório
    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>obrigatório
    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>obrigatório
    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[].actionstringobrigatório
    Valores: disconnect reconnect reconnect_link send_pin edit_label
  • data[].blockedActions[].messagestringobrigatório
    Por que a ação não está disponível agora, em português, pronto para mostrar.
  • data[].createdAtstringobrigatório
  • data[].updatedAtstringobrigatório
  • nextCursorstring | nullobrigatório
    Mande este valor de volta em cursor para pegar a próxima página. Nulo significa fim.
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
Campo recusado, com o motivoJSON
{
  "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."
    }
  ]
}
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "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"
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "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."
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Consultar um número

GET/v1/numbers/{id}

Um número, com tudo que a listagem traz mais a saúde da conexão com a Meta.

Autenticação
Chave de API
Escopo exigido
numbers:read

Parâmetros de caminho

  • idstringobrigatório
    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 a 64 caracteres · /^[A-Za-z0-9_-]+$/

Respostas

200Sucesso.
  • idstring (uuid)obrigatório
  • metaPhoneNumberIdstringobrigatório
  • displayNumberstring | nullobrigatório
  • statestringobrigatório
  • retryNotBeforestring | nullobrigatório
  • podeRetentarbooleanobrigatório
  • qualityRatingstring | nullobrigatório
  • throughputLevelstring | nullobrigatório
    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 | nullobrigatório
    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 | nullobrigatório
  • displayNamestring | nullobrigatório
    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 | nullobrigatório
    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 | nullobrigatório
    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.
  • autoReadbooleanobrigatório
    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 | nullobrigatório
    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 | nullobrigatório
    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 | nullobrigatório
    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 | nullobrigatório
    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.
  • wabaobjectobrigatório
    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 | nullobrigatório
    O identificador da conta de negócio do número na Meta (WABA).
  • waba.restrictedbooleanobrigatório
    true quando a Meta avisou uma restrição da conta e ela ainda vale. Os detalhes estão em GET /v1/business-accounts.
  • waba.disabledbooleanobrigatório
    true quando a Meta avisou que desativou a conta.
  • waba.credentialExpiresAtstring | nullobrigatório
    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 | nullobrigatório
    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 | nullobrigatório
    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 | nullobrigatório
    A moeda da conta na Meta, como ela informa (por exemplo BRL). Nulo quando ainda não lida.
  • readybooleanobrigatório
    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.
  • connectionobjectobrigatório
  • connection.statusstringobrigatório
    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).Valores: connected connecting action_required disconnected
  • connection.canSendbooleanobrigatório
    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>obrigatório
    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[].codestringobrigatório
    O código do motivo, para o seu código comparar. Novos códigos podem aparecer.
  • connection.reasons[].messagestringobrigatório
    O que está acontecendo, em português, pronto para repassar ao seu cliente.
  • connection.reasons[].solutionstringobrigatório
    O que fazer a respeito, em português.
  • connection.reasons[].actionstring | nullobrigatório
    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.Valores: send_pin reconnect reconnect_link meta_manager wait contact_helsen
  • connection.reasons[].actionUrlstring | nullobrigatório
    O endereço da conta no WhatsApp Manager da Meta. Só vem quando action é meta_manager.
  • connection.reasons[].docsUrlstring | nullobrigatório
    O guia do site que explica o motivo.
  • connection.reasons[].sincestring | nullobrigatório
    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>obrigatório
    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[].keystringobrigatório
    Valores: authorized receiving registered ready
  • connection.steps[].labelstringobrigatório
    O nome do passo, em português. Em coexistência o terceiro passo se chama Número vinculado.
  • connection.steps[].statusstringobrigatório
    Valores: done current pending
  • allowedActionsarray<string>obrigatório
    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>obrigatório
    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[].actionstringobrigatório
    Valores: disconnect reconnect reconnect_link send_pin edit_label
  • blockedActions[].messagestringobrigatório
    Por que a ação não está disponível agora, em português, pronto para mostrar.
  • createdAtstringobrigatório
  • updatedAtstringobrigatório
  • tetoDeVazaoPorSegundonumber | nullobrigatório
    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 | nullobrigatório
    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 | nullobrigatório
    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 | nullobrigatório
    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 | nullobrigatório
    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 | nullobrigatório
    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).
  • podeReconectarbooleanobrigatório
    Se a autorização deste número admite reconexão. Quando for true, POST /v1/onboarding/reconnect abre a sessão que a substitui.
  • coexistencebooleanobrigatório
    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.
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
Campo recusado, com o motivoJSON
{
  "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."
    }
  ]
}
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "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"
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "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."
}
404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
Não existe, ou não é seuJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Editar um número

PATCH/v1/numbers/{id}

Troca o externalId e o label de um número, e liga ou desliga o autoRead (marcar como lida sozinho cada mensagem recebida). É o jeito de reaproveitar um número para outro cliente seu, ou de dar nome a um número que foi conectado pelo console, sem link.

Autenticação
Chave de API
Escopo exigido
numbers:write

Parâmetros de caminho

  • idstringobrigatório
    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 a 64 caracteres · /^[A-Za-z0-9_-]+$/

Corpo da requisição

application/json · obrigatório

  • externalIdstring | nullopcional
    O seu identificador para o cliente dono do número (1 a 128 caracteres). null limpa.1 a 128 caracteres
  • labelstring | nullopcional
    Um nome livre e curto para reconhecer o número (1 a 128 caracteres). null limpa.1 a 128 caracteres
  • autoReadbooleanopcional
    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.

Respostas

200Sucesso.
  • idstring (uuid)obrigatório
  • metaPhoneNumberIdstringobrigatório
  • displayNumberstring | nullobrigatório
  • statestringobrigatório
  • retryNotBeforestring | nullobrigatório
  • podeRetentarbooleanobrigatório
  • qualityRatingstring | nullobrigatório
  • throughputLevelstring | nullobrigatório
    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 | nullobrigatório
    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 | nullobrigatório
  • displayNamestring | nullobrigatório
    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 | nullobrigatório
    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 | nullobrigatório
    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.
  • autoReadbooleanobrigatório
    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 | nullobrigatório
    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 | nullobrigatório
    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 | nullobrigatório
    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 | nullobrigatório
    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.
  • wabaobjectobrigatório
    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 | nullobrigatório
    O identificador da conta de negócio do número na Meta (WABA).
  • waba.restrictedbooleanobrigatório
    true quando a Meta avisou uma restrição da conta e ela ainda vale. Os detalhes estão em GET /v1/business-accounts.
  • waba.disabledbooleanobrigatório
    true quando a Meta avisou que desativou a conta.
  • waba.credentialExpiresAtstring | nullobrigatório
    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 | nullobrigatório
    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 | nullobrigatório
    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 | nullobrigatório
    A moeda da conta na Meta, como ela informa (por exemplo BRL). Nulo quando ainda não lida.
  • readybooleanobrigatório
    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.
  • connectionobjectobrigatório
  • connection.statusstringobrigatório
    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).Valores: connected connecting action_required disconnected
  • connection.canSendbooleanobrigatório
    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>obrigatório
    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[].codestringobrigatório
    O código do motivo, para o seu código comparar. Novos códigos podem aparecer.
  • connection.reasons[].messagestringobrigatório
    O que está acontecendo, em português, pronto para repassar ao seu cliente.
  • connection.reasons[].solutionstringobrigatório
    O que fazer a respeito, em português.
  • connection.reasons[].actionstring | nullobrigatório
    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.Valores: send_pin reconnect reconnect_link meta_manager wait contact_helsen
  • connection.reasons[].actionUrlstring | nullobrigatório
    O endereço da conta no WhatsApp Manager da Meta. Só vem quando action é meta_manager.
  • connection.reasons[].docsUrlstring | nullobrigatório
    O guia do site que explica o motivo.
  • connection.reasons[].sincestring | nullobrigatório
    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>obrigatório
    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[].keystringobrigatório
    Valores: authorized receiving registered ready
  • connection.steps[].labelstringobrigatório
    O nome do passo, em português. Em coexistência o terceiro passo se chama Número vinculado.
  • connection.steps[].statusstringobrigatório
    Valores: done current pending
  • allowedActionsarray<string>obrigatório
    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>obrigatório
    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[].actionstringobrigatório
    Valores: disconnect reconnect reconnect_link send_pin edit_label
  • blockedActions[].messagestringobrigatório
    Por que a ação não está disponível agora, em português, pronto para mostrar.
  • createdAtstringobrigatório
  • updatedAtstringobrigatório
  • tetoDeVazaoPorSegundonumber | nullobrigatório
    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 | nullobrigatório
    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 | nullobrigatório
    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 | nullobrigatório
    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 | nullobrigatório
    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 | nullobrigatório
    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).
  • podeReconectarbooleanobrigatório
    Se a autorização deste número admite reconexão. Quando for true, POST /v1/onboarding/reconnect abre a sessão que a substitui.
  • coexistencebooleanobrigatório
    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.
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
Campo recusado, com o motivoJSON
{
  "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."
    }
  ]
}
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "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"
}
Teste grátis terminadoJSON
{
  "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."
}
Conta bloqueada pela 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."
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "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."
}
404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
Não existe, ou não é seuJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
415O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.
Tipo de conteúdo não lidoJSON
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Desconectar um número

DELETE/v1/numbers/{id}

Tira o número da Luna. É o jeito de abrir uma vaga na capacidade do plano: o número deixa de contar a partir deste instante, e o seu cliente pode ser trocado por outro.

Autenticação
Chave de API
Escopo exigido
numbers:write

Parâmetros de caminho

  • idstringobrigatório
    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 a 64 caracteres · /^[A-Za-z0-9_-]+$/

Respostas

204Sem conteúdo: a operação foi feita e a resposta não tem corpo.
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
Campo recusado, com o motivoJSON
{
  "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."
    }
  ]
}
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "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"
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "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."
}
404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
Não existe, ou não é seuJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Informar o PIN de verificação em duas etapas de um número

POST/v1/numbers/{id}/pin

Informa o PIN de verificação em duas etapas de um número que já está registrado na Cloud API de outro provedor, para que a Luna consiga registrá-lo sem que o negócio final precise desligar a verificação.

Autenticação
Chave de API
Escopo exigido
onboarding:write

Parâmetros de caminho

  • idstringobrigatório
    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 a 64 caracteres · /^[A-Za-z0-9_-]+$/

Corpo da requisição

application/json · obrigatório

  • pinstringobrigatório
    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}$/

Respostas

200Sucesso.
  • idstring (uuid)obrigatório
    O identificador deste número na Luna.
  • statestringobrigatório
    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.
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
Campo recusado, com o motivoJSON
{
  "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."
    }
  ]
}
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "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"
}
Teste grátis terminadoJSON
{
  "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."
}
Conta bloqueada pela 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."
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "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."
}
404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
Não existe, ou não é seuJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
409O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.
O número não pede 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á."
}
Tentativas de registro reservadasJSON
{
  "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"
}
A conta já está na capacidade de númerosJSON
{
  "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
}
415O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.
Tipo de conteúdo não lidoJSON
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Reconectar um número cuja autorização morreu

POST/v1/onboarding/reconnect

Abre uma sessão de conexão para um número que já existe, quando a autorização concedida pelo cliente expirou ou foi revogada.

Autenticação
Chave de API
Escopo exigido
onboarding:write

Corpo da requisição

application/json · obrigatório

  • numberIdstringobrigatório
    O número: o UUID da Luna (o id que GET /v1/numbers devolve) ou o id da Meta (metaPhoneNumberId). Os dois valem.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/

Respostas

201Criado.
  • sessionIdstring (uuid)obrigatório
  • statestringobrigatório
  • configIdstringobrigatório
  • sdkVersionstringobrigatório
    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.
  • csrfStatestringobrigatório
  • expiresAtstringobrigatório
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
Campo recusado, com o motivoJSON
{
  "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."
    }
  ]
}
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "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"
}
Conta ainda sem liberação para conectarJSON
{
  "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"
  ]
}
Teste grátis terminadoJSON
{
  "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."
}
Conta bloqueada pela 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."
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "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."
}
404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
Não existe, ou não é seuJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
409O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.
A autorização não admite reconexãoJSON
{
  "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"
}
A conta já está na capacidade de númerosJSON
{
  "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
}
415O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.
Tipo de conteúdo não lidoJSON
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Listar contas de negócio

GET/v1/business-accounts

As contas de WhatsApp Business que este cliente conectou, da mais recente para a mais antiga, cada uma com o nome na Meta, o endereço no WhatsApp Manager e os números.

Autenticação
Chave de API
Escopo exigido
numbers:read

Respostas

200Sucesso.
  • dataarray<object>obrigatório
  • data[].idstring (uuid)obrigatório
  • data[].wabaIdstringobrigatório
  • data[].numbersarray<string>obrigatório
  • data[].namestring | nullobrigatório
    O nome da conta de WhatsApp Business como a Meta o informa. Nulo enquanto a Luna ainda não o leu.
  • data[].managerUrlstringobrigatório
    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>obrigatório
    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)obrigatório
    O id do número na Luna, o mesmo de GET /v1/numbers.
  • data[].phoneNumbers[].displayNumberstring | nullobrigatório
    O número como se lê no telefone, ou nulo enquanto a Luna não o leu.
  • data[].phoneNumbers[].externalIdstring | nullobrigatório
    O seu rótulo para o cliente dono do número.
  • data[].phoneNumbers[].labelstring | nullobrigatório
    O nome que você deu ao número.
  • data[].statusobjectobrigatório
    O último estado de saúde conhecido da conta.
  • data[].status.restrictedbooleanobrigatório
    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>obrigatório
    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 | nullobrigatório
  • data[].status.restrictions[].expirationstring | nullobrigatório
  • data[].status.restrictions[].remediationstring | nullobrigatório
  • data[].status.disabledbooleanobrigatório
    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 | nullobrigatório
    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 | nullobrigatório
    Quando chegou o aviso de saúde mais recente, ou nulo se nunca chegou.
  • data[].credentialExpiresAtstring | nullobrigatório
    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 | nullobrigatório
    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 | nullobrigatório
    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 | nullobrigatório
    A moeda da conta na Meta, como ela informa (por exemplo BRL). Nulo quando a Luna ainda não leu.
  • data[].createdAtstringobrigatório
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "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"
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "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."
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Conferir agora a forma de pagamento da conta na Meta

POST/v1/business-accounts/{id}/payment-method/check

Lê na Meta se a conta tem forma de pagamento cadastrada, sem esperar a leitura de hora em hora, e devolve o resultado. O aviso por webhook segue o caminho de sempre: number.action_required (motivo payment_method_missing) quando falta e number.action_resolved quando aparece. Leitura com menos de 60 segundos é devolvida sem chamar a Meta, e a chamada respeita o orçamento de chamadas da conta.

Autenticação
Chave de API
Escopo exigido
numbers:read

Parâmetros de caminho

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

Respostas

200Sucesso.
  • idstring (uuid)obrigatório
  • wabaIdstringobrigatório
  • paymentMethodOnMetaboolean | nullobrigatório
    true: a conta tem forma de pagamento na Meta. false: não tem. Nulo: a Luna ainda não conseguiu ler.
  • currencystring | nullobrigatório
    A moeda da conta na Meta, como ela informa. Nulo quando ainda não lida.
  • checkedAtstring | nullobrigatório
    Quando a Luna leu a forma de pagamento da Meta pela última vez, em ISO-8601 UTC. Nulo se nunca leu.
  • refreshedbooleanobrigatório
    true quando esta chamada leu na Meta agora. false quando devolveu a leitura que já existia.
  • reasonstringobrigatório
    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.Valores: checked recent busy failed
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
Campo recusado, com o motivoJSON
{
  "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."
    }
  ]
}
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "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"
}
Teste grátis terminadoJSON
{
  "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."
}
Conta bloqueada pela 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."
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "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."
}
404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
Não existe, ou não é seuJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Consultar a saúde de um número

GET/v1/numbers/{id}/health

A avaliação de qualidade, o nível de vazão e o limite diário de conversas que a Meta atribui a este número agora, e as mudanças que a plataforma observou ao longo do tempo.

Autenticação
Chave de API
Escopo exigido
numbers:read

Parâmetros de caminho

  • idstringobrigatório
    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 a 64 caracteres · /^[A-Za-z0-9_-]+$/

Respostas

200Sucesso.
  • idstring (uuid)obrigatório
  • qualityRatingstring | nullobrigatório
  • throughputLevelstring | nullobrigatório
  • tetoDeVazaoPorSegundonumber | nullobrigatório
    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 | nullobrigatório
    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 | nullobrigatório
    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 | nullobrigatório
    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 | nullobrigatório
  • codeVerificationStatusstring | nullobrigatório
  • checkedAtstring | nullobrigatório
  • transitionsarray<object>obrigatório
  • transitions[].qualityRatingstring | nullobrigatório
  • transitions[].throughputLevelstring | nullobrigatório
  • transitions[].limiteDiarioDeConversasstring | nullobrigatório
  • transitions[].codeVerificationStatusstring | nullobrigatório
  • transitions[].observedAtstringobrigatório
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
Campo recusado, com o motivoJSON
{
  "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."
    }
  ]
}
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "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"
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "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."
}
404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
Não existe, ou não é seuJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Ler o consumo da Meta de um número ou de um cliente

GET/v1/usage

O consumo que a Meta mede para um número (numberId) ou para todos os números de um cliente seu (externalId), repassado como ela informa, com a moeda de cada conta e sem somar. format=csv devolve text/csv. A Luna só lê e mostra: nada disto entra na assinatura da Luna.

Autenticação
Chave de API
Escopo exigido
numbers:read

Parâmetros de consulta

  • numberIdstringopcional
    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 a 64 caracteres · /^[A-Za-z0-9_-]+$/
  • externalIdstringopcional
    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 a 128 caracteres
  • startstring (date-time) | string (date)opcional
    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)opcional
    O fim do período, em ISO 8601. Ausente, agora (arredondado para baixo a cada cinco minutos).
  • granularitystringopcional
    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.padrão: "DAILY"Valores: HALF_HOUR DAILY MONTHLY
  • formatstringopcional
    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.padrão: "json"Valores: json csv

Respostas

200Sucesso.
  • numberIdstring (uuid) | nullobrigatório
    O id do número na Luna, quando você consultou por numberId. Nulo quando consultou por externalId.
  • phoneNumberIdstring | nullobrigatório
    O id do número na Meta, quando você consultou por numberId. Nulo quando consultou por externalId.
  • externalIdstring | nullobrigatório
    O rótulo do cliente, quando você consultou por externalId. Nulo quando consultou por numberId.
  • startstringobrigatório
    O começo do período consultado, em ISO 8601.
  • endstringobrigatório
    O fim do período consultado, em ISO 8601.
  • granularitystringobrigatório
    Valores: HALF_HOUR DAILY MONTHLY
  • readAtstringobrigatório
    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.
  • noticestringobrigatório
    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>obrigatório
    Os números cobertos pela consulta, inclusive os que ficaram de fora e os que não tiveram nenhum ponto.
  • numbers[].numberIdstring (uuid)obrigatório
    O id do número na Luna.
  • numbers[].phoneNumberIdstringobrigatório
    O id do número na Meta.
  • numbers[].currencystring | nullobrigatório
    A moeda da conta do negócio na Meta. Nulo quando a Luna ainda não a leu.
  • numbers[].readbooleanobrigatório
    true quando a Luna leu o consumo deste número. false quando ele ficou de fora, e reason diz por quê.
  • numbers[].reasonstring | nullobrigatório
    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>obrigatório
    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)obrigatório
    O número da Luna a que este ponto pertence.
  • data[].phoneNumberIdstringobrigatório
    O id do mesmo número na Meta.
  • data[].currencystring | nullobrigatório
    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 | nullobrigatório
    O começo do ponto, em ISO 8601. Nulo quando a Meta não informou.
  • data[].endstring | nullobrigatório
    O fim do ponto, em ISO 8601. Nulo quando a Meta não informou.
  • data[].pricingCategorystring | nullobrigatório
    A categoria de cobrança, como a Meta a nomeia (por exemplo MARKETING, UTILITY, SERVICE). Novos valores podem aparecer.
  • data[].pricingTypestring | nullobrigatório
    O tipo de cobrança, como a Meta o nomeia (por exemplo REGULAR, FREE_CUSTOMER_SERVICE). Novos valores podem aparecer.
  • data[].tierstring | nullobrigatório
    A faixa de volume da Meta, no formato que ela manda (por exemplo "0:750000"). Nulo quando não veio.
  • data[].countrystring | nullobrigatório
    O país do destinatário, como a Meta informou. Nulo quando não veio.
  • data[].volumenumber | nullobrigatório
    O volume que a Meta mediu neste ponto. É dela, aproximado, e nunca é somado pela Luna.
  • data[].costnumber | nullobrigatório
    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.
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
Campo recusado, com o motivoJSON
{
  "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."
    }
  ]
}
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "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"
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "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."
}
409O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.
Número desconectado da 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)."
}
422O pedido está bem formado e a Luna o repassou, e a Meta recusou. O campo meta traz o que aconteceu, o que fazer e o erro original dela. Repetir o mesmo pedido repete a recusa.
A Meta recusou a operaçãoJSON
{
  "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"
      }
    }
  }
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
Gestão da conta ocupadaJSON
{
  "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."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}