# Templates

Fonte: https://lunahia.com.br/en/docs/reference/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.

Authentication: API key. Required scope: `templates:read`

Topic guide: https://lunahia.com.br/en/docs/templates#rota-get-v1-templates

#### Query parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `string` | no | 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. |
| `wabaId` | `string` | no | 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. |
| `phoneNumberId` | `string` | no | 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. |

#### Code examples

```bash
curl -X GET "https://api.lunahia.com.br/v1/templates" \
  -H "Authorization: Bearer $LUNA_API_KEY"
```

#### Responses

**200**: Success.

```json
{
  "data": [
    {
      "id": "ae60f288-7565-4315-a440-3663e9c231e1",
      "metaTemplateId": "1259544702043801",
      "wabaId": "102290129340398",
      "name": "numero_conectado",
      "language": "pt_BR",
      "category": "UTILITY",
      "status": "APPROVED",
      "createdAt": "2026-08-10T12:24:02.085Z",
      "updatedAt": "2026-08-10T12:31:47.004Z",
      "bodyText": "Olá {{primeiro_nome}}, o seu número foi conectado.",
      "header": null,
      "headerMedia": null,
      "footer": null,
      "buttons": [],
      "variables": [
        {
          "name": "primeiro_nome",
          "example": "Maria"
        }
      ],
      "rejectedReason": null,
      "qualityScore": "GREEN",
      "previousCategory": null,
      "allowedActions": [
        "edit",
        "delete"
      ]
    }
  ]
}
```

**400**: The 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.

```json
{
  "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."
    }
  ]
}
```

**401**: The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.

```json
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
```

**403**: The 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.

```json
{
  "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"
}
```

**429**: Too 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.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.

```json
{
  "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`

Topic guide: https://lunahia.com.br/en/docs/templates#rota-post-v1-templates

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `wabaId` | `string` | yes | 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `name` | `string` | yes | /^[a-z0-9_]{1,512}$/ |
| `bodyText` | `string` | yes | 1 to 1024 characters |
| `examples` | `object` | no | Um valor de amostra por variável do corpo. Obrigatório quando o corpo tem `{{variavel}}`, porque a Meta recusa parâmetro sem exemplo. |
| `header` | `string` | no | Cabeçalho de texto, exibido acima do corpo. Para cabeçalho de imagem, vídeo ou documento, use headerMedia. · 1 to 60 characters |
| `headerMedia` | `object` | no | 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.format` | `string` | yes | IMAGE, VIDEO ou DOCUMENT. Para documento a Meta aceita apenas PDF. · Values: IMAGE, VIDEO, DOCUMENT |
| `headerMedia.handle` | `string` | yes | O handle devolvido por POST /v1/template-assets. · 1 to 2048 characters |
| `footer` | `string` | no | Rodapé, exibido abaixo do corpo. Não aceita variável. · 1 to 60 characters |
| `buttons` | `array<object>` | no | 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[].type` | `string` | no | Values: QUICK_REPLY |
| `buttons[].text` | `string` | no | 1 to 25 characters |
| `buttons[].url` | `string` | no | 1 to 2000 characters |
| `buttons[].example` | `array<string>` | no | up to 1 items |
| `buttons[].phone_number` | `string` | no | 1 to 20 characters |
| `category` | `string` | no | 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 |
| `language` | `string` | no | 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})?$/ |

#### Code examples

```bash
curl -X POST "https://api.lunahia.com.br/v1/templates" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "wabaId": "YOUR_WABAID",
  "name": "YOUR_NAME",
  "bodyText": "YOUR_BODYTEXT"
}'
```

#### Responses

**201**: Created.

```json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "metaTemplateId": "YOUR_METATEMPLATEID",
  "wabaId": "YOUR_WABAID",
  "name": "YOUR_NAME",
  "language": "YOUR_LANGUAGE",
  "category": "YOUR_CATEGORY",
  "status": "YOUR_STATUS",
  "createdAt": "YOUR_CREATEDAT",
  "updatedAt": "YOUR_UPDATEDAT"
}
```

**400**: The 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.

```json
{
  "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."
    }
  ]
}
```

**401**: The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.

```json
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
```

**403**: The 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.

```json
{
  "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"
}
```

**404**: The resource does not exist, or is not yours. The two answers are identical, byte for byte.

```json
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
```

**415**: The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.

```json
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
```

**429**: Too 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.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.

```json
{
  "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`

Topic guide: https://lunahia.com.br/en/docs/templates#rota-get-v1-templates-id

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes |  |

#### Code examples

```bash
curl -X GET "https://api.lunahia.com.br/v1/templates/YOUR_ID" \
  -H "Authorization: Bearer $LUNA_API_KEY"
```

#### Responses

**200**: Success.

