LunaDocs

Carregando a busca...

EnglishEntrar no console
Nesta página

Templates

Usar com IA

Mensagens pré-aprovadas pela Meta, necessárias para iniciar conversa fora da janela de 24 horas.

Aprovado não é liberado para volume: a Meta aplica um ritmo próprio sobre os primeiros envios de um template novo, e não publica prazo nem mecânica. Escalone o primeiro disparo em vez de programá-lo para uma data, e acompanhe o estado do template.

Acima de três botões, apenas dois aparecem na mensagem entregue. A Meta aceita o template com mais e entrega dois, então o arranjo precisa ser decidido antes de o fluxo ser desenhado.

Listar templates

GET/v1/templates

Os templates deste cliente, do mais recente para o mais antigo.

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

Parâmetros de consulta

  • statusstringopcional
    Devolve apenas os templates cujo último estado observado é exatamente este valor. A comparação é literal e sensível a maiúsculas. Valores comuns: APPROVED, PENDING, REJECTED, PAUSED, DISABLED, mas o campo é texto livre, porque a Meta acrescenta estado sem aviso e um conjunto fechado impediria você de filtrar pelo estado novo.1 a 64 caracteres
  • wabaIdstringopcional
    Devolve apenas os templates desta conta de negócio na Meta (WABA), o wabaId que GET /v1/business-accounts devolve. Com um cliente seu por conta, é o jeito de ver só os templates dele. Comparação exata.1 a 64 caracteres
  • phoneNumberIdstringopcional
    Devolve apenas os templates da conta de negócio a que este número pertence. Aceita o UUID da Luna (o id de GET /v1/numbers) ou o id da Meta (metaPhoneNumberId). Template é da conta, e não do número: todos os números da conta compartilham os mesmos templates.1 a 64 caracteres · /^[A-Za-z0-9_-]+$/

Respostas

200Sucesso.
  • dataarray<object>obrigatório
  • data[].idstring (uuid)obrigatório
  • data[].metaTemplateIdstringobrigatório
  • data[].wabaIdstringobrigatório
  • data[].namestringobrigatório
  • data[].languagestringobrigatório
  • data[].categorystringobrigatório
  • data[].statusstringobrigatório
  • data[].createdAtstringobrigatório
  • data[].updatedAtstringobrigatório
  • data[].bodyTextstring | nullobrigatório
    O corpo do template, com as variáveis na forma {{nome}}. Nulo quando a Luna não conhece o conteúdo: template criado antes de ela passar a guardá-lo, ou direto no painel da Meta. Nesse caso header, footer, buttons e variables também vêm vazios.
  • data[].headerstring | nullobrigatório
    O cabeçalho de texto. Nulo quando não há.
  • data[].headerMediaobject | nullobrigatório
    O cabeçalho de imagem, vídeo ou documento: só o formato, porque o arquivo era o exemplo que a Meta revisou. Nulo quando não há.
  • data[].headerMedia.formatstringobrigatório
    IMAGE, VIDEO ou DOCUMENT.
  • data[].footerstring | nullobrigatório
    O rodapé. Nulo quando não há.
  • data[].buttonsarray<object>obrigatório
    Os botões, na mesma forma em que POST /v1/templates os recebe. Vazio quando não há, ou quando o conteúdo é desconhecido.
  • data[].buttons[].typestringopcional
    Valores: QUICK_REPLY
  • data[].buttons[].textstringopcional
    1 a 25 caracteres
  • data[].buttons[].urlstringopcional
    1 a 2000 caracteres
  • data[].buttons[].examplearray<string>opcional
    até 1 itens
  • data[].buttons[].phone_numberstringopcional
    1 a 20 caracteres
  • data[].variablesarray<object>obrigatório
    As variáveis do corpo, na ordem em que aparecem, cada uma com o exemplo. A tela não precisa extrair {{nome}} do texto.
  • data[].variables[].namestringobrigatório
    O nome da variável, o que está entre {{ e }} no corpo.
  • data[].variables[].examplestringobrigatório
    O exemplo que foi mandado para a Meta junto com a variável.
  • data[].rejectedReasonstring | nullobrigatório
    Por que a Meta rejeitou o template, como ela informou (o valor entra como veio). Só tem valor enquanto status é REJECTED, e nulo quando a Meta não mandou a razão.
  • data[].qualityScorestring | nullobrigatório
    A nota de qualidade do template segundo o último aviso da Meta, como ela informou: GREEN, YELLOW, RED ou UNKNOWN, e valores novos podem aparecer. Nulo enquanto a Meta não avisou nenhuma.
  • data[].previousCategorystring | nullobrigatório
    A categoria que o template tinha antes de a Meta mudá-la, quando ela mudou. Nulo quando a categoria nunca mudou.
  • data[].allowedActionsarray<string>obrigatório
    O que a conta pode fazer com o template agora: edit (PATCH /v1/templates/{id}) e delete (DELETE /v1/templates/{id}). Vazio com a conta suspensa. Em quais estados a Meta aceita editar é decisão dela, e a recusa dela chega como erro.
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
Campo recusado, com o motivoJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Criar um template

