Templates
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.
Query parameters
statusstringoptionalDevolve 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 characterswabaIdstringoptionalDevolve 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 charactersphoneNumberIdstringoptionalDevolve 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>requireddata[].idstring (uuid)requireddata[].metaTemplateIdstringrequireddata[].wabaIdstringrequireddata[].namestringrequireddata[].languagestringrequireddata[].categorystringrequireddata[].statusstringrequireddata[].createdAtstringrequireddata[].updatedAtstringrequireddata[].bodyTextstring | nullrequiredO 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 | nullrequiredO cabeçalho de texto. Nulo quando não há.data[].headerMediaobject | nullrequiredO 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.formatstringrequiredIMAGE, VIDEO ou DOCUMENT.data[].footerstring | nullrequiredO rodapé. Nulo quando não há.data[].buttonsarray<object>requiredOs 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[].typestringoptionalValues:QUICK_REPLYdata[].buttons[].textstringoptional1 to 25 charactersdata[].buttons[].urlstringoptional1 to 2000 charactersdata[].buttons[].examplearray<string>optionalup to 1 itemsdata[].buttons[].phone_numberstringoptional1 to 20 charactersdata[].variablesarray<object>requiredAs 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[].namestringrequiredO nome da variável, o que está entre {{ e }} no corpo.data[].variables[].examplestringrequiredO exemplo que foi mandado para a Meta junto com a variável.data[].rejectedReasonstring | nullrequiredPor 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 | nullrequiredA 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 | nullrequiredA categoria que o template tinha antes de a Meta mudá-la, quando ela mudou. Nulo quando a categoria nunca mudou.data[].allowedActionsarray<string>requiredO 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.
{
"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-AuthenticateAlways Bearer.
{
"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.
{
"error": "forbidden",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
"requiredScope": "numbers:read"
}{
"error": "test_key_not_allowed",
"docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
"message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}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-AfterSeconds to wait before repeating.
{
"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.
{
"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.
Request body
wabaIdstringrequired1 to 64 characters · /^[A-Za-z0-9_-]+$/namestringrequired/^[a-z0-9_]{1,512}$/bodyTextstringrequired1 to 1024 charactersexamplesobjectoptionalUm valor de amostra por variável do corpo. Obrigatório quando o corpo tem `{{variavel}}`, porque a Meta recusa parâmetro sem exemplo.headerstringoptionalCabeçalho de texto, exibido acima do corpo. Para cabeçalho de imagem, vídeo ou documento, use headerMedia.1 to 60 charactersheaderMediaobjectoptionalCabeç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.formatstringrequiredIMAGE, VIDEO ou DOCUMENT. Para documento a Meta aceita apenas PDF.Values:IMAGEVIDEODOCUMENTheaderMedia.handlestringrequiredO handle devolvido por POST /v1/template-assets.1 to 2048 charactersfooterstringoptionalRodapé, exibido abaixo do corpo. Não aceita variável.1 to 60 charactersbuttonsarray<object>optionalAté 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[].typestringoptionalValues:QUICK_REPLYbuttons[].textstringoptional1 to 25 charactersbuttons[].urlstringoptional1 to 2000 charactersbuttons[].examplearray<string>optionalup to 1 itemsbuttons[].phone_numberstringoptional1 to 20 characterscategorystringoptionalA 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:MARKETINGUTILITYlanguagestringoptionalO 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)requiredmetaTemplateIdstringrequiredwabaIdstringrequiredO 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.namestringrequiredlanguagestringrequiredcategorystringrequiredstatusstringrequiredcreatedAtstringrequiredupdatedAtstringrequired
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.
{
"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-AuthenticateAlways Bearer.
{
"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.
{
"error": "forbidden",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
"requiredScope": "numbers:read"
}{
"error": "trial_expired",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"message": "O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."
}{
"error": "account_blocked",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."
}{
"error": "test_key_not_allowed",
"docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
"message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
{
"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.
{
"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-AfterSeconds to wait before repeating.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}{
"error": "management_busy",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "As operações de gestão desta conexão atingiram o limite momentâneo. Tente novamente em instantes."
}503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
{
"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.
Path parameters
idstring (uuid)required
Responses
200Success.
idstring (uuid)requiredmetaTemplateIdstringrequiredwabaIdstringrequiredO 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.namestringrequiredlanguagestringrequiredcategorystringrequiredstatusstringrequiredcreatedAtstringrequiredupdatedAtstringrequiredbodyTextstring | nullrequiredO 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 | nullrequiredO cabeçalho de texto. Nulo quando não há.headerMediaobject | nullrequiredO 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.formatstringrequiredIMAGE, VIDEO ou DOCUMENT.footerstring | nullrequiredO rodapé. Nulo quando não há.buttonsarray<object>requiredOs botões, na mesma forma em que POST /v1/templates os recebe. Vazio quando não há, ou quando o conteúdo é desconhecido.buttons[].typestringoptionalValues:QUICK_REPLYbuttons[].textstringoptional1 to 25 charactersbuttons[].urlstringoptional1 to 2000 charactersbuttons[].examplearray<string>optionalup to 1 itemsbuttons[].phone_numberstringoptional1 to 20 charactersvariablesarray<object>requiredAs variáveis do corpo, na ordem em que aparecem, cada uma com o exemplo. A tela não precisa extrair {{nome}} do texto.variables[].namestringrequiredO nome da variável, o que está entre {{ e }} no corpo.variables[].examplestringrequiredO exemplo que foi mandado para a Meta junto com a variável.rejectedReasonstring | nullrequiredPor 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 | nullrequiredA 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 | nullrequiredA categoria que o template tinha antes de a Meta mudá-la, quando ela mudou. Nulo quando a categoria nunca mudou.allowedActionsarray<string>requiredO 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.
{
"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-AuthenticateAlways Bearer.
{
"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.
{
"error": "forbidden",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
"requiredScope": "numbers:read"
}{
"error": "test_key_not_allowed",
"docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
"message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
{
"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-AfterSeconds to wait before repeating.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}{
"error": "management_busy",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "As operações de gestão desta conexão atingiram o limite momentâneo. Tente novamente em instantes."
}503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
{
"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.
Path parameters
idstring (uuid)required
Request body
bodyTextstringoptional1 to 1024 charactersexamplesobjectoptionalheaderstringoptionalCabeçalho de texto, exibido acima do corpo. Para cabeçalho de imagem, vídeo ou documento, use headerMedia.1 to 60 charactersfooterstringoptionalRodapé, exibido abaixo do corpo. Não aceita variável.1 to 60 charactersbuttonsarray<object>optionalAté 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[].typestringoptionalValues:QUICK_REPLYbuttons[].textstringoptional1 to 25 charactersbuttons[].urlstringoptional1 to 2000 charactersbuttons[].examplearray<string>optionalup to 1 itemsbuttons[].phone_numberstringoptional1 to 20 characters
Responses
200Success.
idstring (uuid)requiredmetaTemplateIdstringrequiredwabaIdstringrequiredO 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.namestringrequiredlanguagestringrequiredcategorystringrequiredstatusstringrequiredcreatedAtstringrequiredupdatedAtstringrequired
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.
{
"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-AuthenticateAlways Bearer.
{
"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.
{
"error": "forbidden",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
"requiredScope": "numbers:read"
}{
"error": "trial_expired",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"message": "O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."
}{
"error": "account_blocked",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."
}{
"error": "test_key_not_allowed",
"docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
"message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
{
"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.
{
"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-AfterSeconds to wait before repeating.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}{
"error": "management_busy",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "As operações de gestão desta conexão atingiram o limite momentâneo. Tente novamente em instantes."
}503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
{
"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.
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.
{
"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-AuthenticateAlways Bearer.
{
"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.
{
"error": "forbidden",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
"requiredScope": "numbers:read"
}{
"error": "trial_expired",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"message": "O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."
}{
"error": "account_blocked",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."
}{
"error": "test_key_not_allowed",
"docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
"message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
{
"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-AfterSeconds to wait before repeating.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}{
"error": "management_busy",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "As operações de gestão desta conexão atingiram o limite momentâneo. Tente novamente em instantes."
}503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
{
"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.
Responses
200Success.
categoriesarray<object>requiredAs categorias que a criação aceita. A Meta pode reclassificar o template depois.categories[].valuestringrequiredO que vai em category ao criar o template.categories[].labelstringrequiredO nome da categoria, em português.categories[].summarystringrequiredQuando usar, em uma ou duas frases.languagesarray<object>requiredIdiomas sugeridos. Não é lista fechada: vale qualquer código que a Meta publique, no formato de language em POST /v1/templates.languages[].codestringrequiredlanguages[].labelstringrequirednamePatternstringrequiredA expressão regular que o name precisa cumprir, em sintaxe de JavaScript e sem as barras.nameExamplestringrequiredUm nome que cumpre namePattern.bodyMaxLengthintegerrequiredCaracteres do corpo.headerMaxLengthintegerrequiredCaracteres do cabeçalho de texto.footerMaxLengthintegerrequiredCaracteres do rodapé.buttonLimitsobjectrequiredOs 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.totalintegerrequiredBotões de todos os tipos, somados.buttonLimits.byTypeobjectrequiredO máximo de cada tipo.buttonLimits.byType.QUICK_REPLYintegerrequiredbuttonLimits.byType.URLintegerrequiredbuttonLimits.byType.PHONE_NUMBERintegerrequiredbuttonLimits.byType.COPY_CODEintegerrequired
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
WWW-AuthenticateAlways Bearer.
{
"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.
{
"error": "forbidden",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
"requiredScope": "numbers:read"
}{
"error": "test_key_not_allowed",
"docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
"message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}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-AfterSeconds to wait before repeating.
{
"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.
{
"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.
Request body
wabaIdstringrequired1 to 64 characters · /^[A-Za-z0-9_-]+$/namestringrequired/^[a-z0-9_]{1,512}$/languagestringoptionalO 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})?$/addSecurityRecommendationbooleanoptionalSe 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.codeExpirationMinutesintegerrequiredEm 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 1440buttonTextstringoptionalO 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 charactersmessageSendTtlSecondsintegeroptionalTempo 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)requiredmetaTemplateIdstringrequiredwabaIdstringrequiredO 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.namestringrequiredlanguagestringrequiredcategorystringrequiredstatusstringrequiredcreatedAtstringrequiredupdatedAtstringrequired
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.
{
"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-AuthenticateAlways Bearer.
{
"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.
{
"error": "forbidden",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
"requiredScope": "numbers:read"
}{
"error": "trial_expired",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"message": "O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."
}{
"error": "account_blocked",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."
}{
"error": "test_key_not_allowed",
"docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
"message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
{
"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.
{
"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-AfterSeconds to wait before repeating.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}{
"error": "management_busy",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "As operações de gestão desta conexão atingiram o limite momentâneo. Tente novamente em instantes."
}503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
{
"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.
Path parameters
idstring (uuid)required
Request body
targetsarray<object>requiredOs destinos, de 1 a 50. Cada um é { wabaId } ou { externalId }.1 to 50 itemstargets[].wabaIdstringoptionalA conta de negócio de destino, pelo id dela na Meta (wabaId).1 to 64 characters · /^[A-Za-z0-9_-]+$/targets[].externalIdstringoptionalO rótulo do cliente de destino (externalId): a cópia vai para cada conta de WhatsApp Business dos números dele.1 to 128 charactersheaderMediaHandlestringoptionalO 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 charactersauthenticationobjectoptionalOs parâmetros do template de autenticação, obrigatórios quando o template de origem é de autenticação: a Luna não os guarda.authentication.addSecurityRecommendationbooleanoptionalSe 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.codeExpirationMinutesintegerrequiredEm 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 1440authentication.buttonTextstringoptionalO 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 charactersauthentication.messageSendTtlSecondsintegeroptionalTempo 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>requiredUm resultado por destino (por conta, quando um externalId tem mais de uma).results[].targetobjectrequiredO destino pedido, como veio.results[].target.wabaIdstring | nullrequiredresults[].target.externalIdstring | nullrequiredresults[].wabaIdstring | nullrequiredA conta de negócio onde a cópia foi tentada. Nulo quando o externalId não resolveu para nenhuma conta.results[].statusintegerrequired201 quando a cópia foi criada; senão o status do erro daquele destino.results[].templateobject | nullrequiredO template criado nesta conta. Nulo quando houve erro.results[].template.idstring (uuid)requiredresults[].template.metaTemplateIdstringrequiredresults[].template.wabaIdstringrequiredO 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.namestringrequiredresults[].template.languagestringrequiredresults[].template.categorystringrequiredresults[].template.statusstringrequiredresults[].template.createdAtstringrequiredresults[].template.updatedAtstringrequiredresults[].errorobject | nullrequiredO erro deste destino, no mesmo formato de erro da API. Nulo quando a cópia foi criada.results[].error.errorstringrequiredresults[].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.
{
"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-AuthenticateAlways Bearer.
{
"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.
{
"error": "forbidden",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
"requiredScope": "numbers:read"
}{
"error": "trial_expired",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"message": "O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."
}{
"error": "account_blocked",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."
}{
"error": "test_key_not_allowed",
"docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
"message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
{
"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.
{
"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.
{
"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-AfterSeconds to wait before repeating.
{
"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.
{
"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.
Request body
filestring (binary)requiredThe file to upload, in the file field.
Responses
200Success.
handlestringrequiredO 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.
{
"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-AuthenticateAlways Bearer.
{
"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.
{
"error": "forbidden",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
"requiredScope": "numbers:read"
}{
"error": "trial_expired",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"message": "O teste grátis desta conta terminou. O envio de mensagens e as demais escritas estão pausados até a conta ser contratada. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para continuar, escreva para contato@lunahia.com.br."
}{
"error": "account_blocked",
"docsUrl": "https://lunahia.com.br/docs/plano-e-numeros",
"message": "Esta conta foi bloqueada pela Helsen. O envio de mensagens e as demais escritas estão pausados. Você continua lendo os seus dados, o número segue conectado na Meta e o que chega continua sendo recebido e entregue ao seu webhook. Para saber o motivo e resolver, escreva para contato@lunahia.com.br."
}{
"error": "test_key_not_allowed",
"docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
"message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}413The file is over the size ceiling, which is the same for every customer.
{
"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.
{
"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-AfterSeconds to wait before repeating.
{
"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.
{
"error": "unavailable",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}