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

# Templates oficiais Meta

> Sincronize templates da Meta com o Notifique, vincule canais e envie na linha oficial do WhatsApp.

<Tip>
  Template oficial é uma **carta-modelo aprovada pela Meta**. No Notifique ele convive com SMS, e-mail e outros canais no **mesmo** template, sem duplicar por canal.
</Tip>

## Em poucas palavras

* Na **linha oficial**, fora da janela de 24h, só entra mensagem com template **aprovado** pela Meta.
* Existem templates **internos** (`ZENVIO`) e **oficiais** (`WHATSAPP_OFFICIAL`) espelhados na WABA.
* Você pode **trazer da Meta**, **vincular** a um interno existente ou **publicar** um interno na Meta e aguardar aprovação.
* A Meta avisa mudanças de status; o Notifique propaga via webhooks **`template.*`**.

Instância oficial: [Quick Start WhatsApp](/whatsapp-api/como-funciona/quick-start) (aba **Conexão oficial**). Visão geral: [Introdução Templates](/template-api/como-funciona/introducao).

***

## Por que isso importa?

Na linha **oficial**, a Meta divide a conversa em dois momentos:

| Situação                                | O que enviar          |
| --------------------------------------- | --------------------- |
| Cliente **respondeu** há menos de 24h   | Texto ou mídia livre  |
| **Primeiro contato** ou conversa parada | Template **aprovado** |

Na linha **não oficial**, use templates internos ou texto livre. Detalhes: [Modos de conexão](/whatsapp-api/como-funciona/modos-de-conexao).

***

## Interno × oficial no Notifique

O template do Notifique é uma **pasta** com um bloco por canal.

|             | **Interno**           | **Oficial (Meta)**                               |
| ----------- | --------------------- | ------------------------------------------------ |
| `source`    | `ZENVIO` (ou null)    | `WHATSAPP_OFFICIAL`                              |
| Uso típico  | Linha **não oficial** | Linha **oficial**                                |
| Aprovação   | Imediata no Notifique | Meta: `PENDING` → `APPROVED`                     |
| Campos Meta | ,                     | `metaId`, `metaName`, `metaWabaId`, `components` |

<Info>
  O **nome interno** (`alerta_pedido`) pode diferir do **`metaName`** na Meta (`order_update`). No envio oficial, a Meta valida o modelo **aprovado** no catálogo dela.
</Info>

***

## Um template, vários canais

Exemplo: você já tem `confirmacao_pedido` com SMS e e-mail. Na linha oficial, **vincula** o WhatsApp a um modelo aprovado na Meta.

* SMS e e-mail **não mudam**
* O bloco WhatsApp passa a usar a estrutura **oficial** aprovada
* Um único `POST /v1/templates/send` dispara todos os canais habilitados

Variáveis e CRUD: [Variáveis e CRUD](/template-api/como-funciona/variaveis-disponiveis-e-crud).

***

## Sincronização: três caminhos

Requer instância **oficial ativa**. No painel: instância → **Sincronizar templates com a Meta**.

<AccordionGroup>
  <Accordion title="A, Trazer da Meta (sincronizar)">
    Use quando os templates **já existem** na conta Business.

    1. Clique em **Sincronizar templates com a Meta**
    2. O painel lista o catálogo da Meta e os templates locais
    3. Para cada modelo da Meta, escolha **Vincular** a um interno ou **Criar novo**
    4. Confirme a sincronização

    **Efeito do vínculo:** o template local vira oficial no WhatsApp, guarda `metaId`, `metaName` e `components`, e **mantém** SMS/e-mail/outros canais.

    <Note>
      Se já existir interno com mesmo nome/idioma, o sync **não sobrescreve** sozinho, escolha o vínculo no diálogo.
    </Note>
  </Accordion>

  <Accordion title="B, Ligar um interno a um da Meta">
    Fluxo mais comum quando você **já tem** templates no Notifique.

    1. Rode a sincronização (caminho **A**)
    2. No mapeamento, associe cada modelo Meta ao template interno certo
    3. Salve

    O nome interno permanece. O envio WhatsApp oficial usa o conteúdo **aprovado na Meta**. Sincronizar em qualquer número oficial da mesma WABA atualiza o catálogo do workspace.
  </Accordion>

  <Accordion title="C, Publicar um interno na Meta (enviar para aprovação)">
    Use quando o modelo **nasce no Notifique** e ainda **não existe** na Meta.

    1. Crie ou edite o template (estrutura oficial: cabeçalho, corpo, botões…)
    2. Na instância oficial: **Enviar para a Meta** / **Publicar na Meta**
    3. A Meta recebe com status **PENDING**
    4. Quando aprovar → **APPROVED**, você pode enviar

    <Warning>
      Template **APPROVED**: até **1 edição a cada 24h** e **10 em 30 dias** na Meta. Se o push automático falhar, use **Atualizar na Meta…** no editor.
    </Warning>
  </Accordion>
