> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lovi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API de Gerenciamento de Templates

> Documentação oficial para gerenciamento de templates de mensagens do WhatsApp

## Introdução

Os endpoints de gerenciamento de templates permitem recuperar, inspecionar e criar templates de mensagens do WhatsApp. Templates são formatos de mensagem pré-aprovados exigidos pelo WhatsApp para comunicações comerciais.

***

## 📋 Obter Templates Disponíveis

Recupere todos os templates disponíveis para sua empresa e número de telefone.

### Endpoint

```
GET https://cloud.lovi.ai/functions/v1/notify/templates?access_key={YOUR_ACCESS_KEY}&phone_number={PHONE_NUMBER}
```

### Parâmetros de Query

| Parâmetro      | Obrigatório | Descrição                                                  |
| -------------- | ----------- | ---------------------------------------------------------- |
| `access_key`   | Sim         | Sua chave de acesso única da API.                          |
| `phone_number` | Sim         | Número de telefone para filtrar templates (sem sinal '+'). |

### Resposta

A API retorna um **array** de objetos de template (não encapsulado em um objeto).

**Notas Importantes:**

* A resposta é um **array direto**, não um objeto com uma chave "templates"
* Valores de `status` estão em **MAIÚSCULAS**: `"APPROVED"`, `"PENDING"`, `"REJECTED"`
* Valores de `category` estão em **MAIÚSCULAS**: `"MARKETING"`, `"UTILITY"`, `"AUTHENTICATION"`
* Cada template inclui `parameter_format` (tipicamente `"POSITIONAL"`)
* O array `components` mostra a estrutura do template mas NÃO quais componentes são dinâmicos

***

## 🔍 Obter Componentes do Template

Recupere informações detalhadas sobre os componentes e estrutura de um template específico.

### Endpoint

```
GET https://cloud.lovi.ai/functions/v1/notify/template/components?access_key={YOUR_ACCESS_KEY}&template={TEMPLATE_ID}
```

### Resposta

Este endpoint retorna APENAS os **componentes dinâmicos** que você precisa fornecer ao enviar uma notificação.

```json theme={null}
{
  "status": "OK",
  "components": ["header_image", "body_text_0", "body_text_1"]
}
```

**Notas Importantes:**

* Este endpoint NÃO retorna a estrutura completa do template
* Ele retorna apenas os **nomes** dos componentes que você precisa fornecer ao enviar a notificação
* Footer e botões estáticos NÃO são incluídos (são estáticos no template)
* Nomes de componentes seguem o padrão:
  * Headers: `header_image`, `header_video`, `header_document` (sem número de sufixo)
  * Variáveis do body: `body_text_0`, `body_text_1`, `body_text_N` (com índice)
  * URLs de botões: `buttons_url_0`, `buttons_url_1` (com índice)

***

## 🆕 Criar Novo Template

Crie um novo template de mensagem do WhatsApp para aprovação pelo Meta.

### Endpoint

```
POST https://cloud.lovi.ai/functions/v1/admin/whatsapp/create/template
```

### Parâmetros Obrigatórios

| Parâmetro             | Tipo   | Descrição                                         | Exemplo                    |
| --------------------- | ------ | ------------------------------------------------- | -------------------------- |
| `company_id`          | String | Identificador único da empresa                    | `"uuid-company"`           |
| `waba_id`             | String | ID da Conta Comercial do WhatsApp                 | `"123456789"`              |
| `name_template`       | String | Nome do template (minúsculas, apenas underscores) | `"order_confirmation"`     |
| `language_template`   | String | Código do idioma                                  | `"es_ES"`, `"en_US"`       |
| `category_template`   | String | Categoria do template                             | `"MARKETING"`, `"UTILITY"` |
| `components_template` | Object | Estrutura de componentes do template              | Veja exemplo acima         |

### Categorias de Template

| Categoria        | Descrição                            | Caso de Uso                      |
| ---------------- | ------------------------------------ | -------------------------------- |
| `MARKETING`      | Mensagens promocionais               | Ofertas, anúncios                |
| `UTILITY`        | Mensagens transacionais, funcionais  | Atualizações de pedidos, alertas |
| `AUTHENTICATION` | Mensagens de segurança e verificação | Códigos OTP, confirmações        |

### Processo de Aprovação do Template

1. **Submissão**: Template é enviado ao Meta para revisão
2. **Revisão**: Meta analisa o template (geralmente 24-48 horas)
3. **Aprovação/Rejeição**: Template é aprovado ou rejeitado com feedback
4. **Uso**: Templates aprovados podem ser usados em notificações

### Valores de Status do Template

| Status     | Descrição                        |
| ---------- | -------------------------------- |
| `pending`  | Enviado para revisão             |
| `approved` | Aprovado e pronto para uso       |
| `rejected` | Rejeitado (verifique o feedback) |
| `disabled` | Temporariamente desabilitado     |

***

## 📝 Boas Práticas para Templates

### Convenções de Nomenclatura

* Use apenas letras minúsculas
* Use underscores para espaços
* Seja descritivo: `welcome_new_user` vs `template1`
* Inclua idioma se houver múltiplos: `welcome_es`, `welcome_en`

### Diretrizes de Conteúdo

* **Seja Claro**: Templates devem ser facilmente compreendidos
* **Variáveis**: Use placeholders numerados `{1}`, `{2}`, `{3}` (WhatsApp usa variáveis posicionais)
* **Conformidade**: Siga as políticas comerciais do WhatsApp
* **Teste**: Teste com dados reais antes da submissão

### Motivos Comuns de Rejeição

* ❌ Saudações genéricas ("Olá", "Oi")
* ❌ Linguagem promocional em templates UTILITY
* ❌ Contexto ausente ou propósito não claro
* ❌ Uso incorreto de variáveis
* ❌ Violações de política (spam, conteúdo inapropriado)

### Dicas de Aprovação

* ✅ Inclua contexto comercial específico
* ✅ Use linguagem clara e profissional
* ✅ Forneça exemplos significativos
* ✅ Siga as diretrizes de templates do WhatsApp
* ✅ Teste substituição de variáveis completamente

***

## 🔧 Dicas de Desenvolvimento

* Cache informações de templates para reduzir chamadas de API
* Monitore mudanças de status dos templates
* Tenha templates de fallback para os rejeitados
* Use nomenclatura consistente em toda sua organização
* Documente templates para referência da equipe