```json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "metaTemplateId": "YOUR_METATEMPLATEID",
  "wabaId": "YOUR_WABAID",
  "name": "YOUR_NAME",
  "language": "YOUR_LANGUAGE",
  "category": "YOUR_CATEGORY",
  "status": "YOUR_STATUS",
  "createdAt": "YOUR_CREATEDAT",
  "updatedAt": "YOUR_UPDATEDAT",
  "bodyText": "YOUR_BODYTEXT",
  "header": "YOUR_HEADER",
  "headerMedia": {
    "format": "YOUR_FORMAT"
  },
  "footer": "YOUR_FOOTER",
  "buttons": [
    {
      "type": "QUICK_REPLY",
      "text": "YOUR_TEXT"
    }
  ],
  "variables": [
    {
      "name": "YOUR_NAME",
      "example": "YOUR_EXAMPLE"
    }
  ],
  "rejectedReason": "YOUR_REJECTEDREASON",
  "qualityScore": "YOUR_QUALITYSCORE",
  "previousCategory": "YOUR_PREVIOUSCATEGORY",
  "allowedActions": [
    "edit"
  ]
}
```

**400**: The 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.

```json
{
  "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."
    }
  ]
}
```

**401**: The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.

```json
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
```

**403**: The 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.

```json
{
  "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"
}
```

**404**: The resource does not exist, or is not yours. The two answers are identical, byte for byte.

```json
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
```

**429**: Too 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.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.

```json
{
  "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`

Topic guide: https://lunahia.com.br/en/docs/templates#rota-patch-v1-templates-id

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes |  |

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `bodyText` | `string` | no | 1 to 1024 characters |
| `examples` | `object` | no |  |
| `header` | `string` | no | Cabeçalho de texto, exibido acima do corpo. Para cabeçalho de imagem, vídeo ou documento, use headerMedia. · 1 to 60 characters |
| `footer` | `string` | no | Rodapé, exibido abaixo do corpo. Não aceita variável. · 1 to 60 characters |
| `buttons` | `array<object>` | no | 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[].type` | `string` | no | Values: QUICK_REPLY |
| `buttons[].text` | `string` | no | 1 to 25 characters |
| `buttons[].url` | `string` | no | 1 to 2000 characters |
| `buttons[].example` | `array<string>` | no | up to 1 items |
| `buttons[].phone_number` | `string` | no | 1 to 20 characters |

#### Code examples

```bash
curl -X PATCH "https://api.lunahia.com.br/v1/templates/YOUR_ID" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "bodyText": "YOUR_BODYTEXT",
  "examples": {},
  "header": "YOUR_HEADER"
}'
```

#### Responses

**200**: Success.

```json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "metaTemplateId": "YOUR_METATEMPLATEID",
  "wabaId": "YOUR_WABAID",
  "name": "YOUR_NAME",
  "language": "YOUR_LANGUAGE",
  "category": "YOUR_CATEGORY",
  "status": "YOUR_STATUS",
  "createdAt": "YOUR_CREATEDAT",
  "updatedAt": "YOUR_UPDATEDAT"
}
```

**400**: The 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.

```json
{
  "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."
    }
  ]
}
```

**401**: The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.

```json
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
```

**403**: The 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.

```json
{
  "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"
}
```

**404**: The resource does not exist, or is not yours. The two answers are identical, byte for byte.

```json
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
```

**415**: The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.

```json
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
```

**429**: Too 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.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.

```json
{
  "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`

Topic guide: https://lunahia.com.br/en/docs/templates#rota-delete-v1-templates-id

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes |  |

#### Code examples

```bash
curl -X DELETE "https://api.lunahia.com.br/v1/templates/YOUR_ID" \
  -H "Authorization: Bearer $LUNA_API_KEY"
```

#### Responses

**204**: No content: the operation was done and the response has no body.

**400**: The 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.

```json
{
  "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."
    }
  ]
}
```

**401**: The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.

```json
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
```

**403**: The 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.

```json
{
  "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"
}
```

**404**: The resource does not exist, or is not yours. The two answers are identical, byte for byte.

```json
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
```

**429**: Too 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.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.

```json
{
  "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`

#### Code examples

```bash
curl -X GET "https://api.lunahia.com.br/v1/templates/rules" \
  -H "Authorization: Bearer $LUNA_API_KEY"
```

#### Responses

**200**: Success.

```json
{
  "categories": [
    {
      "value": "MARKETING",
      "label": "Marketing",
      "summary": "Promove, convida ou tenta reengajar: oferta, novidade, carrinho esquecido. A Meta pode reclassificar um template de utilidade para marketing."
    }
  ],
  "languages": [
    {
      "code": "pt_BR",
      "label": "Português (Brasil)"
    }
  ],
  "namePattern": "^[a-z0-9_]{1,512}$",
  "nameExample": "confirmacao_do_pedido",
  "bodyMaxLength": 1024,
  "headerMaxLength": 60,
  "footerMaxLength": 60,
  "buttonLimits": {
    "total": 10,
    "byType": {
      "QUICK_REPLY": 10,
      "URL": 2,
      "PHONE_NUMBER": 1,
      "COPY_CODE": 1
    }
  }
}
```

**401**: The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.

```json
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
```

**403**: The 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.

```json
{
  "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"
}
```

**429**: Too 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.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.

```json
{
  "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`

Topic guide: https://lunahia.com.br/en/docs/templates#rota-post-v1-templates-authentication

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `wabaId` | `string` | yes | 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `name` | `string` | yes | /^[a-z0-9_]{1,512}$/ |
| `language` | `string` | no | 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})?$/ |
| `addSecurityRecommendation` | `boolean` | no | 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. |
| `codeExpirationMinutes` | `integer` | yes | 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 |
| `buttonText` | `string` | no | 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 |
| `messageSendTtlSeconds` | `integer` | no | 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 |

