LunaDocs

Loading search...

PortuguêsSign in to the console
On this page

Templates

Use with AI

Messages pre-approved by Meta, required to start a conversation outside the 24 hour window.

Approved is not cleared for volume: Meta applies a pace of its own over the first sends of a new template, and publishes no deadline and no mechanics. Ramp up your first send instead of scheduling it for a date, and watch the state of the template.

Above three buttons, only two appear in the delivered message. Meta accepts the template with more and delivers two, so the arrangement has to be decided before the flow is designed.

List templates

GET/v1/templates

This customer's templates, newest first.

Authentication
API key
Required scope
templates:read

Query parameters

  • statusstringoptional
    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 to 64 characters
  • wabaIdstringoptional
    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 to 64 characters
  • phoneNumberIdstringoptional
    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 to 64 characters · /^[A-Za-z0-9_-]+$/

Responses

200Success.
  • dataarray<object>required
  • data[].idstring (uuid)required
  • data[].metaTemplateIdstringrequired
  • data[].wabaIdstringrequired
  • data[].namestringrequired
  • data[].languagestringrequired
  • data[].categorystringrequired
  • data[].statusstringrequired
  • data[].createdAtstringrequired
  • data[].updatedAtstringrequired
  • data[].bodyTextstring | nullrequired
    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 | nullrequired
    O cabeçalho de texto. Nulo quando não há.
  • data[].headerMediaobject | nullrequired
    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.formatstringrequired
    IMAGE, VIDEO ou DOCUMENT.
  • data[].footerstring | nullrequired
    O rodapé. Nulo quando não há.
  • data[].buttonsarray<object>required
    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[].typestringoptional
    Values: QUICK_REPLY
  • data[].buttons[].textstringoptional
    1 to 25 characters
  • data[].buttons[].urlstringoptional
    1 to 2000 characters
  • data[].buttons[].examplearray<string>optional
    up to 1 items
  • data[].buttons[].phone_numberstringoptional
    1 to 20 characters
  • data[].variablesarray<object>required
    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[].namestringrequired
    O nome da variável, o que está entre {{ e }} no corpo.
  • data[].variables[].examplestringrequired
    O exemplo que foi mandado para a Meta junto com a variável.
  • data[].rejectedReasonstring | nullrequired
    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 | nullrequired
    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 | nullrequired
    A categoria que o template tinha antes de a Meta mudá-la, quando ela mudou. Nulo quando a categoria nunca mudou.
  • data[].allowedActionsarray<string>required
    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.
400The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.
Field refused, with the reasonJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
  • WWW-Authenticate Always Bearer.
Key refusedJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
Insufficient scopeJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Test key on a route outside test modeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
429Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.
  • Retry-After Seconds to wait before repeating.
Request limitJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
UnavailableJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Create a template

POST/v1/templates

Creates the template in the customer's account and submits it to Meta for approval.

Authentication
API key
Required scope
templates:write

Request body

application/json · required

  • wabaIdstringrequired
    1 to 64 characters · /^[A-Za-z0-9_-]+$/
  • namestringrequired
    /^[a-z0-9_]{1,512}$/
  • bodyTextstringrequired
    1 to 1024 characters
  • examplesobjectoptional
    Um valor de amostra por variável do corpo. Obrigatório quando o corpo tem `{{variavel}}`, porque a Meta recusa parâmetro sem exemplo.
  • headerstringoptional
    Cabeçalho de texto, exibido acima do corpo. Para cabeçalho de imagem, vídeo ou documento, use headerMedia.1 to 60 characters
  • headerMediaobjectoptional
    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.formatstringrequired
    IMAGE, VIDEO ou DOCUMENT. Para documento a Meta aceita apenas PDF.Values: IMAGE VIDEO DOCUMENT
  • headerMedia.handlestringrequired
    O handle devolvido por POST /v1/template-assets.1 to 2048 characters
  • footerstringoptional
    Rodapé, exibido abaixo do corpo. Não aceita variável.1 to 60 characters
  • buttonsarray<object>optional
    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[].typestringoptional
    Values: QUICK_REPLY
  • buttons[].textstringoptional
    1 to 25 characters
  • buttons[].urlstringoptional
    1 to 2000 characters
  • buttons[].examplearray<string>optional
    up to 1 items
  • buttons[].phone_numberstringoptional
    1 to 20 characters
  • categorystringoptional
    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.Values: MARKETING UTILITY
  • languagestringoptional
    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})?$/

Responses