POST/v1/templates

Cria o template na conta do cliente e o submete à Meta para aprovação.

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

Corpo da requisição

application/json · obrigatório

  • wabaIdstringobrigatório
    1 a 64 caracteres · /^[A-Za-z0-9_-]+$/
  • namestringobrigatório
    /^[a-z0-9_]{1,512}$/
  • bodyTextstringobrigatório
    1 a 1024 caracteres
  • examplesobjectopcional
    Um valor de amostra por variável do corpo. Obrigatório quando o corpo tem `{{variavel}}`, porque a Meta recusa parâmetro sem exemplo.
  • headerstringopcional
    Cabeçalho de texto, exibido acima do corpo. Para cabeçalho de imagem, vídeo ou documento, use headerMedia.1 a 60 caracteres
  • headerMediaobjectopcional
    Cabeçalho de imagem, vídeo ou documento. O handle vem de POST /v1/template-assets, e não do identificador de mídia de mensagem. O arquivo é o exemplo que a Meta revisa, e não o conteúdo entregue: cada mensagem enviada fornece a própria mídia.
  • headerMedia.formatstringobrigatório
    IMAGE, VIDEO ou DOCUMENT. Para documento a Meta aceita apenas PDF.Valores: IMAGE VIDEO DOCUMENT
  • headerMedia.handlestringobrigatório
    O handle devolvido por POST /v1/template-assets.1 a 2048 caracteres
  • footerstringopcional
    Rodapé, exibido abaixo do corpo. Não aceita variável.1 a 60 caracteres
  • buttonsarray<object>opcional
    Até 10 botões no total, somando todos os tipos. Se houver respostas rápidas junto de outros botões, os dois conjuntos precisam ficar agrupados: respostas rápidas de um lado, o resto do outro. Acima de três botões, apenas dois aparecem na mensagem entregue: a Meta aceita o template e entrega dois.
  • buttons[].typestringopcional
    Valores: QUICK_REPLY
  • buttons[].textstringopcional
    1 a 25 caracteres
  • buttons[].urlstringopcional
    1 a 2000 caracteres
  • buttons[].examplearray<string>opcional
    até 1 itens
  • buttons[].phone_numberstringopcional
    1 a 20 caracteres
  • categorystringopcional
    A categoria do template. Ausente vale UTILITY, que é o comportamento de quem já integra e não manda o campo. A Meta pode reclassificar na criação: o template continua aprovado, com outra categoria, e a resposta traz a que ela atribuiu. Template de autenticação tem corpo próprio e ainda não é criado por esta rota.Valores: MARKETING UTILITY
  • languagestringopcional
    O código de idioma do template, na grafia da Meta: sublinhado e não hífen. pt_BR, pt_PT, en_US, es_MX, fr. A lista completa está em Supported Languages, na documentação da Meta, e o campo aceita qualquer código que ela publicar, porque um conjunto fechado aqui impediria você de usar o próximo. Ausente vale pt_BR. Atenção ao que o idioma custa: cada idioma é um template separado para a Meta, e o teto é de 250 templates por conta de WhatsApp Business./^[a-z]{2,3}(_[A-Z]{2})?$/

Respostas