#### Code examples

```bash
curl -X POST "https://api.lunahia.com.br/v1/templates/authentication" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "wabaId": "YOUR_WABAID",
  "name": "YOUR_NAME",
  "codeExpirationMinutes": 10
}'
```

#### Responses

**201**: Created.

```json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "metaTemplateId": "YOUR_METATEMPLATEID",
  "wabaId": "YOUR_WABAID",
  "name": "YOUR_NAME",
  "language": "YOUR_LANGUAGE",
  "category": "YOUR_CATEGORY",
  "status": "YOUR_STATUS",
  "createdAt": "YOUR_CREATEDAT",
  "updatedAt": "YOUR_UPDATEDAT"
}
```

**400**: The 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.

```json
{
  "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."
    }
  ]
}
```

**401**: The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.

```json
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
```

**403**: The 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.

```json
{
  "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"
}
```

**404**: The resource does not exist, or is not yours. The two answers are identical, byte for byte.

```json
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
```

**415**: The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.

```json
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
```

**429**: Too 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.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.

```json
{
  "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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes |  |

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `targets` | `array<object>` | yes | Os destinos, de 1 a 50. Cada um é { wabaId } ou { externalId }. · 1 to 50 items |
| `targets[].wabaId` | `string` | no | A conta de negócio de destino, pelo id dela na Meta (wabaId). · 1 to 64 characters · /^[A-Za-z0-9_-]+$/ |
| `targets[].externalId` | `string` | no | 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 |
| `headerMediaHandle` | `string` | no | 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 |
| `authentication` | `object` | no | 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.addSecurityRecommendation` | `boolean` | no | 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.codeExpirationMinutes` | `integer` | yes | 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.buttonText` | `string` | no | 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.messageSendTtlSeconds` | `integer` | no | 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 |

#### Code examples

```bash
curl -X POST "https://api.lunahia.com.br/v1/templates/YOUR_ID/copy" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "targets": [
    {
      "wabaId": "YOUR_WABAID",
      "externalId": "YOUR_EXTERNALID"
    }
  ]
}'
```

#### Responses

**200**: Success.

```json
{
  "results": [
    {
      "target": {
        "wabaId": "YOUR_WABAID",
        "externalId": "YOUR_EXTERNALID"
      },
      "wabaId": "YOUR_WABAID",
      "status": 1,
      "template": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "metaTemplateId": "YOUR_METATEMPLATEID",
        "wabaId": "YOUR_WABAID",
        "name": "YOUR_NAME",
        "language": "YOUR_LANGUAGE",
        "category": "YOUR_CATEGORY",
        "status": "YOUR_STATUS",
        "createdAt": "YOUR_CREATEDAT",
        "updatedAt": "YOUR_UPDATEDAT"
      },
      "error": {
        "error": "YOUR_ERROR",
        "message": "YOUR_MESSAGE"
      }
    }
  ]
}
```

**400**: The 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.

```json
{
  "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."
    }
  ]
}
```

**401**: The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.

```json
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
```

**403**: The 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.

```json
{
  "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"
}
```

**404**: The resource does not exist, or is not yours. The two answers are identical, byte for byte.

```json
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
```

**409**: The request is well formed, but the resource state does not allow it. The error field says which case it is.

```json
{
  "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."
}
```

**415**: The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.

```json
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
```

**429**: Too 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.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.

```json
{
  "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`

Topic guide: https://lunahia.com.br/en/docs/templates#rota-post-v1-template-assets

#### Request body

`multipart/form-data`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `file` | `string (binary)` | yes | The file to upload, in the file field. |

#### Code examples

```bash
curl -X POST "https://api.lunahia.com.br/v1/template-assets" \
  -H "Authorization: Bearer $LUNA_API_KEY" \
  -F "file=@./pedido.jpg;type=image/jpeg"
```

#### Responses

**200**: Success.

```json
{
  "handle": "4:cGVkaWRvLnBuZw==:aW1hZ2UvcG5n:ARb0Xk:e:1790451084:1269849425120687:0"
}
```

**400**: The 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.

```json
{
  "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."
    }
  ]
}
```

**401**: The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.

```json
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
```

**403**: The 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.

```json
{
  "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"
}
```

**413**: The file is over the size ceiling, which is the same for every customer.

```json
{
  "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."
}
```

**415**: The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.

```json
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
```

**429**: Too 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.

```json
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
```

**503**: The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.

```json
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}
```