201Created.
  • idstring (uuid)required
  • metaTemplateIdstringrequired
  • wabaIdstringrequired
    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.
  • namestringrequired
  • languagestringrequired
  • categorystringrequired
  • statusstringrequired
  • createdAtstringrequired
  • updatedAtstringrequired
400The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.
Field refused, with the reasonJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
  • WWW-Authenticate Always Bearer.
Key refusedJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
Insufficient scopeJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Free trial endedJSON
{
  "error": "trial_expired",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."
}
Account blocked by HelsenJSON
{
  "error": "account_blocked",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."
}
Test key on a route outside test modeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
Does not exist, or is not yoursJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
415The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.
Content type not readJSON
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
429Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.
  • Retry-After Seconds to wait before repeating.
Request limitJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
Account management busyJSON
{
  "error": "management_busy",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "As operações de gestão desta conexão atingiram o limite momentâneo. Tente novamente em instantes."
}
503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
UnavailableJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Read a template

GET/v1/templates/{id}

The template's current state at Meta, the content you wrote, and what Meta announced about it.

Authentication
API key
Required scope
templates:read

Path parameters

  • idstring (uuid)required

Responses

200Success.
  • idstring (uuid)required
  • metaTemplateIdstringrequired
  • wabaIdstringrequired
    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.
  • namestringrequired
  • languagestringrequired
  • categorystringrequired
  • statusstringrequired
  • createdAtstringrequired
  • updatedAtstringrequired
  • bodyTextstring | nullrequired
    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 | nullrequired
    O cabeçalho de texto. Nulo quando não há.
  • headerMediaobject | nullrequired
    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.formatstringrequired
    IMAGE, VIDEO ou DOCUMENT.
  • footerstring | nullrequired
    O rodapé. Nulo quando não há.
  • buttonsarray<object>required
    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[].typestringoptional
    Values: QUICK_REPLY
  • buttons[].textstringoptional
    1 to 25 characters
  • buttons[].urlstringoptional
    1 to 2000 characters
  • buttons[].examplearray<string>optional
    up to 1 items
  • buttons[].phone_numberstringoptional
    1 to 20 characters
  • variablesarray<object>required
    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[].namestringrequired
    O nome da variável, o que está entre {{ e }} no corpo.
  • variables[].examplestringrequired
    O exemplo que foi mandado para a Meta junto com a variável.
  • rejectedReasonstring | nullrequired
    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 | nullrequired
    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 | nullrequired
    A categoria que o template tinha antes de a Meta mudá-la, quando ela mudou. Nulo quando a categoria nunca mudou.
  • allowedActionsarray<string>required
    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.
400The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.
Field refused, with the reasonJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
  • WWW-Authenticate Always Bearer.
Key refusedJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
Insufficient scopeJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Test key on a route outside test modeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
Does not exist, or is not yoursJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
429Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.
  • Retry-After Seconds to wait before repeating.
Request limitJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
Account management busyJSON
{
  "error": "management_busy",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "As operações de gestão desta conexão atingiram o limite momentâneo. Tente novamente em instantes."
}
503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
UnavailableJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Edit a template

PATCH/v1/templates/{id}

Changes the components of an existing template.

Authentication
API key
Required scope
templates:write

Path parameters

  • idstring (uuid)required

Request body

application/json · required

  • bodyTextstringoptional
    1 to 1024 characters
  • examplesobjectoptional
  • headerstringoptional
    Cabeçalho de texto, exibido acima do corpo. Para cabeçalho de imagem, vídeo ou documento, use headerMedia.1 to 60 characters
  • footerstringoptional
    Rodapé, exibido abaixo do corpo. Não aceita variável.1 to 60 characters
  • buttonsarray<object>optional
    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[].typestringoptional
    Values: QUICK_REPLY
  • buttons[].textstringoptional
    1 to 25 characters
  • buttons[].urlstringoptional
    1 to 2000 characters
  • buttons[].examplearray<string>optional
    up to 1 items
  • buttons[].phone_numberstringoptional
    1 to 20 characters

Responses

200Success.
  • idstring (uuid)required
  • metaTemplateIdstringrequired
  • wabaIdstringrequired
    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.
  • namestringrequired
  • languagestringrequired
  • categorystringrequired
  • statusstringrequired
  • createdAtstringrequired
  • updatedAtstringrequired
400The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.
Field refused, with the reasonJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
  • WWW-Authenticate Always Bearer.
Key refusedJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
Insufficient scopeJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Free trial endedJSON
{
  "error": "trial_expired",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."
}
Account blocked by HelsenJSON
{
  "error": "account_blocked",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."
}
Test key on a route outside test modeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
Does not exist, or is not yoursJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
415The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.
Content type not readJSON
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
429Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.
  • Retry-After Seconds to wait before repeating.
