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

# Campanhas no painel

> Template, canais, audiência, agendamento, Run e estatísticas: mesmo fluxo de fila e créditos da API.

<Tip>
  **Campanha** = **o quê** (template) + **por onde** (canais) + **para quem** (segmento ou IDs). O **Run** enfileira, não é um motor separado da API de envio.
</Tip>

## O que é uma campanha?

É o **disparo em lote** para uma audiência usando um **template** multicanal. O painel e a API compartilham o mesmo fluxo de fila, créditos e status.

Analogia: **template** é o texto do correio. **Segmento** é a lista de endereços. **Campanha** é carimbar e soltar na caixa.

## Campanha × segmento × envio direto

|                    | **Campanha**                             | **Segmento**                    | **Envio API direto**                       |
| ------------------ | ---------------------------------------- | ------------------------------- | ------------------------------------------ |
| Para quê           | Disparo **em lote** agendado ou imediato | Define **público** reutilizável | Um ou poucos destinos pontuais             |
| Precisa de         | Template + canais + audiência            | Só regras JSON                  | Rota do canal ou `POST /v1/templates/send` |
| Automação contínua | Não (use **Automações**)                 | Não                             | Pode ser script                            |

## Quando usar?

Funciona muito bem para **newsletter**, **promoção para público filtrado** e **teste com poucos IDs** antes da base inteira. Para **um aviso único** por script, use envio direto na API do canal ou template.

## Canais na campanha

`channels` aceita: **`whatsapp`**, **`sms`**, **`email`**, **`telegram`**.

Cada canal listado precisa estar **habilitado no template**. Templates podem ter RCS, Push ou Voz, campanha usa só o subconjunto dos quatro acima.

| Canal    | Contato precisa de                  | Config extra                      |
| -------- | ----------------------------------- | --------------------------------- |
| WhatsApp | **Telefone**                        | `instanceId` ou Sending Pool      |
| SMS      | **Telefone**                        | ,                                 |
| E-mail   | **E-mail**                          | `fromEmail` ou domínio verificado |
| Telegram | Peer na instância (`telegramLinks`) | `telegramInstanceId`              |

Sem telefone, e-mail ou peer, o contato **é ignorado naquele canal** (sem erro por pessoa).

<Info>
  **Marketing:** contato precisa `receiveMarketing` **e** inscrição no **tópico** do template (quando vinculado). Quem não passa não entra na fila.
</Info>

## Como funciona na prática

1. **Template** com canais ativos e texto preenchido
2. **New campaign**, nome, template, canais desta execução, audiência (segmento ou IDs)
3. Roteamento: WhatsApp, Telegram, e-mail conforme tabela acima
4. Opcional: **agendar** (`scheduledFor`, mín. \~2 min à frente) → **SCHEDULED**
5. **Preview** do segmento (se usar segmento)
6. **Run** ou disparo no horário → **RUNNING** → **COMPLETED** ou **FAILED**

### Status

| Status      | Significado                    |
| ----------- | ------------------------------ |
| `DRAFT`     | Rascunho                       |
| `SCHEDULED` | Agendada                       |
| `RUNNING`   | Enfileirando / executando      |
| `COMPLETED` | Última execução ok             |
| `FAILED`    | Última execução falhou         |
| `CANCELLED` | Cancelada (só DRAFT/SCHEDULED) |

## Variáveis globais (opcional)

JSON mesclado **por cima** dos dados do contato, cupom igual para todos:

```json theme={null}
{
  "discount": "10",
  "campaign_name": "abril_2026"
}
```

## Na API

| Ação                  | Escopo típico      |
| --------------------- | ------------------ |
| Criar / agendar       | `campaigns:create` |
| Disparar agora        | `campaigns:run`    |
| Cancelar              | `campaigns:update` |
| Stats e destinatários | `campaigns:read`   |

O **Run** devolve `sent` e `runId`. Links curtos recebem `utm_campaign` e `utm_content` automaticamente.

## Checklist antes do Run

1. Canais da campanha **ativos no template**?
2. **Preview** do segmento faz sentido?
3. Telegram: peers na instância certa?
4. Testou com **poucos IDs**?
5. **Créditos**, instâncias e remetente de e-mail OK?

Códigos comuns: `CAMPAIGN_CHANNEL_NOT_IN_TEMPLATE`, `CAMPAIGN_AUDIENCE_TOO_LARGE`, `CAMPAIGN_WHATSAPP_INSTANCE_REQUIRED`. Veja [Respostas de erro](/guides/conceitos/resposta-de-erros).

## Próximos passos

* [Quick Start](/contacts-api/como-funciona/quick-start)
* [Segmentos](/contacts-api/como-funciona/segmentos-na-audiencia)
* [Templates](/template-api/como-funciona/quick-start)
* [Sending Pools](/whatsapp-api/como-funciona/sending-pools)