201Criado.
  • idstring (uuid)obrigatório
  • metaTemplateIdstringobrigatório
  • wabaIdstringobrigatório
    O id da conta de negócio na Meta (WABA) a que o template pertence, o mesmo wabaId que GET /v1/templates devolve e que POST /v1/templates recebe.
  • namestringobrigatório
  • languagestringobrigatório
  • categorystringobrigatório
  • statusstringobrigatório
  • createdAtstringobrigatório
  • updatedAtstringobrigatório
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
Campo recusado, com o motivoJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Teste grátis terminadoJSON
{
  "error": "trial_expired",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."
}
Conta bloqueada pela HelsenJSON
{
  "error": "account_blocked",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
Não existe, ou não é seuJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
415O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.
Tipo de conteúdo não lidoJSON
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
Gestão da conta ocupadaJSON
{
  "error": "management_busy",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "As operações de gestão desta conexão atingiram o limite momentâneo. Tente novamente em instantes."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Consultar um template

GET/v1/templates/{id}

O estado atual do template na Meta, o conteúdo que você escreveu e o que a Meta avisou sobre ele.

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

Parâmetros de caminho

  • idstring (uuid)obrigatório

Respostas

200Sucesso.
  • idstring (uuid)obrigatório
  • metaTemplateIdstringobrigatório
  • wabaIdstringobrigatório
    O id da conta de negócio na Meta (WABA) a que o template pertence, o mesmo wabaId que GET /v1/templates devolve e que POST /v1/templates recebe.
  • namestringobrigatório
  • languagestringobrigatório
  • categorystringobrigatório
  • statusstringobrigatório
  • createdAtstringobrigatório
  • updatedAtstringobrigatório
  • bodyTextstring | nullobrigatório
    O corpo do template, com as variáveis na forma {{nome}}. Nulo quando a Luna não conhece o conteúdo: template criado antes de ela passar a guardá-lo, ou direto no painel da Meta. Nesse caso header, footer, buttons e variables também vêm vazios.
  • headerstring | nullobrigatório
    O cabeçalho de texto. Nulo quando não há.
  • headerMediaobject | nullobrigatório
    O cabeçalho de imagem, vídeo ou documento: só o formato, porque o arquivo era o exemplo que a Meta revisou. Nulo quando não há.
  • headerMedia.formatstringobrigatório
    IMAGE, VIDEO ou DOCUMENT.
  • footerstring | nullobrigatório
    O rodapé. Nulo quando não há.
  • buttonsarray<object>obrigatório
    Os botões, na mesma forma em que POST /v1/templates os recebe. Vazio quando não há, ou quando o conteúdo é desconhecido.
  • buttons[].typestringopcional
    Valores: QUICK_REPLY
  • buttons[].textstringopcional
    1 a 25 caracteres
  • buttons[].urlstringopcional
    1 a 2000 caracteres
  • buttons[].examplearray<string>opcional
    até 1 itens
  • buttons[].phone_numberstringopcional
    1 a 20 caracteres
  • variablesarray<object>obrigatório
    As variáveis do corpo, na ordem em que aparecem, cada uma com o exemplo. A tela não precisa extrair {{nome}} do texto.
  • variables[].namestringobrigatório
    O nome da variável, o que está entre {{ e }} no corpo.
  • variables[].examplestringobrigatório
    O exemplo que foi mandado para a Meta junto com a variável.
  • rejectedReasonstring | nullobrigatório
    Por que a Meta rejeitou o template, como ela informou (o valor entra como veio). Só tem valor enquanto status é REJECTED, e nulo quando a Meta não mandou a razão.
  • qualityScorestring | nullobrigatório
    A nota de qualidade do template segundo o último aviso da Meta, como ela informou: GREEN, YELLOW, RED ou UNKNOWN, e valores novos podem aparecer. Nulo enquanto a Meta não avisou nenhuma.
  • previousCategorystring | nullobrigatório
    A categoria que o template tinha antes de a Meta mudá-la, quando ela mudou. Nulo quando a categoria nunca mudou.
  • allowedActionsarray<string>obrigatório
    O que a conta pode fazer com o template agora: edit (PATCH /v1/templates/{id}) e delete (DELETE /v1/templates/{id}). Vazio com a conta suspensa. Em quais estados a Meta aceita editar é decisão dela, e a recusa dela chega como erro.
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
Campo recusado, com o motivoJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
Não existe, ou não é seuJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
Gestão da conta ocupadaJSON
{
  "error": "management_busy",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "As operações de gestão desta conexão atingiram o limite momentâneo. Tente novamente em instantes."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Editar um template

PATCH/v1/templates/{id}

Altera os componentes de um template existente.

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

Parâmetros de caminho

  • idstring (uuid)obrigatório

Corpo da requisição

application/json · obrigatório

  • bodyTextstringopcional
    1 a 1024 caracteres
  • examplesobjectopcional
  • headerstringopcional
    Cabeçalho de texto, exibido acima do corpo. Para cabeçalho de imagem, vídeo ou documento, use headerMedia.1 a 60 caracteres
  • footerstringopcional
    Rodapé, exibido abaixo do corpo. Não aceita variável.1 a 60 caracteres
  • buttonsarray<object>opcional
    Até 10 botões no total, somando todos os tipos. Se houver respostas rápidas junto de outros botões, os dois conjuntos precisam ficar agrupados: respostas rápidas de um lado, o resto do outro. Acima de três botões, apenas dois aparecem na mensagem entregue: a Meta aceita o template e entrega dois.
  • buttons[].typestringopcional
    Valores: QUICK_REPLY
  • buttons[].textstringopcional
    1 a 25 caracteres
  • buttons[].urlstringopcional
    1 a 2000 caracteres
  • buttons[].examplearray<string>opcional
    até 1 itens
  • buttons[].phone_numberstringopcional
    1 a 20 caracteres

Respostas

200Sucesso.
  • idstring (uuid)obrigatório
  • metaTemplateIdstringobrigatório
  • wabaIdstringobrigatório
    O id da conta de negócio na Meta (WABA) a que o template pertence, o mesmo wabaId que GET /v1/templates devolve e que POST /v1/templates recebe.
  • namestringobrigatório
  • languagestringobrigatório
  • categorystringobrigatório
  • statusstringobrigatório
  • createdAtstringobrigatório
  • updatedAtstringobrigatório
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
Campo recusado, com o motivoJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Teste grátis terminadoJSON
{
  "error": "trial_expired",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."
}
Conta bloqueada pela HelsenJSON
{
  "error": "account_blocked",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
Não existe, ou não é seuJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
415O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.
Tipo de conteúdo não lidoJSON
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
Gestão da conta ocupadaJSON
{
  "error": "management_busy",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "As operações de gestão desta conexão atingiram o limite momentâneo. Tente novamente em instantes."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Remover um template

DELETE/v1/templates/{id}

Remove o template na Meta e da sua listagem.

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

Parâmetros de caminho

  • idstring (uuid)obrigatório

Respostas

204Sem conteúdo: a operação foi feita e a resposta não tem corpo.
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
Campo recusado, com o motivoJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Teste grátis terminadoJSON
{
  "error": "trial_expired",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."
}
Conta bloqueada pela HelsenJSON
{
  "error": "account_blocked",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
Não existe, ou não é seuJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
Gestão da conta ocupadaJSON
{
  "error": "management_busy",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "As operações de gestão desta conexão atingiram o limite momentâneo. Tente novamente em instantes."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Ler as regras de um template

GET/v1/templates/rules

As categorias, os idiomas sugeridos, o formato do nome, os tamanhos máximos de corpo, cabeçalho e rodapé, e os limites de botões. É o que POST /v1/templates cobra, servido para você mostrar o mesmo limite sem copiar o número.

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

Respostas

200Sucesso.
  • categoriesarray<object>obrigatório
    As categorias que a criação aceita. A Meta pode reclassificar o template depois.
  • categories[].valuestringobrigatório
    O que vai em category ao criar o template.
  • categories[].labelstringobrigatório
    O nome da categoria, em português.
  • categories[].summarystringobrigatório
    Quando usar, em uma ou duas frases.
  • languagesarray<object>obrigatório
    Idiomas sugeridos. Não é lista fechada: vale qualquer código que a Meta publique, no formato de language em POST /v1/templates.
  • languages[].codestringobrigatório
  • languages[].labelstringobrigatório
  • namePatternstringobrigatório
    A expressão regular que o name precisa cumprir, em sintaxe de JavaScript e sem as barras.
  • nameExamplestringobrigatório
    Um nome que cumpre namePattern.
  • bodyMaxLengthintegerobrigatório
    Caracteres do corpo.
  • headerMaxLengthintegerobrigatório
    Caracteres do cabeçalho de texto.
  • footerMaxLengthintegerobrigatório
    Caracteres do rodapé.
  • buttonLimitsobjectobrigatório
    Os limites de botões. Resposta rápida junto de outros tipos precisa formar dois grupos: as respostas rápidas de um lado, os outros do outro.
  • buttonLimits.totalintegerobrigatório
    Botões de todos os tipos, somados.
  • buttonLimits.byTypeobjectobrigatório
    O máximo de cada tipo.
  • buttonLimits.byType.QUICK_REPLYintegerobrigatório
  • buttonLimits.byType.URLintegerobrigatório
  • buttonLimits.byType.PHONE_NUMBERintegerobrigatório
  • buttonLimits.byType.COPY_CODEintegerobrigatório
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Criar um template de autenticação

POST/v1/templates/authentication

Cria um template de autenticação com botão de copiar código, e o submete à Meta para aprovação.

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

Corpo da requisição

application/json · obrigatório

  • wabaIdstringobrigatório
    1 a 64 caracteres · /^[A-Za-z0-9_-]+$/
  • namestringobrigatório
    /^[a-z0-9_]{1,512}$/
  • languagestringopcional
    O código de idioma do template, na grafia da Meta: sublinhado e não hífen. pt_BR, pt_PT, en_US, es_MX, fr. A lista completa está em Supported Languages, na documentação da Meta, e o campo aceita qualquer código que ela publicar, porque um conjunto fechado aqui impediria você de usar o próximo. Ausente vale pt_BR. Atenção ao que o idioma custa: cada idioma é um template separado para a Meta, e o teto é de 250 templates por conta de WhatsApp Business./^[a-z]{2,3}(_[A-Z]{2})?$/
  • addSecurityRecommendationbooleanopcional
    Se o template deve incluir o aviso de segurança da Meta, que pede para não compartilhar o código. O texto é da Meta, é gerado no idioma do template e não é customizável. Ausente vale falso.
  • codeExpirationMinutesintegerobrigatório
    Em quantos minutos o código expira. Vai para o rodapé do template, num texto da Meta que não é customizável. O teto aceito aqui é uma guarda desta plataforma contra valor absurdo, e não uma afirmação sobre a faixa que a Meta aceita: essa faixa não está publicada na documentação dela.mínimo 1 · máximo 1440
  • buttonTextstringopcional
    O rótulo do botão de copiar código. Omitir é o recomendado: sem ele a Meta usa o rótulo padrão do idioma do template, que já está traduzido. Máximo de 25 caracteres.1 a 25 caracteres
  • messageSendTtlSecondsintegeropcional
    Tempo de vida, em segundos, das mensagens enviadas com este template. Ausente, o campo não é enviado à Meta e vale o padrão dela. Um código de verificação que chega tarde demais já não serve, e é para isso que ele existe.mínimo 1

Respostas

201Criado.
  • idstring (uuid)obrigatório
  • metaTemplateIdstringobrigatório
  • wabaIdstringobrigatório
    O id da conta de negócio na Meta (WABA) a que o template pertence, o mesmo wabaId que GET /v1/templates devolve e que POST /v1/templates recebe.
  • namestringobrigatório
  • languagestringobrigatório
  • categorystringobrigatório
  • statusstringobrigatório
  • createdAtstringobrigatório
  • updatedAtstringobrigatório
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
Campo recusado, com o motivoJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Teste grátis terminadoJSON
{
  "error": "trial_expired",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."
}
Conta bloqueada pela HelsenJSON
{
  "error": "account_blocked",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
Não existe, ou não é seuJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
415O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.
Tipo de conteúdo não lidoJSON
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
Gestão da conta ocupadaJSON
{
  "error": "management_busy",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "As operações de gestão desta conexão atingiram o limite momentâneo. Tente novamente em instantes."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Copiar um template para outros clientes

POST/v1/templates/{id}/copy

Cria uma cópia do template em até 50 destinos, cada um uma conta de negócio (wabaId) ou um cliente seu (externalId). Responde 200 com um resultado por destino, e um destino que falha não derruba os outros. A cópia passa pelo mesmo caminho e pelas mesmas regras de POST /v1/templates.

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

Parâmetros de caminho

  • idstring (uuid)obrigatório

Corpo da requisição

application/json · obrigatório

  • targetsarray<object>obrigatório
    Os destinos, de 1 a 50. Cada um é { wabaId } ou { externalId }.1 a 50 itens
  • targets[].wabaIdstringopcional
    A conta de negócio de destino, pelo id dela na Meta (wabaId).1 a 64 caracteres · /^[A-Za-z0-9_-]+$/
  • targets[].externalIdstringopcional
    O rótulo do cliente de destino (externalId): a cópia vai para cada conta de WhatsApp Business dos números dele.1 a 128 caracteres
  • headerMediaHandlestringopcional
    O handle do arquivo de exemplo do cabeçalho de mídia, para template de origem que tem um. A Luna guarda só o formato do cabeçalho, não o arquivo.1 a 1024 caracteres
  • authenticationobjectopcional
    Os parâmetros do template de autenticação, obrigatórios quando o template de origem é de autenticação: a Luna não os guarda.
  • authentication.addSecurityRecommendationbooleanopcional
    Se o template deve incluir o aviso de segurança da Meta, que pede para não compartilhar o código. O texto é da Meta, é gerado no idioma do template e não é customizável. Ausente vale falso.
  • authentication.codeExpirationMinutesintegerobrigatório
    Em quantos minutos o código expira. Vai para o rodapé do template, num texto da Meta que não é customizável. O teto aceito aqui é uma guarda desta plataforma contra valor absurdo, e não uma afirmação sobre a faixa que a Meta aceita: essa faixa não está publicada na documentação dela.mínimo 1 · máximo 1440
  • authentication.buttonTextstringopcional
    O rótulo do botão de copiar código. Omitir é o recomendado: sem ele a Meta usa o rótulo padrão do idioma do template, que já está traduzido. Máximo de 25 caracteres.1 a 25 caracteres
  • authentication.messageSendTtlSecondsintegeropcional
    Tempo de vida, em segundos, das mensagens enviadas com este template. Ausente, o campo não é enviado à Meta e vale o padrão dela. Um código de verificação que chega tarde demais já não serve, e é para isso que ele existe.mínimo 1

Respostas

200Sucesso.
  • resultsarray<object>obrigatório
    Um resultado por destino (por conta, quando um externalId tem mais de uma).
  • results[].targetobjectobrigatório
    O destino pedido, como veio.
  • results[].target.wabaIdstring | nullobrigatório
  • results[].target.externalIdstring | nullobrigatório
  • results[].wabaIdstring | nullobrigatório
    A conta de negócio onde a cópia foi tentada. Nulo quando o externalId não resolveu para nenhuma conta.
  • results[].statusintegerobrigatório
    201 quando a cópia foi criada; senão o status do erro daquele destino.
  • results[].templateobject | nullobrigatório
    O template criado nesta conta. Nulo quando houve erro.
  • results[].template.idstring (uuid)obrigatório
  • results[].template.metaTemplateIdstringobrigatório
  • results[].template.wabaIdstringobrigatório
    O id da conta de negócio na Meta (WABA) a que o template pertence, o mesmo wabaId que GET /v1/templates devolve e que POST /v1/templates recebe.
  • results[].template.namestringobrigatório
  • results[].template.languagestringobrigatório
  • results[].template.categorystringobrigatório
  • results[].template.statusstringobrigatório
  • results[].template.createdAtstringobrigatório
  • results[].template.updatedAtstringobrigatório
  • results[].errorobject | nullobrigatório
    O erro deste destino, no mesmo formato de erro da API. Nulo quando a cópia foi criada.
  • results[].error.errorstringobrigatório
  • results[].error.messagestringobrigatório
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
Campo recusado, com o motivoJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Teste grátis terminadoJSON
{
  "error": "trial_expired",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."
}
Conta bloqueada pela HelsenJSON
{
  "error": "account_blocked",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
Não existe, ou não é seuJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
409O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.
A Luna não conhece o conteúdo do templateJSON
{
  "error": "template_content_unknown",
  "docsUrl": "https://lunahia.com.br/docs/templates",
  "message": "A Luna não conhece o conteúdo deste template: ele foi criado direto no painel da Meta, ou antes de a Luna guardar o conteúdo. Sem o conteúdo não há o que copiar. Crie o template de novo por POST /v1/templates e copie o novo."
}
415O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.
Tipo de conteúdo não lidoJSON
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Subir o arquivo de exemplo de um cabeçalho de mídia

POST/v1/template-assets

Recebe um arquivo em multipart/form-data no campo file e devolve o handle que a criação de template aceita em headerMedia.handle.

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

Corpo da requisição

multipart/form-data · obrigatório

  • filestring (binary)obrigatório
    O arquivo a enviar, no campo file.

Respostas

200Sucesso.
  • handlestringobrigatório
    O identificador do arquivo de exemplo. Use-o em headerMedia.handle ao criar o template.
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
Campo recusado, com o motivoJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Teste grátis terminadoJSON
{
  "error": "trial_expired",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."
}
Conta bloqueada pela HelsenJSON
{
  "error": "account_blocked",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
413O arquivo passa do teto de tamanho, que é o mesmo para todos os clientes.
Arquivo acima do tetoJSON
{
  "error": "file_too_large",
  "docsUrl": "https://lunahia.com.br/docs/enviar-mensagens",
  "message": "O arquivo passa do tamanho que a plataforma aceita. O limite é o mesmo para todos os clientes: ele existe por capacidade de infraestrutura."
}
415O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.
Tipo de conteúdo não lidoJSON
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}