Request limitJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
Account management busyJSON
{
  "error": "management_busy",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "As operações de gestão desta conexão atingiram o limite momentâneo. Tente novamente em instantes."
}
503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
UnavailableJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Delete a template

DELETE/v1/templates/{id}

Deletes the template at Meta and from your listing.

Authentication
API key
Required scope
templates:write

Path parameters

  • idstring (uuid)required

Responses

204No content: the operation was done and the response has no body.
400The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.
Field refused, with the reasonJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
  • WWW-Authenticate Always Bearer.
Key refusedJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
Insufficient scopeJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Free trial endedJSON
{
  "error": "trial_expired",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."
}
Account blocked by HelsenJSON
{
  "error": "account_blocked",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."
}
Test key on a route outside test modeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
Does not exist, or is not yoursJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
429Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.
  • Retry-After Seconds to wait before repeating.
Request limitJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
Account management busyJSON
{
  "error": "management_busy",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "As operações de gestão desta conexão atingiram o limite momentâneo. Tente novamente em instantes."
}
503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
UnavailableJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Read the template rules

GET/v1/templates/rules

The categories, the suggested languages, the name format, the maximum lengths of body, header and footer, and the button limits. It is what POST /v1/templates enforces, served so you can show the same limit without copying the number.

Authentication
API key
Required scope
templates:read

Responses

200Success.
  • categoriesarray<object>required
    As categorias que a criação aceita. A Meta pode reclassificar o template depois.
  • categories[].valuestringrequired
    O que vai em category ao criar o template.
  • categories[].labelstringrequired
    O nome da categoria, em português.
  • categories[].summarystringrequired
    Quando usar, em uma ou duas frases.
  • languagesarray<object>required
    Idiomas sugeridos. Não é lista fechada: vale qualquer código que a Meta publique, no formato de language em POST /v1/templates.
  • languages[].codestringrequired
  • languages[].labelstringrequired
  • namePatternstringrequired
    A expressão regular que o name precisa cumprir, em sintaxe de JavaScript e sem as barras.
  • nameExamplestringrequired
    Um nome que cumpre namePattern.
  • bodyMaxLengthintegerrequired
    Caracteres do corpo.
  • headerMaxLengthintegerrequired
    Caracteres do cabeçalho de texto.
  • footerMaxLengthintegerrequired
    Caracteres do rodapé.
  • buttonLimitsobjectrequired
    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.totalintegerrequired
    Botões de todos os tipos, somados.
  • buttonLimits.byTypeobjectrequired
    O máximo de cada tipo.
  • buttonLimits.byType.QUICK_REPLYintegerrequired
  • buttonLimits.byType.URLintegerrequired
  • buttonLimits.byType.PHONE_NUMBERintegerrequired
  • buttonLimits.byType.COPY_CODEintegerrequired
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
  • WWW-Authenticate Always Bearer.
Key refusedJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
Insufficient scopeJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Test key on a route outside test modeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
429Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.
  • Retry-After Seconds to wait before repeating.
Request limitJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
UnavailableJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Create an authentication template

POST/v1/templates/authentication

Creates an authentication template with a copy code button, and submits it to Meta for approval.

Authentication
API key
Required scope
templates:write

Request body

application/json · required

  • wabaIdstringrequired
    1 to 64 characters · /^[A-Za-z0-9_-]+$/
  • namestringrequired
    /^[a-z0-9_]{1,512}$/
  • languagestringoptional
    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})?$/
  • addSecurityRecommendationbooleanoptional
    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.
  • codeExpirationMinutesintegerrequired
    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.minimum 1 · maximum 1440
  • buttonTextstringoptional
    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 to 25 characters
  • messageSendTtlSecondsintegeroptional
    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.minimum 1

Responses

201Created.
  • idstring (uuid)required
  • metaTemplateIdstringrequired
  • wabaIdstringrequired
    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.
  • namestringrequired
  • languagestringrequired
  • categorystringrequired
  • statusstringrequired
  • createdAtstringrequired
  • updatedAtstringrequired
400The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.
Field refused, with the reasonJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
  • WWW-Authenticate Always Bearer.
Key refusedJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
Insufficient scopeJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Free trial endedJSON
{
  "error": "trial_expired",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."
}
Account blocked by HelsenJSON
{
  "error": "account_blocked",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."
}
Test key on a route outside test modeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
Does not exist, or is not yoursJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
415The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.
Content type not readJSON
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
429Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.
  • Retry-After Seconds to wait before repeating.
