> ## 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.

# Quick Start

> Crie um template multicanal e dispare SMS e e-mail numa chamada, com nota sobre WhatsApp oficial.

<Tip>
  Do **zero ao primeiro disparo na fila**: crie o template, ligue os canais que precisa e chame **`POST /v1/templates/send`**. Gestão (`templates:*`) e envio (escopos por canal) são **famílias diferentes** de permissão.
</Tip>

## Em poucas palavras

* Um template **não precisa** ter os sete canais, ligue só os que for usar.
* No envio, **`channels`** deve ser **subconjunto** dos canais habilitados no template.
* Resposta **202** = enfileirado. Entrega → webhooks de **cada canal**. Aprovação Meta → webhooks **`template.*`**.

Contexto: [Introdução](/template-api/como-funciona/introducao). Escopos: [Escopos da API Key](/template-api/como-funciona/escopos-da-api-key). WhatsApp oficial: [Templates oficiais Meta](/template-api/como-funciona/templates-oficiais-meta).

## Antes de começar

* **Gestão:** `templates:create` (criar), `templates:read` (listar)
* **Envio:** escopo de **cada** canal usado (`sms:send`, `email:send`, `whatsapp:send`, …)
* **WhatsApp:** instância ativa. **E-mail:** domínio verificado. **Push:** app. **Voz:** número ACTIVE
* Auth: `Authorization: Bearer sk_live_...` ou `x-api-key`
* Base URL: `https://api.notifique.dev`

***

## 1. Criar template

#### 1A, Pelo painel

1. Templates → **Novo template**
2. Ligue os canais (SMS, e-mail, WhatsApp, …)
3. Escreva o conteúdo com `{{variáveis}}` e salve

Para **WhatsApp oficial**: após criar, use **Sincronizar** ou **Publicar na Meta** na instância oficial, [guia completo](/template-api/como-funciona/templates-oficiais-meta).

#### 1B, Pela API

Escopo: **`templates:create`**.

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

```json theme={null}
{
  "name": "alerta_pedido",
  "category": "TRANSACTIONAL",
  "language": "pt_BR",
  "sms": {
    "enabled": true,
    "payload": { "content": "Pedido {{codigo}} despachado." }
  },
  "email": {
    "enabled": true,
    "payload": {
      "subject": "Pedido {{codigo}}",
      "html": "<p>Olá {{name}}, seu pedido saiu.</p>"
    }
  },
  "whatsapp": { "enabled": false, "payload": {} },
  "telegram": { "enabled": false, "payload": {} },
  "rcs": { "enabled": false, "payload": {} },
  "push": { "enabled": false, "payload": {} },
  "voice": { "enabled": false, "payload": {} }
}
```

Resposta esperada: **200** com `enabledChannels` (ex.: `["email","sms"]`).

<Note>
  Canal com **`enabled: false`** usa **`payload: {}`**. Pedir canal desabilitado no envio → **400** (`TEMPLATE_CHANNEL_NOT_ENABLED`).
</Note>

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

***

## 2. Enviar por template

Escopos neste exemplo: **`sms:send`**, **`email:send`**.

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

```json theme={null}
{
  "template": "alerta_pedido",
  "channels": ["sms", "email"],
  "to": ["5511999999999", "cliente@email.com"],
  "variables": {
    "codigo": "12345",
    "name": "Maria"
  },
  "from": "ola@meudominio.com.br",
  "fromName": "Equipe Notifique"
}
```

Resposta esperada: **202**

```json theme={null}
{
  "success": true,
  "data": {
    "smsIds": ["clsms1..."],
    "emailIds": ["clemail1..."],
    "status": "QUEUED",
    "count": 2
  }
}
```

Só aparecem IDs dos canais que **geraram** envio. Campos por canal: `messageIds` (WhatsApp), `smsIds`, `emailIds`, `telegramIds`, `rcsIds`, `pushIds`, `voiceCallIds`.

### WhatsApp no mesmo template

Inclua `whatsapp` em `channels` e informe `instanceId` (se não houver padrão no workspace):

```json theme={null}
{
  "template": "alerta_pedido",
  "channels": ["whatsapp", "sms"],
  "to": ["5511999999999"],
  "variables": { "codigo": "12345", "name": "Maria" },
  "instanceId": "cuid_instancia_whatsapp"
}
```

**Linha oficial:** o template precisa estar **vinculado/aprovado na Meta** (`WHATSAPP_OFFICIAL`, status `APPROVED`). Veja [Templates oficiais Meta](/template-api/como-funciona/templates-oficiais-meta).

### Push e Voz

* **Push:** `channels: ["push"]` + `push.pushAppId` + device IDs em `to`
* **Voz:** `channels: ["voice"]` + `voice.from` + números com `+` em `to`

***

## 3. Campos principais do envio

| Campo               | Obrigatório          | Descrição                          |
| ------------------- | -------------------- | ---------------------------------- |
| `template`          | Sim                  | ID ou **nome** do template         |
| `channels`          | Sim                  | Canais **habilitados no template** |
| `to`                | Sim                  | Até **100** destinatários          |
| `variables`         | Conforme template    | Valores para `{{chave}}`           |
| `instanceId`        | Se WA sem padrão     | Instância WhatsApp                 |
| `from` / `fromName` | Se e-mail sem padrão | Remetente verificado               |
| `push.pushAppId`    | Se `push`            | App de push                        |
| `voice.from`        | Se `voice`           | Número de origem                   |
| `schedule.sendAt`   | Não                  | Agenda (ISO 8601)                  |

***

## 4. Acompanhar resultado

| O que                              | Onde                                                                                               |
| ---------------------------------- | -------------------------------------------------------------------------------------------------- |
| Entrega SMS, e-mail, WhatsApp…     | Webhooks do **canal** (`sms.delivered`, `message.sent`, …)                                         |
| Meta **aprovou/rejeitou** template | Webhooks **`template.*`**, [Eventos dos webhooks](/template-api/como-funciona/eventos-do-webhooks) |
| Erros de validação / Meta          | [Respostas de erro](/guides/conceitos/resposta-de-erros)                                           |

***

## Erros comuns

| HTTP    | Significado                                                         |
| ------- | ------------------------------------------------------------------- |
| **400** | Canal não habilitado, variável faltando, template Meta não aprovado |
| **403** | Escopo ausente ou créditos insuficientes                            |
| **404** | Template, instância ou app não encontrado                           |

***

## Próximos passos

* [Templates oficiais Meta](/template-api/como-funciona/templates-oficiais-meta): sync e aprovação
* [Variáveis e CRUD](/template-api/como-funciona/variaveis-disponiveis-e-crud): merge e edição
* [Escopos](/template-api/como-funciona/escopos-da-api-key): permissões
* [Eventos dos webhooks](/template-api/como-funciona/eventos-do-webhooks): `template.*`