Números
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.
Parâmetros de caminho
idstringobrigatórioO 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órioO recado curto do perfil. Nulo quando não há.addressstring | nullobrigatórioO endereço do negócio.descriptionstring | nullobrigatórioA descrição do negócio.emailstring | nullobrigatórioO e-mail de contato.websitesarray<string>obrigatórioOs sites do negócio. Lista vazia quando não há.verticalstring | nullobrigatórioO ramo de atividade, como a Meta o devolve. Texto da Meta, sem lista fechada aqui.profilePictureUrlstring | nullobrigatórioO 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.
{
"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-AuthenticateSempre Bearer.
{
"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.
{
"error": "forbidden",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
"requiredScope": "numbers:read"
}{
"error": "test_key_not_allowed",
"docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
"message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
{
"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.
{
"error": "not_available_in_coexistence",
"docsUrl": "https://lunahia.com.br/docs/numero-na-meta",
"message": "Este número está conectado em coexistência, e a Meta não aceita esta operação por API nesse caso. Faça a mudança no aplicativo WhatsApp Business do celular do negócio."
}{
"error": "number_disconnected",
"docsUrl": "https://lunahia.com.br/docs/conectar-numero",
"message": "Este número foi desconectado da Luna e não envia mais. O histórico foi preservado. Para voltar a usá-lo, conecte-o de novo com um link de conexão (POST /v1/onboarding/links)."
}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.
{
"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-AfterSegundos a esperar antes de repetir.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}{
"error": "management_busy",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "As operações de gestão desta conexão atingiram o limite momentâneo. Tente novamente em instantes."
}503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
{
"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.
Parâmetros de caminho
idstringobrigatórioO 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
aboutstringopcionalO recado curto. Até 139 caracteres.1 a 139 caracteresaddressstringopcionalO endereço. Até 256 caracteres.1 a 256 caracteresdescriptionstringopcionalA descrição. Até 512 caracteres.1 a 512 caracteresemailstringopcionalO e-mail de contato. Até 128 caracteres.1 a 128 caractereswebsitesarray<string (uri)>opcionalAté dois sites. A lista inteira substitui a que existe.até 2 itensverticalstringopcionalO ramo de atividade, no vocabulário da Meta.1 a 64 caracteresdisplayNamestringopcionalPede à 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 caracteresprofilePictureHandlestringopcionalO 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órioOs campos que a Meta aceitou trocar, pelos nomes que você mandou.
202Aceito: o pedido foi registrado e será processado.
updatedFieldsarray<string>obrigatórioOs campos que a Meta aceitou trocar, pelos nomes que você mandou.displayNameStatusstringobrigatórioO nome foi pedido e está em revisão na Meta. O resultado chega no evento number.display_name_reviewed.Valores:pending_reviewpendingDisplayNamestringobrigatórioO 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.
{
"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-AuthenticateSempre Bearer.
{
"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.
{
"error": "forbidden",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
"requiredScope": "numbers:read"
}{
"error": "trial_expired",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"message": "O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."
}{
"error": "account_blocked",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."
}{
"error": "test_key_not_allowed",
"docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
"message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
{
"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.
{
"error": "not_available_in_coexistence",
"docsUrl": "https://lunahia.com.br/docs/numero-na-meta",
"message": "Este número está conectado em coexistência, e a Meta não aceita esta operação por API nesse caso. Faça a mudança no aplicativo WhatsApp Business do celular do negócio."
}{
"error": "number_disconnected",
"docsUrl": "https://lunahia.com.br/docs/conectar-numero",
"message": "Este número foi desconectado da Luna e não envia mais. O histórico foi preservado. Para voltar a usá-lo, conecte-o de novo com um link de conexão (POST /v1/onboarding/links)."
}415O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.
{
"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.
{
"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-AfterSegundos a esperar antes de repetir.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}{
"error": "management_busy",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "As operações de gestão desta conexão atingiram o limite momentâneo. Tente novamente em instantes."
}503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
{
"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.
Parâmetros de caminho
idstringobrigatórioO 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
limitintegeropcionalQuantos por página, de 1 a 100.mínimo 1 · máximo 100cursorstringopcionalO nextCursor da página anterior.1 a 512 caracteres
Respostas
200Sucesso.
dataarray<object>obrigatórioOs usuários bloqueados nesta página.data[].waIdstring | nullobrigatórioO telefone do usuário bloqueado.data[].userIdstring | nullobrigatórioO BSUID do usuário bloqueado.nextCursorstring | nullobrigatórioO 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.
{
"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-AuthenticateSempre Bearer.
{
"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.
{
"error": "forbidden",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
"requiredScope": "numbers:read"
}{
"error": "test_key_not_allowed",
"docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
"message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
{
"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.
{
"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.
{
"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-AfterSegundos a esperar antes de repetir.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}{
"error": "management_busy",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "As operações de gestão desta conexão atingiram o limite momentâneo. Tente novamente em instantes."
}503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
{
"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.
Parâmetros de caminho
idstringobrigatórioO 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
usersarray<string>obrigatórioOs usuários a bloquear, de um a cinquenta.1 a 50 itens
Respostas
200Sucesso.
donearray<object>obrigatórioOs usuários que a Meta aceitou bloquear ou desbloquear.done[].inputstring | nullobrigatórioO que você pediu, como a Meta o devolveu.done[].waIdstring | nullobrigatórioO telefone do usuário na Meta, quando ela o devolve.done[].userIdstring | nullobrigatórioO BSUID do usuário, quando a Meta o devolve.done[].reasonsarray<string>obrigatórioSó em failed: o motivo que a Meta deu. Texto dela.failedarray<object>obrigatórioOs que a Meta recusou, cada um com o motivo dela.failed[].inputstring | nullobrigatórioO que você pediu, como a Meta o devolveu.failed[].waIdstring | nullobrigatórioO telefone do usuário na Meta, quando ela o devolve.failed[].userIdstring | nullobrigatórioO BSUID do usuário, quando a Meta o devolve.failed[].reasonsarray<string>obrigatórioSó 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.
{
"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-AuthenticateSempre Bearer.
{
"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.
{
"error": "forbidden",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
"requiredScope": "numbers:read"
}{
"error": "trial_expired",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"message": "O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."
}{
"error": "account_blocked",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."
}{
"error": "test_key_not_allowed",
"docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
"message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
{
"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.
{
"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.
{
"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.
{
"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-AfterSegundos a esperar antes de repetir.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}{
"error": "management_busy",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "As operações de gestão desta conexão atingiram o limite momentâneo. Tente novamente em instantes."
}503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
{
"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.
Parâmetros de caminho
idstringobrigatórioO 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órioO telefone (só dígitos) ou o BSUID do usuário.1 a 160 caracteres · /^[A-Za-z0-9.]+$/
Respostas
200Sucesso.
donearray<object>obrigatórioOs usuários que a Meta aceitou bloquear ou desbloquear.done[].inputstring | nullobrigatórioO que você pediu, como a Meta o devolveu.done[].waIdstring | nullobrigatórioO telefone do usuário na Meta, quando ela o devolve.done[].userIdstring | nullobrigatórioO BSUID do usuário, quando a Meta o devolve.done[].reasonsarray<string>obrigatórioSó em failed: o motivo que a Meta deu. Texto dela.failedarray<object>obrigatórioOs que a Meta recusou, cada um com o motivo dela.failed[].inputstring | nullobrigatórioO que você pediu, como a Meta o devolveu.failed[].waIdstring | nullobrigatórioO telefone do usuário na Meta, quando ela o devolve.failed[].userIdstring | nullobrigatórioO BSUID do usuário, quando a Meta o devolve.failed[].reasonsarray<string>obrigatórioSó 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.
{
"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-AuthenticateSempre Bearer.
{
"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.
{
"error": "forbidden",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
"requiredScope": "numbers:read"
}{
"error": "test_key_not_allowed",
"docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
"message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
{
"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.
{
"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.
{
"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-AfterSegundos a esperar antes de repetir.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}{
"error": "management_busy",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "As operações de gestão desta conexão atingiram o limite momentâneo. Tente novamente em instantes."
}503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
{
"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.
Parâmetros de caminho
idstringobrigatórioO 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órioOs códigos do número.data[].codestringobrigatórioO código do QR, que vai no caminho de DELETE.data[].prefilledMessagestring | nullobrigatórioA mensagem que já vem escrita quando o contato abre a conversa.data[].linkstring | nullobrigatórioO link curto (wa.me) que abre a mesma conversa.data[].imageUrlstring | nullobrigatórioO 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.
{
"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-AuthenticateSempre Bearer.
{
"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.
{
"error": "forbidden",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
"requiredScope": "numbers:read"
}{
"error": "test_key_not_allowed",
"docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
"message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
{
"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.
{
"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.
{
"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-AfterSegundos a esperar antes de repetir.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}{
"error": "management_busy",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "As operações de gestão desta conexão atingiram o limite momentâneo. Tente novamente em instantes."
}503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
{
"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.
Parâmetros de caminho
idstringobrigatórioO 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
prefilledMessagestringobrigatórioA mensagem que já vem escrita. Até 140 caracteres, o limite da Meta, que está a confirmar na doc dela.1 a 140 caracteresimageFormatstringopcionalPeça a imagem do QR em PNG ou SVG. Sem isto, só o código e o link voltam.Valores:PNGSVG
Respostas
201Criado.
codestringobrigatórioO código do QR, que vai no caminho de DELETE.prefilledMessagestring | nullobrigatórioA mensagem que já vem escrita quando o contato abre a conversa.linkstring | nullobrigatórioO link curto (wa.me) que abre a mesma conversa.imageUrlstring | nullobrigatórioO 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.
{
"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-AuthenticateSempre Bearer.
{
"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.
{
"error": "forbidden",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
"requiredScope": "numbers:read"
}{
"error": "trial_expired",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"message": "O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."
}{
"error": "account_blocked",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."
}{
"error": "test_key_not_allowed",
"docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
"message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
{
"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.
{
"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.
{
"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.
{
"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-AfterSegundos a esperar antes de repetir.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}{
"error": "management_busy",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "As operações de gestão desta conexão atingiram o limite momentâneo. Tente novamente em instantes."
}503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
{
"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.
Parâmetros de caminho
idstringobrigatórioO 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órioO 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.
{
"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-AuthenticateSempre Bearer.
{
"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.
{
"error": "forbidden",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
"requiredScope": "numbers:read"
}{
"error": "test_key_not_allowed",
"docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
"message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
{
"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.
{
"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.
{
"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-AfterSegundos a esperar antes de repetir.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}{
"error": "management_busy",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "As operações de gestão desta conexão atingiram o limite momentâneo. Tente novamente em instantes."
}503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
{
"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.
Respostas
201Criado.
sessionIdstring (uuid)obrigatóriostatestringobrigatórioconfigIdstringobrigatóriosdkVersionstringobrigatórioA 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órioexpiresAtstringobrigatório
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
WWW-AuthenticateSempre Bearer.
{
"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.
{
"error": "forbidden",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
"requiredScope": "numbers:read"
}{
"error": "connection_not_released",
"docsUrl": "https://lunahia.com.br/docs/conectar-numero",
"message": "Esta conta ainda não pode conectar um número: falta confirmar o e-mail do cadastro. Abra o link que enviamos para esse e-mail e tente de novo. A lista faltando mostra o que ainda não foi cumprido.",
"faltando": [
"email_confirmado"
]
}{
"error": "trial_expired",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"message": "O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."
}{
"error": "account_blocked",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."
}{
"error": "test_key_not_allowed",
"docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
"message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}409O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.
{
"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-AfterSegundos a esperar antes de repetir.
{
"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.
{
"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.
Parâmetros de caminho
idstring (uuid)obrigatório
Respostas
200Sucesso.
sessionIdstring (uuid)obrigatóriostatestringobrigatórioorientacaostringobrigatórioterminalbooleanobrigatórioproximoPassostring | nullobrigatórioattemptCountintegerobrigatórionextAttemptAtstring | nullobrigatórioretryNotBeforestring | nullobrigatórioexpiresAtstringobrigatóriocreatedAtstringobrigatórioupdatedAtstringobrigató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.
{
"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-AuthenticateSempre Bearer.
{
"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.
{
"error": "forbidden",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
"requiredScope": "numbers:read"
}{
"error": "test_key_not_allowed",
"docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
"message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
{
"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-AfterSegundos a esperar antes de repetir.
{
"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.
{
"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.
Parâmetros de caminho
idstring (uuid)obrigatório
Corpo da requisição
csrfStatestringobrigatóriocurrentStepstring | nullopcional1 a 120 caractereserrorCodeinteger | nullopcionalerrorMessagestring | nullopcional
Respostas
200Sucesso.
sessionIdstring (uuid)obrigatóriostatestringobrigatórioorientacaostringobrigatórioabandonedAtStepstring | 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.
{
"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-AuthenticateSempre Bearer.
{
"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.
{
"error": "forbidden",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
"requiredScope": "numbers:read"
}{
"error": "test_key_not_allowed",
"docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
"message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
{
"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.
{
"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-AfterSegundos a esperar antes de repetir.
{
"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.
{
"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.
Parâmetros de caminho
idstring (uuid)obrigatório
Corpo da requisição
codestringobrigatóriocsrfStatestringobrigatóriowabaIdstring | nullopcionalphoneNumberIdstring | nullopcionalbusinessIdstring | nullopcional
Respostas
200Sucesso.
sessionIdstring (uuid)obrigatóriostatestringobrigatórioorientacaostringobrigatórioterminalbooleanobrigatórioproximoPassostring | nullobrigatóriomotivostring | nullobrigatóriopodeRetentarbooleanobrigatóriowabaIdstring | nullobrigatóriophoneNumberIdstring | 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.
{
"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-AuthenticateSempre Bearer.
{
"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.
{
"error": "forbidden",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
"requiredScope": "numbers:read"
}{
"error": "trial_expired",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"message": "O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."
}{
"error": "account_blocked",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."
}{
"error": "test_key_not_allowed",
"docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
"message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
{
"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.
{
"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-AfterSegundos a esperar antes de repetir.
{
"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.
{
"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.
Parâmetros de consulta
externalIdstringopcionalO rótulo que você deu ao seu cliente. Igualdade exata; rótulo sem número devolve lista vazia.1 a 128 caracteresstatestringopcionalO estado do número (state): PENDING, REGISTER_SENT, REGISTERED, PIN_REQUIRED, BLOCKED ou DISCONNECTED.Valores:PENDINGREGISTER_SENTREGISTEREDPIN_REQUIREDBLOCKEDDISCONNECTEDqstringopcionalBusca 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 caractereswabaIdstringopcionalO 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 caracteresqualityRatingstringopcionalA 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:GREENYELLOWREDNAUNKNOWNconnectionStatusstringopcionalSó os números com este connection.status: connected, connecting, action_required ou disconnected.Valores:connectedconnectingaction_requireddisconnectedreadystringopcionaltrue: só os números prontos para enviar e receber. false: só os que ainda não estão.Valores:truefalsecanSendstringopcionaltrue: só os números por onde enviar funciona agora (connection.canSend). false: só os que não.Valores:truefalselimitintegeropcionalQuantos números por página: de 1 a 100, 50 se omitido.mínimo 1 · máximo 100cursorstringopcionalO nextCursor da resposta anterior. Opaco: carrega posição, não contagem.até 256 caracteres
Respostas
200Sucesso.
dataarray<object>obrigatóriodata[].idstring (uuid)obrigatóriodata[].metaPhoneNumberIdstringobrigatóriodata[].displayNumberstring | nullobrigatóriodata[].statestringobrigatóriodata[].retryNotBeforestring | nullobrigatóriodata[].podeRetentarbooleanobrigatóriodata[].qualityRatingstring | nullobrigatóriodata[].throughputLevelstring | nullobrigatórioA 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órioO 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óriodata[].displayNamestring | nullobrigatórioO 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órioO 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órioO 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órioQuando 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órioO 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órioUm 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órioO 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órioQuando 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órioO 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órioO identificador da conta de negócio do número na Meta (WABA).data[].waba.restrictedbooleanobrigatóriotrue 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óriotrue quando a Meta avisou que desativou a conta.data[].waba.credentialExpiresAtstring | nullobrigatórioQuando 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óriotrue: 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óriotrue: 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órioA moeda da conta na Meta, como ela informa (por exemplo BRL). Nulo quando ainda não lida.data[].readybooleanobrigatóriotrue 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órioO 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órioO 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:connectedconnectingaction_requireddisconnecteddata[].connection.canSendbooleanobrigatórioSe 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órioPor 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órioO código do motivo, para o seu código comparar. Novos códigos podem aparecer.data[].connection.reasons[].messagestringobrigatórioO que está acontecendo, em português, pronto para repassar ao seu cliente.data[].connection.reasons[].solutionstringobrigatórioO que fazer a respeito, em português.data[].connection.reasons[].actionstring | nullobrigatórioA 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_pinreconnectreconnect_linkmeta_managerwaitcontact_helsendata[].connection.reasons[].actionUrlstring | nullobrigatórioO endereço da conta no WhatsApp Manager da Meta. Só vem quando action é meta_manager.data[].connection.reasons[].docsUrlstring | nullobrigatórioO guia do site que explica o motivo.data[].connection.reasons[].sincestring | nullobrigatórioDesde 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órioO 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órioAs 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órioValores:disconnectreconnectreconnect_linksend_pinedit_labeldata[].blockedActions[].messagestringobrigatórioPor que a ação não está disponível agora, em português, pronto para mostrar.data[].createdAtstringobrigatóriodata[].updatedAtstringobrigatórionextCursorstring | nullobrigatórioMande 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.
{
"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-AuthenticateSempre Bearer.
{
"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.
{
"error": "forbidden",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
"requiredScope": "numbers:read"
}{
"error": "test_key_not_allowed",
"docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
"message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}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-AfterSegundos a esperar antes de repetir.
{
"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.
{
"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.
Parâmetros de caminho
idstringobrigatórioO 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óriometaPhoneNumberIdstringobrigatóriodisplayNumberstring | nullobrigatóriostatestringobrigatórioretryNotBeforestring | nullobrigatóriopodeRetentarbooleanobrigatórioqualityRatingstring | nullobrigatóriothroughputLevelstring | nullobrigatórioA 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órioO 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óriodisplayNamestring | nullobrigatórioO 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órioO 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órioO 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órioQuando 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órioO 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órioUm 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órioO 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órioQuando 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órioO 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órioO identificador da conta de negócio do número na Meta (WABA).waba.restrictedbooleanobrigatóriotrue quando a Meta avisou uma restrição da conta e ela ainda vale. Os detalhes estão em GET /v1/business-accounts.waba.disabledbooleanobrigatóriotrue quando a Meta avisou que desativou a conta.waba.credentialExpiresAtstring | nullobrigatórioQuando 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óriotrue: 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óriotrue: 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órioA moeda da conta na Meta, como ela informa (por exemplo BRL). Nulo quando ainda não lida.readybooleanobrigatóriotrue 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órioconnection.statusstringobrigatórioO 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:connectedconnectingaction_requireddisconnectedconnection.canSendbooleanobrigatórioSe 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órioPor 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órioO código do motivo, para o seu código comparar. Novos códigos podem aparecer.connection.reasons[].messagestringobrigatórioO que está acontecendo, em português, pronto para repassar ao seu cliente.connection.reasons[].solutionstringobrigatórioO que fazer a respeito, em português.connection.reasons[].actionstring | nullobrigatórioA 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_pinreconnectreconnect_linkmeta_managerwaitcontact_helsenconnection.reasons[].actionUrlstring | nullobrigatórioO endereço da conta no WhatsApp Manager da Meta. Só vem quando action é meta_manager.connection.reasons[].docsUrlstring | nullobrigatórioO guia do site que explica o motivo.connection.reasons[].sincestring | nullobrigatórioDesde 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órioOs 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órioValores:authorizedreceivingregisteredreadyconnection.steps[].labelstringobrigatórioO nome do passo, em português. Em coexistência o terceiro passo se chama Número vinculado.connection.steps[].statusstringobrigatórioValores:donecurrentpendingallowedActionsarray<string>obrigatórioO 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órioAs 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órioValores:disconnectreconnectreconnect_linksend_pinedit_labelblockedActions[].messagestringobrigatórioPor que a ação não está disponível agora, em português, pronto para mostrar.createdAtstringobrigatórioupdatedAtstringobrigatóriotetoDeVazaoPorSegundonumber | nullobrigatórioO 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órioEm 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órioAté 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órioO 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órioQuando 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órioO 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órioSe a autorização deste número admite reconexão. Quando for true, POST /v1/onboarding/reconnect abre a sessão que a substitui.coexistencebooleanobrigatóriotrue 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.
{
"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-AuthenticateSempre Bearer.
{
"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.
{
"error": "forbidden",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
"requiredScope": "numbers:read"
}{
"error": "test_key_not_allowed",
"docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
"message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
{
"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-AfterSegundos a esperar antes de repetir.
{
"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.
{
"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.
Parâmetros de caminho
idstringobrigatórioO 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
externalIdstring | nullopcionalO seu identificador para o cliente dono do número (1 a 128 caracteres). null limpa.1 a 128 caractereslabelstring | nullopcionalUm nome livre e curto para reconhecer o número (1 a 128 caracteres). null limpa.1 a 128 caracteresautoReadbooleanopcionaltrue: 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óriometaPhoneNumberIdstringobrigatóriodisplayNumberstring | nullobrigatóriostatestringobrigatórioretryNotBeforestring | nullobrigatóriopodeRetentarbooleanobrigatórioqualityRatingstring | nullobrigatóriothroughputLevelstring | nullobrigatórioA 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órioO 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óriodisplayNamestring | nullobrigatórioO 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órioO 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órioO 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órioQuando 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órioO 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órioUm 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órioO 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órioQuando 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órioO 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órioO identificador da conta de negócio do número na Meta (WABA).waba.restrictedbooleanobrigatóriotrue quando a Meta avisou uma restrição da conta e ela ainda vale. Os detalhes estão em GET /v1/business-accounts.waba.disabledbooleanobrigatóriotrue quando a Meta avisou que desativou a conta.waba.credentialExpiresAtstring | nullobrigatórioQuando 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óriotrue: 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óriotrue: 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órioA moeda da conta na Meta, como ela informa (por exemplo BRL). Nulo quando ainda não lida.readybooleanobrigatóriotrue 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órioconnection.statusstringobrigatórioO 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:connectedconnectingaction_requireddisconnectedconnection.canSendbooleanobrigatórioSe 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órioPor 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órioO código do motivo, para o seu código comparar. Novos códigos podem aparecer.connection.reasons[].messagestringobrigatórioO que está acontecendo, em português, pronto para repassar ao seu cliente.connection.reasons[].solutionstringobrigatórioO que fazer a respeito, em português.connection.reasons[].actionstring | nullobrigatórioA 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_pinreconnectreconnect_linkmeta_managerwaitcontact_helsenconnection.reasons[].actionUrlstring | nullobrigatórioO endereço da conta no WhatsApp Manager da Meta. Só vem quando action é meta_manager.connection.reasons[].docsUrlstring | nullobrigatórioO guia do site que explica o motivo.connection.reasons[].sincestring | nullobrigatórioDesde 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órioOs 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órioValores:authorizedreceivingregisteredreadyconnection.steps[].labelstringobrigatórioO nome do passo, em português. Em coexistência o terceiro passo se chama Número vinculado.connection.steps[].statusstringobrigatórioValores:donecurrentpendingallowedActionsarray<string>obrigatórioO 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órioAs 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órioValores:disconnectreconnectreconnect_linksend_pinedit_labelblockedActions[].messagestringobrigatórioPor que a ação não está disponível agora, em português, pronto para mostrar.createdAtstringobrigatórioupdatedAtstringobrigatóriotetoDeVazaoPorSegundonumber | nullobrigatórioO 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órioEm 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órioAté 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órioO 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órioQuando 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órioO 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órioSe a autorização deste número admite reconexão. Quando for true, POST /v1/onboarding/reconnect abre a sessão que a substitui.coexistencebooleanobrigatóriotrue 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.
{
"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-AuthenticateSempre Bearer.
{
"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.
{
"error": "forbidden",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
"requiredScope": "numbers:read"
}{
"error": "trial_expired",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"message": "O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."
}{
"error": "account_blocked",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."
}{
"error": "test_key_not_allowed",
"docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
"message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
{
"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.
{
"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-AfterSegundos a esperar antes de repetir.
{
"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.
{
"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.
Parâmetros de caminho
idstringobrigatórioO 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.
{
"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-AuthenticateSempre Bearer.
{
"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.
{
"error": "forbidden",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
"requiredScope": "numbers:read"
}{
"error": "test_key_not_allowed",
"docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
"message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
{
"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-AfterSegundos a esperar antes de repetir.
{
"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.
{
"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.
Parâmetros de caminho
idstringobrigatórioO 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
pinstringobrigatórioO 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órioO identificador deste número na Luna.statestringobrigatórioO 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.
{
"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-AuthenticateSempre Bearer.
{
"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.
{
"error": "forbidden",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
"requiredScope": "numbers:read"
}{
"error": "trial_expired",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"message": "O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."
}{
"error": "account_blocked",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."
}{
"error": "test_key_not_allowed",
"docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
"message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
{
"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.
{
"error": "pin_not_applicable",
"docsUrl": "https://lunahia.com.br/docs/conectar-numero",
"message": "Este número não está aguardando o PIN de verificação em duas etapas. O campo state diz em que ponto ele está."
}{
"error": "register_budget_reserved",
"docsUrl": "https://lunahia.com.br/docs/conectar-numero",
"message": "As tentativas de registro que a Meta concede a este número em 72 horas estão perto do fim, e a plataforma guarda as últimas para não travar o número. Confirme o PIN com o negócio final antes de submeter de novo.",
"tentativasRestantes": 1,
"janelaVira": "2026-10-09T12:00:00.000Z"
}{
"error": "number_capacity_reached",
"message": "Esta conta já tem 20 números ativos, o máximo contratado (20). Para conectar outro, desconecte um número (DELETE /v1/numbers/{id}) ou escreva para contato@lunahia.com.br.",
"capacity": 20,
"activeNumbers": 20
}415O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.
{
"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-AfterSegundos a esperar antes de repetir.
{
"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.
{
"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.
Corpo da requisição
numberIdstringobrigatórioO 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óriostatestringobrigatórioconfigIdstringobrigatóriosdkVersionstringobrigatórioA 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órioexpiresAtstringobrigató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.
{
"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-AuthenticateSempre Bearer.
{
"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.
{
"error": "forbidden",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
"requiredScope": "numbers:read"
}{
"error": "connection_not_released",
"docsUrl": "https://lunahia.com.br/docs/conectar-numero",
"message": "Esta conta ainda não pode conectar um número: falta confirmar o e-mail do cadastro. Abra o link que enviamos para esse e-mail e tente de novo. A lista faltando mostra o que ainda não foi cumprido.",
"faltando": [
"email_confirmado"
]
}{
"error": "trial_expired",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"message": "O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."
}{
"error": "account_blocked",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."
}{
"error": "test_key_not_allowed",
"docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
"message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
{
"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.
{
"error": "reconnect_not_applicable",
"docsUrl": "https://lunahia.com.br/docs/conectar-numero",
"message": "A autorização deste número não admite reconexão.",
"credentialStatus": "active"
}{
"error": "number_capacity_reached",
"message": "Esta conta já tem 20 números ativos, o máximo contratado (20). Para conectar outro, desconecte um número (DELETE /v1/numbers/{id}) ou escreva para contato@lunahia.com.br.",
"capacity": 20,
"activeNumbers": 20
}415O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.
{
"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-AfterSegundos a esperar antes de repetir.
{
"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.
{
"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.
Respostas
200Sucesso.
dataarray<object>obrigatóriodata[].idstring (uuid)obrigatóriodata[].wabaIdstringobrigatóriodata[].numbersarray<string>obrigatóriodata[].namestring | nullobrigatórioO nome da conta de WhatsApp Business como a Meta o informa. Nulo enquanto a Luna ainda não o leu.data[].managerUrlstringobrigatórioO 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órioOs 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órioO id do número na Luna, o mesmo de GET /v1/numbers.data[].phoneNumbers[].displayNumberstring | nullobrigatórioO número como se lê no telefone, ou nulo enquanto a Luna não o leu.data[].phoneNumbers[].externalIdstring | nullobrigatórioO seu rótulo para o cliente dono do número.data[].phoneNumbers[].labelstring | nullobrigatórioO nome que você deu ao número.data[].statusobjectobrigatórioO último estado de saúde conhecido da conta.data[].status.restrictedbooleanobrigatóriotrue 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órioAs 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óriodata[].status.restrictions[].expirationstring | nullobrigatóriodata[].status.restrictions[].remediationstring | nullobrigatóriodata[].status.disabledbooleanobrigatóriotrue 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órioO 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órioQuando chegou o aviso de saúde mais recente, ou nulo se nunca chegou.data[].credentialExpiresAtstring | nullobrigatórioQuando 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óriotrue: 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óriotrue 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órioA 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-AuthenticateSempre Bearer.
{
"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.
{
"error": "forbidden",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
"requiredScope": "numbers:read"
}{
"error": "test_key_not_allowed",
"docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
"message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}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-AfterSegundos a esperar antes de repetir.
{
"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.
{
"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.
Parâmetros de caminho
idstring (uuid)obrigatórioO id da conta de negócio na Luna, o mesmo que GET /v1/business-accounts devolve em id.
Respostas
200Sucesso.
idstring (uuid)obrigatóriowabaIdstringobrigatóriopaymentMethodOnMetaboolean | nullobrigatóriotrue: a conta tem forma de pagamento na Meta. false: não tem. Nulo: a Luna ainda não conseguiu ler.currencystring | nullobrigatórioA moeda da conta na Meta, como ela informa. Nulo quando ainda não lida.checkedAtstring | nullobrigatórioQuando a Luna leu a forma de pagamento da Meta pela última vez, em ISO-8601 UTC. Nulo se nunca leu.refreshedbooleanobrigatóriotrue quando esta chamada leu na Meta agora. false quando devolveu a leitura que já existia.reasonstringobrigatóriochecked: 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:checkedrecentbusyfailed
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.
{
"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-AuthenticateSempre Bearer.
{
"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.
{
"error": "forbidden",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
"requiredScope": "numbers:read"
}{
"error": "trial_expired",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"message": "O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."
}{
"error": "account_blocked",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."
}{
"error": "test_key_not_allowed",
"docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
"message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
{
"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-AfterSegundos a esperar antes de repetir.
{
"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.
{
"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.
Parâmetros de caminho
idstringobrigatórioO 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órioqualityRatingstring | nullobrigatóriothroughputLevelstring | nullobrigatóriotetoDeVazaoPorSegundonumber | nullobrigatórioO 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órioEm 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órioAté 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órioO 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óriocodeVerificationStatusstring | nullobrigatóriocheckedAtstring | nullobrigatóriotransitionsarray<object>obrigatóriotransitions[].qualityRatingstring | nullobrigatóriotransitions[].throughputLevelstring | nullobrigatóriotransitions[].limiteDiarioDeConversasstring | nullobrigatóriotransitions[].codeVerificationStatusstring | nullobrigatóriotransitions[].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.
{
"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-AuthenticateSempre Bearer.
{
"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.
{
"error": "forbidden",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
"requiredScope": "numbers:read"
}{
"error": "test_key_not_allowed",
"docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
"message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
{
"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-AfterSegundos a esperar antes de repetir.
{
"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.
{
"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.
Parâmetros de consulta
numberIdstringopcionalO 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_-]+$/externalIdstringopcionalO 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 caracteresstartstring (date-time) | string (date)opcionalO 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)opcionalO fim do período, em ISO 8601. Ausente, agora (arredondado para baixo a cada cinco minutos).granularitystringopcionalO 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_HOURDAILYMONTHLYformatstringopcionaljson (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:jsoncsv
Respostas
200Sucesso.
numberIdstring (uuid) | nullobrigatórioO id do número na Luna, quando você consultou por numberId. Nulo quando consultou por externalId.phoneNumberIdstring | nullobrigatórioO id do número na Meta, quando você consultou por numberId. Nulo quando consultou por externalId.externalIdstring | nullobrigatórioO rótulo do cliente, quando você consultou por externalId. Nulo quando consultou por numberId.startstringobrigatórioO começo do período consultado, em ISO 8601.endstringobrigatórioO fim do período consultado, em ISO 8601.granularitystringobrigatórioValores:HALF_HOURDAILYMONTHLYreadAtstringobrigatórioQuando 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órioO 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órioOs números cobertos pela consulta, inclusive os que ficaram de fora e os que não tiveram nenhum ponto.numbers[].numberIdstring (uuid)obrigatórioO id do número na Luna.numbers[].phoneNumberIdstringobrigatórioO id do número na Meta.numbers[].currencystring | nullobrigatórioA moeda da conta do negócio na Meta. Nulo quando a Luna ainda não a leu.numbers[].readbooleanobrigatóriotrue quando a Luna leu o consumo deste número. false quando ele ficou de fora, e reason diz por quê.numbers[].reasonstring | nullobrigatórioPor 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órioOs 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órioO número da Luna a que este ponto pertence.data[].phoneNumberIdstringobrigatórioO id do mesmo número na Meta.data[].currencystring | nullobrigatórioA 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órioO começo do ponto, em ISO 8601. Nulo quando a Meta não informou.data[].endstring | nullobrigatórioO fim do ponto, em ISO 8601. Nulo quando a Meta não informou.data[].pricingCategorystring | nullobrigatórioA categoria de cobrança, como a Meta a nomeia (por exemplo MARKETING, UTILITY, SERVICE). Novos valores podem aparecer.data[].pricingTypestring | nullobrigatórioO tipo de cobrança, como a Meta o nomeia (por exemplo REGULAR, FREE_CUSTOMER_SERVICE). Novos valores podem aparecer.data[].tierstring | nullobrigatórioA faixa de volume da Meta, no formato que ela manda (por exemplo "0:750000"). Nulo quando não veio.data[].countrystring | nullobrigatórioO país do destinatário, como a Meta informou. Nulo quando não veio.data[].volumenumber | nullobrigatórioO volume que a Meta mediu neste ponto. É dela, aproximado, e nunca é somado pela Luna.data[].costnumber | nullobrigatórioO 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.
{
"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-AuthenticateSempre Bearer.
{
"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.
{
"error": "forbidden",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
"requiredScope": "numbers:read"
}{
"error": "test_key_not_allowed",
"docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
"message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}409O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.
{
"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.
{
"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-AfterSegundos a esperar antes de repetir.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}{
"error": "management_busy",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "As operações de gestão desta conexão atingiram o limite momentâneo. Tente novamente em instantes."
}503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
{
"error": "unavailable",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}