Request limitJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
Account management busyJSON
{
  "error": "management_busy",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "As operações de gestão desta conexão atingiram o limite momentâneo. Tente novamente em instantes."
}
503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
UnavailableJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Copy a template to other customers

POST/v1/templates/{id}/copy

Creates a copy of the template in up to 50 destinations, each a business account (wabaId) or a customer of yours (externalId). Answers 200 with one result per destination, and a destination that fails does not bring the others down. The copy goes through the same path and the same rules as POST /v1/templates.

Authentication
API key
Required scope
templates:write

Path parameters

  • idstring (uuid)required

Request body

application/json · required

  • targetsarray<object>required
    Os destinos, de 1 a 50. Cada um é { wabaId } ou { externalId }.1 to 50 items
  • targets[].wabaIdstringoptional
    A conta de negócio de destino, pelo id dela na Meta (wabaId).1 to 64 characters · /^[A-Za-z0-9_-]+$/
  • targets[].externalIdstringoptional
    O rótulo do cliente de destino (externalId): a cópia vai para cada conta de WhatsApp Business dos números dele.1 to 128 characters
  • headerMediaHandlestringoptional
    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 to 1024 characters
  • authenticationobjectoptional
    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.addSecurityRecommendationbooleanoptional
    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.codeExpirationMinutesintegerrequired
    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.minimum 1 · maximum 1440
  • authentication.buttonTextstringoptional
    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 to 25 characters
  • authentication.messageSendTtlSecondsintegeroptional
    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.minimum 1

Responses

200Success.
  • resultsarray<object>required
    Um resultado por destino (por conta, quando um externalId tem mais de uma).
  • results[].targetobjectrequired
    O destino pedido, como veio.
  • results[].target.wabaIdstring | nullrequired
  • results[].target.externalIdstring | nullrequired
  • results[].wabaIdstring | nullrequired
    A conta de negócio onde a cópia foi tentada. Nulo quando o externalId não resolveu para nenhuma conta.
  • results[].statusintegerrequired
    201 quando a cópia foi criada; senão o status do erro daquele destino.
  • results[].templateobject | nullrequired
    O template criado nesta conta. Nulo quando houve erro.
  • results[].template.idstring (uuid)required
  • results[].template.metaTemplateIdstringrequired
  • results[].template.wabaIdstringrequired
    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.namestringrequired
  • results[].template.languagestringrequired
  • results[].template.categorystringrequired
  • results[].template.statusstringrequired
  • results[].template.createdAtstringrequired
  • results[].template.updatedAtstringrequired
  • results[].errorobject | nullrequired
    O erro deste destino, no mesmo formato de erro da API. Nulo quando a cópia foi criada.
  • results[].error.errorstringrequired
  • results[].error.messagestringrequired
400The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.
Field refused, with the reasonJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
  • WWW-Authenticate Always Bearer.
Key refusedJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
Insufficient scopeJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Free trial endedJSON
{
  "error": "trial_expired",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."
}
Account blocked by HelsenJSON
{
  "error": "account_blocked",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."
}
Test key on a route outside test modeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
Does not exist, or is not yoursJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
409The request is well formed, but the resource state does not allow it. The error field says which case it is.
Luna does not know the template contentJSON
{
  "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."
}
415The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.
Content type not readJSON
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
429Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.
  • Retry-After Seconds to wait before repeating.
Request limitJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
UnavailableJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Upload the example file for a media header

POST/v1/template-assets

Takes a file in multipart/form-data under the field file and returns the handle that template creation accepts in headerMedia.handle.

Authentication
API key
Required scope
templates:write

Request body

multipart/form-data · required

  • filestring (binary)required
    The file to upload, in the file field.

Responses

200Success.
  • handlestringrequired
    O identificador do arquivo de exemplo. Use-o em headerMedia.handle ao criar o template.
400The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.
Field refused, with the reasonJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
  • WWW-Authenticate Always Bearer.
Key refusedJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives test_key_not_allowed.
Insufficient scopeJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Free trial endedJSON
{
  "error": "trial_expired",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."
}
Account blocked by HelsenJSON
{
  "error": "account_blocked",
  "docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
  "message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."
}
Test key on a route outside test modeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
413The file is over the size ceiling, which is the same for every customer.
File over the ceilingJSON
{
  "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."
}
415The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.
Content type not readJSON
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
429Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.
  • Retry-After Seconds to wait before repeating.
Request limitJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
UnavailableJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}