</AccordionGroup>

***

## Aprovação, status e webhooks

Acompanhe no painel ou automatize com webhooks:

| Status                                | Significado                          |
| ------------------------------------- | ------------------------------------ |
| `PENDING`                             | Meta analisando                      |
| `APPROVED`                            | Pode enviar na linha oficial         |
| `REJECTED`                            | Recusado, ajuste e publique de novo  |
| `PAUSED`                              | Pausado por qualidade                |
| `IN_APPEAL`, `DISABLED`, `DELETED`, … | Ver evento `template.status_changed` |

| Evento webhook              | Quando dispara                                |
| --------------------------- | --------------------------------------------- |
| `template.submitted`        | Template enviado/publicado na Meta            |
| `template.status_changed`   | Status local muda (`APPROVED`, `REJECTED`, …) |
| `template.category_changed` | Categoria muda (ex.: MARKETING ↔ UTILITY)     |

Guia com payloads: [Eventos dos webhooks](/template-api/como-funciona/eventos-do-webhooks).

Para **entrega** da mensagem (enviado, entregue, lido, falha), use [webhooks do WhatsApp](/whatsapp-api/como-funciona/eventos-do-webhooks), são eventos **`message.*`**, não `template.*`.

***

## Enviar um template oficial

**Pré-requisitos:**

1. Instância oficial **ativa** e pagamento Meta ok
2. Template com status **APPROVED** e `source: WHATSAPP_OFFICIAL`
3. `metaName` preenchido (rode sync/vínculo se vazio)

**Multicanal** (WhatsApp + SMS no mesmo disparo):

```http theme={null}
POST /v1/templates/send
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx
```

```json theme={null}
{
  "template": "confirmacao_pedido",
  "channels": ["whatsapp", "sms"],
  "to": ["5511999999999"],
  "variables": { "codigo": "482910", "name": "Maria" },
  "instanceId": "ID_DA_INSTANCIA_OFICIAL"
}
```

Resposta esperada: **202**

```json theme={null}
{
  "success": true,
  "data": {
    "messageIds": ["clxx789..."],
    "smsIds": ["clxx790..."],
    "status": "QUEUED",
    "count": 2
  }
}
```

<Note>
  Com **`sk_test_`**, gates da Meta **não** rodam, envio simulado no [Sandbox](/guides/sandbox/index). Aprovação real e cobrança de conversa só em **`sk_live_`**.
</Note>

***

## Qual instância aceita qual template?

| Instância       | Templates no WhatsApp                       |
| --------------- | ------------------------------------------- |
| **Oficial**     | Oficiais (`WHATSAPP_OFFICIAL`) **APPROVED** |
| **Não oficial** | Internos (`ZENVIO`), texto/imagem simples   |

Botões, cabeçalho ou carrossel Meta **não funcionam** na linha não oficial.

***

## Erros comuns

| Código                                      | O que significa                           | O que fazer                                |
| ------------------------------------------- | ----------------------------------------- | ------------------------------------------ |
| `META_TEMPLATE_REQUIRED`                    | Fora da janela 24h sem template           | Envie template aprovado ou espere resposta |
| `META_TEMPLATE_NOT_FOUND`                   | Nome/idioma não bate com a Meta           | Sync/vínculo; confira `metaName`           |
| `TEMPLATE_NOT_ALLOWED_FOR_INSTANCE`         | Template de um modo na instância do outro | Oficial na oficial; interno na não oficial |
| `META_PAYMENT_METHOD_REQUIRED`              | Sem cartão na conta Meta                  | Cadastre pagamento no WhatsApp Manager     |
| `META_TOKEN_EXPIRED` / `META_TOKEN_INVALID` | Linha oficial desconectada                | Reconecte a instância                      |

Catálogo: [Respostas de erro](/guides/conceitos/resposta-de-erros) (accordion **Meta Cloud / templates oficiais**).

***

## Próximos passos

* [Quick Start](/template-api/como-funciona/quick-start): criar e disparar multicanal
* [Eventos dos webhooks](/template-api/como-funciona/eventos-do-webhooks): `template.*`
* [Modos de conexão](/whatsapp-api/como-funciona/modos-de-conexao): oficial × não oficial
* [Eventos WhatsApp](/whatsapp-api/como-funciona/eventos-do-webhooks): entrega `message.*`